Merge branch 'master' into rcv-services

* agent: use primary key index in setRcvServiceAssocs

Previous WHERE rcv_id = ? did not match the (host, port, rcv_id)
primary key prefix and fell back to a table scan via
idx_rcv_queues_client_notice_id. With ~390k rows per queue, each
update in a 1350-row batch scanned the whole table, yielding ~290s
per batch and a multi-hour rcv-services migration.

* agent: pass SMPServer explicitly to setRcvServiceAssocs

Avoid extracting host/port from the first queue inside setRcvServiceAssocs.
The caller already has SMPServer in scope (from tSess) and the call chain
is short, so threading it through is simpler than inspecting the list.
Removes the empty-list guard from setRcvServiceAssocs (it remains in
processRcvServiceAssocs).

.github/actions/swap/action.yml

@@ -0,0 +1,44 @@
+name: 'Set Swap Space'
+description: 'Add moar swap'
+branding:
+  icon: 'crop'
+  color: 'orange'
+inputs:
+  swap-size-gb:
+    description: 'Swap space to create, in Gigabytes.'
+    required: false
+    default: '10'
+runs:
+  using: "composite"
+  steps:
+    - name: Swap space report before modification
+      shell: bash
+      run: |
+        echo "Memory and swap:"
+        free -h
+        echo
+        swapon --show
+        echo
+    - name: Set Swap
+      shell: bash
+      run: |
+          export SWAP_FILE=$(swapon --show=NAME | tail -n 1)
+          echo "Swap file: $SWAP_FILE"
+          if [ -z "$SWAP_FILE" ]; then
+            SWAP_FILE=/opt/swapfile
+          else
+            sudo swapoff $SWAP_FILE
+            sudo rm $SWAP_FILE
+          fi
+          sudo fallocate -l ${{ inputs.swap-size-gb }}G $SWAP_FILE
+          sudo chmod 600 $SWAP_FILE
+          sudo mkswap $SWAP_FILE
+          sudo swapon $SWAP_FILE
+    - name: Swap space report after modification
+      shell: bash
+      run: |
+        echo "Memory and swap:"
+        free -h
+        echo
+        swapon --show
+        echo

.github/workflows/build.yml

@@ -10,62 +10,25 @@ on:
   pull_request:
 
 jobs:
-  build:
-    name: build-${{ matrix.os }}-${{ matrix.ghc }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-20.04
-            platform_name: 20_04-x86-64
-            ghc: "8.10.7"
-          - os: ubuntu-20.04
-            platform_name: 20_04-x86-64
-            ghc: "9.6.3"
-          - os: ubuntu-22.04
-            platform_name: 22_04-x86-64
-            ghc: "9.6.3"
+
+# =============================
+#       Create release
+# =============================
+
+# Create release, but only if it's triggered by tag push.
+# On pull requests/commits push, this job will always complete.
+
+  maybe-release:
+    runs-on: ubuntu-latest
     steps:
       - name: Clone project
+        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/checkout@v3
 
-      - name: Setup Haskell
-        uses: haskell-actions/setup@v2
-        with:
-          ghc-version: ${{ matrix.ghc }}
-          cabal-version: "3.10.1.0"
-
-      - name: Cache dependencies
-        uses: actions/cache@v2
-        with:
-          path: |
-            ~/.cabal/store
-            dist-newstyle
-          key: ${{ matrix.os }}-${{ hashFiles('cabal.project', 'simplexmq.cabal') }}
-
-      - name: Build
-        shell: bash
-        run: cabal build --enable-tests
-
-      - name: Test
-        timeout-minutes: 40
-        shell: bash
-        run: cabal test --test-show-details=direct
-
-      - name: Prepare binaries
-        if: startsWith(github.ref, 'refs/tags/v')
-        shell: bash
-        run: |
-          mv $(cabal list-bin smp-server) smp-server-ubuntu-${{ matrix.platform_name}}
-          mv $(cabal list-bin ntf-server) ntf-server-ubuntu-${{ matrix.platform_name}}
-          mv $(cabal list-bin xftp-server) xftp-server-ubuntu-${{ matrix.platform_name}}
-          mv $(cabal list-bin xftp) xftp-ubuntu-${{ matrix.platform_name}}
-
       - name: Build changelog
-        if: startsWith(github.ref, 'refs/tags/v') && matrix.os == 'ubuntu-22.04'
         id: build_changelog
-        uses: mikepenz/release-changelog-builder-action@v1
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: simplex-chat/release-changelog-builder-action@v5
         with:
           configuration: .github/changelog_conf.json
           failOnError: true
@@ -75,8 +38,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Create release
-        if: startsWith(github.ref, 'refs/tags/v') && matrix.ghc != '8.10.7'
-        uses: softprops/action-gh-release@v1
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: simplex-chat/action-gh-release@v2
         with:
           body: |
             See full changelog [here](https://github.com/simplex-chat/simplexmq/blob/master/CHANGELOG.md).
@@ -86,10 +49,251 @@ jobs:
           prerelease: true
           files: |
             LICENSE
-            smp-server-ubuntu-${{ matrix.platform_name}}
-            ntf-server-ubuntu-${{ matrix.platform_name}}
-            xftp-server-ubuntu-${{ matrix.platform_name}}
-            xftp-ubuntu-${{ matrix.platform_name}}
           fail_on_unmatched_files: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+# =============================
+#        Main build job
+# =============================
+
+  build:
+    name: "ubuntu-${{ matrix.os }}-${{ matrix.arch }}, GHC: ${{ matrix.ghc }}"
+    needs: maybe-release
+    env:
+      apps: "smp-server xftp-server ntf-server xftp"
+    runs-on: ${{ matrix.runner }}
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_HOST_AUTH_METHOD: trust # Allows passwordless access
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          # Maps tcp port 5432 on service container to the host
+          - 5432:5432
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: 22.04
+            os_underscore: 22_04
+            arch: x86-64
+            runner: "ubuntu-22.04"
+            ghc: "8.10.7"
+            should_run: ${{ !(github.ref == 'refs/heads/stable' || startsWith(github.ref, 'refs/tags/v')) }}
+          - os: 22.04
+            os_underscore: 22_04
+            arch: x86-64
+            runner: "ubuntu-22.04"
+            ghc: "9.6.3"
+            should_run: true
+          - os: 24.04
+            os_underscore: 24_04
+            arch: x86-64
+            runner: "ubuntu-24.04"
+            ghc: "9.6.3"
+            should_run: true
+          - os: 22.04
+            os_underscore: 22_04
+            arch: aarch64
+            runner: "ubuntu-22.04-arm"
+            ghc: "9.6.3"
+            should_run: true
+          - os: 24.04
+            os_underscore: 24_04
+            arch: aarch64
+            runner: "ubuntu-24.04-arm"
+            ghc: "9.6.3"
+            should_run: true
+    steps:
+      - name: Clone project
+        if: matrix.should_run == true
+        uses: actions/checkout@v3
+
+      - name: Set up Docker Buildx
+        if: matrix.should_run == true
+        uses: simplex-chat/docker-setup-buildx-action@v3
+
+      - name: Setup swap
+        if: matrix.ghc == '8.10.7' && matrix.should_run == true
+        uses: ./.github/actions/swap
+        with:
+          swap-size-gb: 20
+
+      - name: Install PostgreSQL 15 client tools
+        if: matrix.os == '22.04' && matrix.should_run == true
+        shell: bash
+        run: |
+          # Import the repository signing key
+          sudo install -d /usr/share/postgresql-common/pgdg
+          sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
+          # Add the PostgreSQL APT repository
+          sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+          # Update repository and install postgresql tools
+          sudo apt update
+          sudo apt -y install postgresql-client-15
+
+      - name: Build and cache Docker image
+        if: matrix.should_run == true
+        uses: simplex-chat/docker-build-push-action@v6
+        with:
+          context: .
+          load: true
+          file: Dockerfile.build
+          tags: build/${{ matrix.os }}:latest
+          build-args: |
+            TAG=${{ matrix.os }}
+            GHC=${{ matrix.ghc }}
+
+      - name: Cache dependencies
+        if: matrix.should_run == true
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cabal/store
+            dist-newstyle
+          key: ubuntu-${{ matrix.os }}-${{ matrix.arch }}-ghc${{ matrix.ghc }}-${{ hashFiles('cabal.project', 'simplexmq.cabal') }}
+
+      - name: Start container
+        if: matrix.should_run == true
+        shell: bash
+        run: |
+          docker run -t -d \
+            --device /dev/fuse \
+            --cap-add SYS_ADMIN \
+            --security-opt apparmor:unconfined \
+            --name builder \
+            -v ~/.cabal:/root/.cabal \
+            -v /home/runner/work/_temp:/home/runner/work/_temp \
+            -v ${{ github.workspace }}:/project \
+            build/${{ matrix.os }}:latest
+
+      - name: Build smp-server, xftp-server (postgresql) and tests
+        if: matrix.should_run == true
+        shell: docker exec -t builder sh -eu {0}
+        run: |
+          chmod -fR 777 ~/.cabal ./dist-newstyle || :; git config --global --add safe.directory '*'
+          cabal clean
+          cabal update
+          cabal build --jobs=$(nproc) --enable-tests -fserver_postgres
+          mkdir -p /out
+          for i in smp-server xftp-server simplexmq-test; do
+            bin=$(find /project/dist-newstyle -name "$i" -type f -executable)
+            chmod +x "$bin"
+            mv "$bin" /out/
+          done
+          strip /out/smp-server /out/xftp-server
+
+      - name: Copy simplexmq-test from container
+        if: matrix.should_run == true
+        shell: bash
+        run: |
+          docker cp builder:/out/simplexmq-test .
+
+      - name: Copy smp-server, xftp-server (postgresql) from container and prepare it
+        if: startsWith(github.ref, 'refs/tags/v') && matrix.should_run == true
+        id: prepare-postgres
+        shell: bash
+        run: |
+          printf 'bins<<EOF\n' > bins.output
+          printf 'hashes<<EOF\n' > hashes.output
+
+          for i in smp-server xftp-server; do
+            name="${i}-postgres-ubuntu-${{ matrix.os_underscore }}-${{ matrix.arch }}"
+            docker cp builder:/out/$i $name
+
+            path="${{ github.workspace }}/$name"
+            hash="SHA2-256($name)= $(openssl sha256 $path | cut -d' ' -f 2)"
+
+            printf '%s\n' "$path" >> bins.output
+            printf '%s\n\n' "$hash" >> hashes.output
+          done
+          printf 'EOF\n' >> bins.output
+          printf 'EOF\n' >> hashes.output
+
+          cat bins.output >> "$GITHUB_OUTPUT"
+          cat hashes.output >> "$GITHUB_OUTPUT"
+
+      - name: Build everything else (standard)
+        if: matrix.should_run == true
+        shell: docker exec -t builder sh -eu {0}
+        run: |
+          cabal build --jobs=$(nproc)
+          mkdir -p /out
+          for i in ${{ env.apps }}; do
+            bin=$(find /project/dist-newstyle -name "$i" -type f -executable)
+            strip "$bin"
+            chmod +x "$bin"
+            mv "$bin" /out/
+          done
+
+      - name: Copy binaries from container and prepare them
+        id: prepare-regular
+        if: startsWith(github.ref, 'refs/tags/v') && matrix.should_run == true
+        shell: bash
+        run: |
+          docker cp builder:/out .
+
+          printf 'bins<<EOF\n' > bins.output
+          printf 'hashes<<EOF\n' > hashes.output
+          for i in ${{ env.apps }}; do
+            name="$i-ubuntu-${{ matrix.os_underscore }}-${{ matrix.arch }}"
+
+            mv ./out/$i ./$name
+
+            path="${{ github.workspace }}/$name"
+            hash="SHA2-256($name)= $(openssl sha256 $path | cut -d' ' -f 2)"
+
+            printf '%s\n' "$path" >> bins.output
+            printf '%s\n\n' "$hash" >> hashes.output
+          done
+          printf 'EOF\n' >> bins.output
+          printf 'EOF\n' >> hashes.output
+
+          cat bins.output >> "$GITHUB_OUTPUT"
+          cat hashes.output >> "$GITHUB_OUTPUT"
+
+      - name: Upload binaries
+        if: startsWith(github.ref, 'refs/tags/v') && matrix.should_run == true
+        uses: simplex-chat/action-gh-release@v2
+        with:
+          append_body: true
+          prerelease: true
+          fail_on_unmatched_files: true
+          body: |
+            ${{ steps.prepare-regular.outputs.hashes }}
+            ${{ steps.prepare-postgres.outputs.hashes }}
+          files: |
+            ${{ steps.prepare-regular.outputs.bins }}
+            ${{ steps.prepare-postgres.outputs.bins }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test
+        if: matrix.should_run == true && matrix.arch == 'x86-64'
+        timeout-minutes: 120
+        shell: bash
+        env:
+          PGHOST: localhost
+        run: |
+          i=1
+          attempts=1
+          ${{ (github.ref == 'refs/heads/stable' || startsWith(github.ref, 'refs/tags/v')) }} && attempts=3
+          while [ "$i" -le "$attempts" ]; do
+            if ./simplexmq-test; then
+              break
+            else
+              echo "Attempt $i failed, retrying..."
+              i=$((i + 1))
+              sleep 1
+            fi
+          done
+          if [ "$i" -gt "$attempts" ]; then
+            echo "All "$attempts" attempts failed."
+            exit 1
+          fi

.github/workflows/docker-image.yml

@@ -14,22 +14,22 @@ jobs:
       matrix:
         include:
           - app: smp-server
-            app_port: 5223
+            app_port: "443 5223"
           - app: xftp-server
-            app_port: 443 
+            app_port: 443
     steps:
       - name: Clone project
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Log in to Docker Hub
-        uses: docker/login-action@v2
+        uses: simplex-chat/docker-login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
       - name: Extract metadata for Docker image
         id: meta
-        uses: docker/metadata-action@v4
+        uses: simplex-chat/docker-metadata-action@v5
         with:
           images: ${{ secrets.DOCKERHUB_USERNAME }}/${{ matrix.app }}
           flavor: |
@@ -39,9 +39,17 @@ jobs:
             type=semver,pattern=v{{major}}.{{minor}}
             type=semver,pattern=v{{major}}
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
       - name: Build and push Docker image
-        uses: docker/build-push-action@v4
+        uses: simplex-chat/docker-build-push-action@v6
         with:
+          context: .
+          platforms: linux/amd64,linux/arm64
           push: true
           build-args: |
             APP=${{ matrix.app }}

.github/workflows/reproduce-schedule.yml

@@ -0,0 +1,45 @@
+name: Reproduce latest release
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 2 * * *' # every day at 02:00 night
+
+jobs:
+  reproduce:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Get latest release
+        shell: bash
+        run: |
+          curl --proto '=https' \
+               --tlsv1.2 \
+               -sSf -L \
+               'https://api.github.com/repos/simplex-chat/simplexmq/releases/latest' \
+               2>/dev/null | \
+          grep -i "tag_name" | \
+          awk -F \" '{print "TAG="$4}' >> $GITHUB_ENV
+
+      - name: Execute reproduce script
+        run: |
+          ${GITHUB_WORKSPACE}/scripts/simplexmq-reproduce-builds.sh "$TAG" || :
+
+      - name: Check if build has been reproduced
+        env:
+          url: ${{ secrets.STATUS_SIMPLEX_WEBHOOK_URL }}
+          user: ${{ secrets.STATUS_SIMPLEX_WEBHOOK_USER }}
+          pass: ${{ secrets.STATUS_SIMPLEX_WEBHOOK_PASS }}
+        run: |
+          if [ -f "${GITHUB_WORKSPACE}/${TAG}-simplexmq/_sha256sums" ]; then
+            exit 0
+          else
+            curl --proto '=https' --tlsv1.2 -sSf \
+              -u "${user}:${pass}" \
+              -H 'Content-Type: application/json' \
+              -d '{"title": "👾 GitHub: Runner", "description": "⛔️ '"$TAG"' did not reproduce."}' \
+              "$url"
+            exit 1
+          fi

.gitignore

@@ -11,3 +11,4 @@ cabal.project.local~
 .hpc/
 *.tix
 .coverage
+

2026-02-04-xftp-web-persistent-connections.md

@@ -0,0 +1,53 @@
+# XFTPClientAgent Pattern
+
+## TOC
+1. Executive Summary
+2. Changes: client.ts
+3. Changes: agent.ts
+4. Changes: test/browser.test.ts
+5. Verification
+
+## Executive Summary
+
+Add `XFTPClientAgent` — a per-server connection pool matching the Haskell pattern. The agent caches `XFTPClient` instances by server URL. All orchestration functions (`uploadFile`, `downloadFile`, `deleteFile`) take `agent` as first parameter and use `getXFTPServerClient(agent, server)` instead of calling `connectXFTP` directly. Connections stay open on success; the caller creates and closes the agent.
+
+`connectXFTP` and `closeXFTP` stay exported (used by `XFTPWebTests.hs` Haskell tests). The `browserClients` hack, per-function `connections: Map`, and `getOrConnect` are deleted.
+
+## Changes: client.ts
+
+**Add** after types section: `XFTPClientAgent` interface, `newXFTPAgent`, `getXFTPServerClient`, `closeXFTPServerClient`, `closeXFTPAgent`.
+
+**Delete**: `browserClients` Map and all `isNode` browser-cache checks in `connectXFTP` and `closeXFTP`.
+
+**Revert `closeXFTP`** to unconditional `c.transport.close()` (browser transport.close() is already a no-op).
+
+`connectXFTP` stays exported (backward compat) but becomes a raw low-level function — no caching.
+
+## Changes: agent.ts
+
+**Imports**: replace `connectXFTP`/`closeXFTP` with `getXFTPServerClient`/`closeXFTPAgent` etc.
+
+**Re-export** from agent.ts: `newXFTPAgent`, `closeXFTPAgent`, `XFTPClientAgent`.
+
+**`uploadFile`**: add `agent: XFTPClientAgent` as first param. Replace `connectXFTP` → `getXFTPServerClient`. Remove `finally { closeXFTP }`. Pass `agent` to `uploadRedirectDescription`.
+
+**`uploadRedirectDescription`**: change from `(client, server, innerFd)` to `(agent, server, innerFd)`. Get client via `getXFTPServerClient`.
+
+**`downloadFile`**: add `agent` param. Delete local `connections: Map`. Replace `getOrConnect` → `getXFTPServerClient`. Remove finally cleanup. Pass `agent` to `downloadWithRedirect`.
+
+**`downloadWithRedirect`**: add `agent` param. Same replacements. Remove try/catch cleanup. Recursive call passes `agent`.
+
+**`deleteFile`**: add `agent` param. Same pattern.
+
+**Delete**: `getOrConnect` function entirely.
+
+## Changes: test/browser.test.ts
+
+Create agent before operations, pass to upload/download, close in finally.
+
+## Verification
+
+1. `npx vitest --run` — browser round-trip test passes
+2. No remaining `browserClients`, `getOrConnect`, or per-function `connections: Map` locals
+3. `connectXFTP` and `closeXFTP` still exported (XFTPWebTests.hs compat)
+4. All orchestration functions take `agent` as first param

CHANGELOG.md

@@ -1,3 +1,242 @@
+# 6.5.1
+
+Version 6.5.1.0
+
+XFTP client:
+- backwards compatible file header decoding.
+
+# 6.5.0
+
+Version 6.5.0.17
+
+SMP agent:
+- improve subscriptions
+  - reduce memory usage and retries during initial subscription (#1758)
+  - fix race resulting in pending subscriptions never subscribed (#1756)
+  - batch processing of subscription results and errors (#1652)
+  - reduce memory usage of active subscriptions.
+- drop message after N reception attempts (#1762)
+- fix possible deadlocks of queue overloading when processing messages (#1713)
+- improved APIs for short link management and creation.
+- support multiple link owners in link data (#1701)
+
+SMP server:
+- store messages in PostgreSQL (#1622).
+- reduce memory usage with PostgreSQL database - do not use queue cache (#1637)
+- fix in-memory server not restoring queue/service associations after 2+ restarts (#1618)
+
+XFTP server:
+- support PostgreSQL database.
+- add server page.
+- support uploads from web clients.
+
+Servers:
+- better socket leak prevention during TLS handshake, NetworkError type to bette diagnose connection errors (#1619)
+- use "=" as default INI key-value separator (#1767)
+
+# 6.4.4
+
+Servers:
+- fix server pages when source code is not specified.
+- include commit SHA in printed version and in web page (#1608).
+
+SMP server:
+- support short SimpleX addresses in server information page (#1600).
+- wrap all queries in transactions (#1603).
+
+SMP agent:
+- chat relay address type for short links (#1602).
+- extend xrcp certificate validity 1 hour in the past, to allow out of sync clocks (#1601).
+
+# 6.4.3
+
+SMP agent:
+- fix some connection errors by updating contact request server hosts to match server in short link (#1597).
+
+SMP server:
+- support short link URI as queue identifier in control port commands (#1596).
+
+# 6.4.2
+
+SMP server:
+- fix memory leak when connection interrupts straight after client connects.
+- do not include repeated queue blocking into stats/quota.
+
+XFTP server:
+- prometheus metrics
+
+# 6.4.1
+
+SMP protocol:
+- create notification credentials via NEW command that creates the queue (#1586)
+
+SMP server:
+- control port session improvements (#1591)
+- additional stat counter for ntf credentials created together with the queue (#1589)
+
+# 6.4.0
+
+SMP protocol (server/client):
+- support associated queue data and short connection links (see [RFC](./rfcs/2025-03-16-smp-queues.md)).
+- service certificates to optimize subscriptions.
+
+SMP agent:
+- support retries for interactive connection handshakes.
+- use web port 443 by default for preset servers.
+- use static RNG function to avoid creating dynamic C stubs when generating sntrup keys (it was detected as Dynamic Code Loading in GrapheneOS).
+- different timeouts for interactive and background operations.
+
+Ntf server:
+- PostgreSQL storage.
+- Prometheus metrics.
+- use service certificates.
+- fix repeat token registration.
+
+# 6.3.2
+
+Servers:
+- enable store log by default (#1501).
+
+SMP server:
+- reduce memory usage (#1498)
+
+SMP agent:
+- handle client/agent version downgrades after connection was established (#1508).
+
+# 6.3.1
+
+Servers:
+- handle ECONNABORTED error on client connections.
+- reproducible builds.
+- blocking records for content moderation.
+- update script (simplex-servers-update) downloads scripts from the specified or the latest stable tag.
+
+SMP server:
+- support for PostgreSQL database for queue records for higher traffic servers.
+- fix old clients sending messages to new servers (#1443)
+- remove empty journals when opening message queues and expiring idle queues (#1456, #1458).
+- additional start options (#1465):
+  - `maintenance` to run all start/stop operations without starting server.
+  - `skip-warnings` to ignore the last corrupted line in store log (can happen on abnormal termination).
+
+Ntf server:
+- record date of last token activity, to allow expiring inactive tokens.
+- additional token invalidation reasons in logs.
+
+SMP agent:
+- store message sent to multiple connections only once, to reduce storage when sending to groups (#1453).
+- encrypt messages on delivery, to reduce database writes (#1446).
+- don't block method calls on congested sockets for better concurrency (#1454).
+- check notification token status on client connection.
+- option to skip SQLite vacuum on migrations.
+
+# 6.3.0
+
+SMP agent: fix joining connection after failure by using the same ratchet.
+
+# 6.2.2
+
+SMP server:
+- add optional Prometheus metrics (#1411).
+
+Build:
+- remove three modules from client library.
+
+# 6.2.0
+
+Version 6.2.0.7
+
+Build:
+- client_library flag to build only used modules in the clients, remove package yaml
+
+SMP server:
+- journal storage for messages (BETA).
+- prevent race condition when deleting queue and to avoid "orphan" messages (#1395).
+
+SMP agent:
+- support SMP and XFTP server roles (storage/proxy) and operators (#1343).
+- treat blocked STM and other critical errors that offer restart as temporary for message delivery (#1405).
+- fix inconsistent state after app restart while accepting contact request (#1412).
+
+# 6.1.3
+
+SMP server: fix restoring notification credentials.
+
+# 6.1.2
+
+Servers: more reliable restoring of state.
+
+SMP server: reduced memory usage and faster start.
+
+Notifications: compensate for iOS notifications being dropped by Apple while device is offline (#1378):
+- Ntf server: send multiple SMP notifications in one iOS notification.
+- Agent: get multiple messages for one iOS notification.
+
+# 6.1.1
+
+SMP:
+- stop server faster (#1371)
+- add STORE error (#1372)
+
+# 6.1.0
+
+Version 6.1.0.7
+
+SMP server and client:
+- transport block encryption (#1317).
+
+Agent:
+- batch and optimize iOS notifications processing (#1308, #1311, #1313, #1316, #1330, #1331, #1333, #1337, #1346).
+- allow receiving multiple messages from single iOS notification (#1355, #1362).
+- prepare connection to accept to avoid race condition with events (#1365).
+- transport isolation mode "Session" (default) to use new SOCKS credentials when client restarts or SOCKS proxy configuration changes (#1321).
+
+Ntf server:
+- control port (#1354).
+- enable pings on ntf subscriptions, to resubscribe on reconnection (#1353).
+
+SMP server:
+- support multiple server ports (#1319).
+- support serving HTTPS and SMP transport on the same port (#1326, #1327).
+- persist iOS notifications to avoid losing them when Ntf server is offline (#1336, #1339, #1350).
+- fix lost notification subscriptions (#1347).
+- reject SKEY with different key earlier, at verification step (#1366).
+- pass server information via CLI during server initialization (#1356).
+- show version on server page (#1341).
+- explicit graceful shutdown on SIGINT (#1360).
+
+XRCP (remote access protocol):
+- use SHA3-256 in hybrid key agreement (#1302).
+- session encryption with forward secrecy (#1328).
+
+# 6.0.5
+
+SMP agent:
+- support generic SOCKS proxy (without isolate-by-auth).
+- reduce max message sizes
+
+# 6.0.4
+
+SMP server:
+- better performance/memory: fewer map updates on re-subscriptions (#1297), split and reduce STM transactions (#1294)
+- send DELD when subscribed queue is deleted (#1312)
+- add created/updated/used date to queues to manage expiration (#1306)
+
+XFTP server: truncate file creation time to 1 hour (#1310)
+
+Servers:
+- bind control port only to 127.0.0.1 for better security in case of firewall misconfiguration (#1280)
+- reduce memory used for period stats (#1298)
+
+Agent: process last notification from list (#1307)
+- report receive file error with redirected file ID, when redirect is present (#1304)
+- special error when deleted user record is not in database (#1303)
+- fix race when sending a message to the deleted connection (#1296)
+- support for multiple messages in a single notification
+
+Ntf server:
+- only use SOCKS proxy for servers without public address (#1314)
+
 # 6.0.3
 
 Agent:

Dockerfile

@@ -1,15 +1,20 @@
-ARG TAG=22.04
+# syntax=docker/dockerfile:1.7.0-labs
+ARG TAG=24.04
 
 FROM ubuntu:${TAG} AS build
 
 ### Build stage
 
 # Install curl and git and simplexmq dependencies
-RUN apt-get update && apt-get install -y curl git build-essential libgmp3-dev zlib1g-dev llvm-12 llvm-12-dev libnuma-dev libssl-dev
+RUN apt-get update && apt-get install -y curl git build-essential libgmp3-dev zlib1g-dev llvm-18 llvm-18-dev libnuma-dev libssl-dev
 
 # Specify bootstrap Haskell versions
 ENV BOOTSTRAP_HASKELL_GHC_VERSION=9.6.3
-ENV BOOTSTRAP_HASKELL_CABAL_VERSION=3.10.1.0
+ENV BOOTSTRAP_HASKELL_CABAL_VERSION=3.12.1.0
+
+# Do not install Stack
+ENV BOOTSTRAP_HASKELL_INSTALL_NO_STACK=true
+ENV BOOTSTRAP_HASKELL_INSTALL_NO_STACK_HOOK=true
 
 # Install ghcup
 RUN curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_HASKELL_NONINTERACTIVE=1 sh
@@ -21,26 +26,42 @@ ENV PATH="/root/.cabal/bin:/root/.ghcup/bin:$PATH"
 RUN ghcup set ghc "${BOOTSTRAP_HASKELL_GHC_VERSION}" && \
     ghcup set cabal "${BOOTSTRAP_HASKELL_CABAL_VERSION}"
 
-COPY . /project
+# Copy only the source code
+COPY apps /project/apps/
+COPY cbits /project/cbits/
+COPY src /project/src/
+
+COPY cabal.project Setup.hs simplexmq.cabal LICENSE /project
+
 WORKDIR /project
 
+# Debug
+#ARG CACHEBUST=1
+
+#ADD --chmod=755 https://github.com/MShekow/directory-checksum/releases/download/v1.4.6/directory-checksum_1.4.6_linux_amd64 /usr/local/bin/directory-checksum
+#RUN directory-checksum --max-depth 2 .
+
+# Set build arguments and check if they exist
 ARG APP
-ARG APP_PORT
-RUN if [ -z "$APP" ] || [ -z "$APP_PORT" ]; then printf "Please spcify \$APP and \$APP_PORT build-arg.\n"; exit 1; fi
+RUN if [ -z "$APP" ]; then printf "Please spcify \$APP build-arg.\n"; exit 1; fi
 
 # Compile app
 RUN cabal update
 RUN cabal build exe:$APP
 
+# Copy scripts
+COPY scripts /project/scripts/
+
 # Create new path containing all files needed
 RUN mkdir /final
 WORKDIR /final
 
 # Strip the binary from debug symbols to reduce size
-RUN bin=$(find /project/dist-newstyle -name "$APP" -type f -executable) && \
+RUN bin="$(find /project/dist-newstyle -name "$APP" -type f -executable)" && \
     mv "$bin" ./ && \
     strip ./"$APP" &&\
-    mv /project/scripts/docker/entrypoint-"$APP" ./entrypoint
+    mv /project/scripts/docker/entrypoint-"$APP" ./entrypoint &&\
+    mv /project/scripts/main/simplex-servers-stopscript ./simplex-servers-stopscript
 
 ### Final stage
 FROM ubuntu:${TAG}
@@ -53,6 +74,8 @@ COPY --from=build /final /usr/local/bin/
 
 # Open app listening port
 ARG APP_PORT
+RUN if [ -z "$APP_PORT" ]; then printf "Please spcify \$APP_PORT build-arg.\n"; exit 1; fi
+
 EXPOSE $APP_PORT
 
 # simplexmq requires using SIGINT to correctly preserve undelivered messages and restore them on restart

Dockerfile.build

@@ -0,0 +1,31 @@
+# syntax=docker/dockerfile:1.7.0-labs
+ARG TAG=24.04
+FROM ubuntu:${TAG} AS build
+
+### Build stage
+
+ARG GHC=9.6.3
+ARG CABAL=3.14.1.1
+
+# Install curl, git and and simplexmq dependencies
+RUN apt-get update && apt-get install -y curl libpq-dev git sqlite3 libsqlite3-dev build-essential libgmp3-dev zlib1g-dev llvm llvm-dev libnuma-dev libssl-dev
+
+# Specify bootstrap Haskell versions
+ENV BOOTSTRAP_HASKELL_GHC_VERSION=${GHC}
+ENV BOOTSTRAP_HASKELL_CABAL_VERSION=${CABAL}
+
+# Do not install Stack
+ENV BOOTSTRAP_HASKELL_INSTALL_NO_STACK=true
+ENV BOOTSTRAP_HASKELL_INSTALL_NO_STACK_HOOK=true
+
+# Install ghcup
+RUN curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_HASKELL_NONINTERACTIVE=1 sh
+
+# Adjust PATH
+ENV PATH="/root/.cabal/bin:/root/.ghcup/bin:$PATH"
+
+# Set both as default
+RUN ghcup set ghc "${GHC}" && \
+    ghcup set cabal "${CABAL}"
+
+WORKDIR /project

README.md

@@ -1,6 +1,6 @@
 # SimpleXMQ
 
-[![GitHub build](https://github.com/simplex-chat/simplexmq/workflows/build/badge.svg)](https://github.com/simplex-chat/simplexmq/actions?query=workflow%3Abuild)
+[![GitHub build](https://github.com/simplex-chat/simplexmq/actions/workflows/build.yml/badge.svg)](https://github.com/simplex-chat/simplexmq/actions/workflows/build.yml)
 [![GitHub release](https://img.shields.io/github/v/release/simplex-chat/simplexmq)](https://github.com/simplex-chat/simplexmq/releases)
 
 📢 SimpleXMQ v1 is released - with many security, privacy and efficiency improvements, new functionality - see [release notes](https://github.com/simplex-chat/simplexmq/releases/tag/v1.0.0).
@@ -33,7 +33,7 @@ To initialize the server use `smp-server init -n <fqdn>` (or `smp-server init --
 
 SMP server uses in-memory persistence with an optional append-only log of created queues that allows to re-start the server without losing the connections. This log is compacted on every server restart, permanently removing suspended and removed queues.
 
-To enable store log, initialize server using `smp-server -l` command, or modify `smp-server.ini` created during initialization (uncomment `enable: on` option in the store log section). Use `smp-server --help` for other usage tips.
+To enable store log, initialize server using `smp-server -l` command, or modify `smp-server.ini` created during initialization (uncomment `enable = on` option in the store log section). Use `smp-server --help` for other usage tips.
 
 Starting from version 2.3.0, when store log is enabled, the server would also enable saving undelivered messages on exit and restoring them on start. This can be disabled via a separate setting `restore_messages` in `smp-server.ini` file. Saving messages would only work if the server is stopped with SIGINT signal (keyboard interrupt), if it is stopped with SIGTERM signal the messages would not be saved.
 
@@ -116,7 +116,7 @@ On Linux, you can deploy smp and xftp server using Docker. This will download im
 2. Run your Docker container.
 
    - `smp-server`
-   
+
      You must change **your_ip_or_domain**. `-e "pass=password"` is optional variable to password-protect your `smp` server:
      ```sh
      docker run -d \
@@ -129,7 +129,7 @@ On Linux, you can deploy smp and xftp server using Docker. This will download im
      ```
 
    - `xftp-server`
-   
+
      You must change **your_ip_or_domain** and **maximum_storage**.
      ```sh
      docker run -d \
@@ -149,8 +149,15 @@ On Linux, you can deploy smp and xftp server using Docker. This will download im
 You can install and setup servers automatically using our script:
 
 ```sh
-curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/simplex-chat/simplexmq/stable/install.sh -o simplex-server-install.sh \
-&& if echo 'c90886104cd640b2ed64921dba80e90691db36788e8d6dcc13d8f33f92f0ea54 simplex-server-install.sh' | sha256sum -c; then chmod +x ./simplex-server-install.sh && ./simplex-server-install.sh; rm ./simplex-server-install.sh; else echo "SHA-256 checksum is incorrect!" && rm ./simplex-server-install.sh; fi
+curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/simplex-chat/simplexmq/stable/install.sh -o simplex-server-install.sh &&\
+if echo '53fcdb4ceab324316e2c4cda7e84dbbb344f32550a65975a7895425e5a1be757 simplex-server-install.sh' | sha256sum -c; then
+  chmod +x ./simplex-server-install.sh
+  ./simplex-server-install.sh
+  rm ./simplex-server-install.sh
+else
+  echo "SHA-256 checksum is incorrect!"
+  rm ./simplex-server-install.sh
+fi
 ```
 
 ### Build from source
@@ -180,7 +187,7 @@ On Linux, you can build smp server using Docker.
 3. Run your Docker container.
 
    - `smp-server`
-   
+
      You must change **your_ip_or_domain**. `-e "pass=password"` is optional variable to password-protect your `smp` server:
      ```sh
      docker run -d \
@@ -193,7 +200,7 @@ On Linux, you can build smp server using Docker.
      ```
 
    - `xftp-server`
-   
+
      You must change **your_ip_or_domain** and **maximum_storage**.
      ```sh
      docker run -d \
@@ -240,7 +247,7 @@ On Linux, you can build smp server using Docker.
 
    `xftp-server`
    ```sh
-   cabal list-bin exe:xftp-server 
+   cabal list-bin exe:xftp-server
    ```
 
 - Initialize SMP server with `smp-server init [-l] -n <fqdn>` or `smp-server init [-l] --ip <ip>` - depending on how you initialize it, either FQDN or IP will be used for server's address.

apps/common/Web/Embedded.hs

@@ -0,0 +1,15 @@
+{-# LANGUAGE TemplateHaskell #-}
+
+module Web.Embedded where
+
+import Data.FileEmbed (embedDir, embedFile)
+import Simplex.Messaging.Server.Web (EmbeddedContent (..))
+
+embeddedContent :: EmbeddedContent
+embeddedContent =
+  EmbeddedContent
+    { indexHtml = $(embedFile "apps/common/Web/static/index.html"),
+      linkHtml = $(embedFile "apps/common/Web/static/link.html"),
+      mediaContent = $(embedDir "apps/common/Web/static/media/"),
+      wellKnown = $(embedDir "apps/common/Web/static/.well-known/")
+    }

apps/common/Web/static/.well-known/apple-app-site-association

@@ -0,0 +1,49 @@
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": [
+          "5NN7GUYB6T.chat.simplex.app"
+        ],
+        "components": [
+          {
+            "/": "/contact/*"
+          },
+          {
+            "/": "/contact"
+          },
+          {
+            "/": "/invitation/*"
+          },
+          {
+            "/": "/invitation"
+          },
+          {
+            "/": "/a/*"
+          },
+          {
+            "/": "/a"
+          },
+          {
+            "/": "/c/*"
+          },
+          {
+            "/": "/c"
+          },
+          {
+            "/": "/g/*"
+          },
+          {
+            "/": "/g"
+          },
+          {
+            "/": "/i/*"
+          },
+          {
+            "/": "/i"
+          }
+        ]
+      }
+    ]
+  }
+}

apps/common/Web/static/.well-known/assetlinks.json

@@ -0,0 +1,16 @@
+[
+    {
+        "relation": [
+            "delegate_permission/common.handle_all_urls"
+        ],
+        "target": {
+            "namespace": "android_app",
+            "package_name": "chat.simplex.app",
+            "sha256_cert_fingerprints": [
+                "5E:3E:DC:C2:00:FB:A8:D5:F4:88:F3:CA:4C:32:5B:05:78:C5:6A:9C:03:A1:CC:B5:92:9C:D7:5C:7E:57:E2:4D",
+                "3C:52:C4:FD:3C:AD:1C:07:C9:B0:0A:70:80:E3:58:FA:B9:FE:FC:B8:AF:5A:EC:14:77:65:F1:6D:0F:21:AD:85",
+                "AE:C1:95:DC:FD:46:14:BD:3A:91:EC:26:D1:D5:14:C8:75:71:C5:CC:8D:CF:48:08:3F:92:83:14:3C:A2:B9:A6"
+            ]
+        }
+    }
+]

apps/common/Web/static/index.html

@@ -105,6 +105,13 @@
                     class="text-[16px] leading-[26px] tracking-[0.01em] nav-link-text text-black dark:text-white before:bg-black dark:before:bg-white">Server
                     information</span></a>
               </li>
+              <!-- <x-xftpConfig>
+              <li class="nav-link relative"><a href="/file"
+                  class="flex items-center justify-between gap-2 lg:py-5 whitespace-nowrap"><span
+                    class="text-[16px] leading-[26px] tracking-[0.01em] nav-link-text text-black dark:text-white before:bg-black dark:before:bg-white">File
+                    transfer</span></a>
+              </li>
+              </x-xftpConfig> -->
             </ul><a target="_blank" href="https://github.com/simplex-chat/simplex-chat#help-us-with-donations"
               class="whitespace-nowrap flex items-center gap-1 self-center text-white dark:text-black text-[16px] font-medium tracking-[0.02em] rounded-[34px] bg-primary-light dark:bg-primary-dark py-3 lg:py-2 px-20 lg:px-5 mb-16 lg:mb-0">Donate</a>
           </div>
@@ -221,9 +228,16 @@
               Public information
             </h2>
             <table id="public-info">
+              <tr class="text-grey-black dark:text-white text-base">
+                <td>Server version:</td>
+                <td>${version}<x-commit> / <a href="${commitSourceCode}/commit/${commit}" target="_blank">${shortCommit}</a></x-commit></td>
+              </tr>
               <tr class="text-grey-black dark:text-white text-base">
                 <td>Source code:</td>
-                <td><a href="${sourceCode}" target="_blank">${sourceCode}</a></td>
+                <td>
+                  <x-sourceCode><a href="${sourceCode}" target="_blank">${sourceCode}</a></x-sourceCode>
+                  <x-noSourceCode>add to ${iniFileName} (required by <a href="https://github.com/simplex-chat/simplexmq/blob/stable/LICENSE" target="_blank">AGPLv3</a>)</x-noSourceCode>
+                </td>
               </tr>
               <x-website>
                 <tr class="text-grey-black dark:text-white text-base">
@@ -291,6 +305,12 @@
                   <td>${hostingEntity} (${hostingCountry})</td>
                 </tr>
               </x-hosting>
+              <x-hostingType>
+                <tr class="text-grey-black dark:text-white text-base">
+                  <td>Hosting type:</td>
+                  <td>${hostingType}</td>
+                </tr>
+              </x-hostingType>
               <x-serverCountry>
                 <tr class="text-grey-black dark:text-white text-base">
                   <td>Server country:</td>
@@ -304,6 +324,7 @@
             <h2 class="text-[30px] mb-[20px] leading-[28px] text-[#606C71] dark:text-white font-bold max-w-[475px]">
               Configuration</h2>
             <table id="config">
+              <x-smpConfig>
               <tr class="text-grey-black dark:text-white text-base">
                 <td>Persistence:</td>
                 <td>${persistence}</td>
@@ -324,6 +345,25 @@
                 <td>Basic auth enabled:</td>
                 <td>${basicAuthEnabled}</td>
               </tr>
+              </x-smpConfig>
+              <x-xftpConfig>
+              <tr class="text-grey-black dark:text-white text-base">
+                <td>File expiration:</td>
+                <td>${fileExpiration}</td>
+              </tr>
+              <tr class="text-grey-black dark:text-white text-base">
+                <td>Stats enabled:</td>
+                <td>${statsEnabled}</td>
+              </tr>
+              <tr class="text-grey-black dark:text-white text-base">
+                <td>New uploads allowed:</td>
+                <td>${newUploadsAllowed}</td>
+              </tr>
+              <tr class="text-grey-black dark:text-white text-base">
+                <td>Basic auth enabled:</td>
+                <td>${basicAuthEnabled}</td>
+              </tr>
+              </x-xftpConfig>
             </table>
           </div>
         </div>

apps/common/Web/static/link.html

@@ -142,8 +142,7 @@
     class="hidden xl:block h-screen pt-[66px] bg-white dark:bg-gradient-radial-mobile dark:lg:bg-gradient-radial">
     <div class="container m-auto h-full flex items-center justify-between px-5">
       <div class="flex flex-col items-start justify-center w-full">
-        <h1 class="text-[38px] leading-[43px] font-bold max-w-[500px] mb-[30px] primary-header-contact">You received a
-          1-time link to connect on SimpleX Chat</h1>
+        <h1 class="text-[38px] leading-[43px] font-bold max-w-[500px] mb-[30px] primary-header-contact">This is a one-time link of the SimpleX&nbsp;network user</h1>
         <h2
           class="text-[20px] leading-[28px] text-[#606C71] dark:text-white font-bold max-w-[475px] mb-[80px] secondary-header-contact">
           Scan the QR code with the SimpleX Chat app on your phone or tablet.</h2>
@@ -184,10 +183,8 @@
     class="block xl:hidden pt-[106px] py-[90px] bg-white dark:bg-gradient-radial-mobile dark:lg:bg-gradient-radial">
     <div class="container m-auto px-5">
       <div class="flex flex-col items-center">
-        <h1 class="text-[28px] font-bold text-center max-w-[602px] mb-[40px] primary-header-contact">You received a
-          1-time link to connect on SimpleX Chat</h1>
-        <p class="text-[20px] leading-[28px] text-grey-black dark:text-white font-medium mb-[30px]">To make a
-          connection:</p>
+        <h1 class="text-[28px] font-bold text-center max-w-[602px] mb-[40px] primary-header-contact">This is a one-time link of the SimpleX&nbsp;network user</h1>
+        <p class="text-[20px] leading-[28px] text-grey-black dark:text-white font-medium mb-[30px]">To make a connection:</p>
         <div
           class="flex flex-col justify-center items-center p-4 w-full max-w-[468px] min-h-[131px] rounded-[30px] border-[1px] border-[#A8B0B4] dark:border-white border-opacity-60 mb-6 relative">
           <p class="text-xl font-medium text-grey-black dark:text-white mb-4">Install SimpleX app</p>
@@ -506,13 +503,17 @@
     const url = window.location.href
     const messageElements = document.getElementsByClassName('primary-header-contact')
 
-    if (url.includes('/invitation')) {
-      for (let element of messageElements) {
-        element.textContent = 'You received a 1-time link to connect on SimpleX Chat'
-      }
-    } else {
-      for (let element of messageElements) {
-        element.textContent = 'You received an address to connect on SimpleX Chat'
+    for (let element of messageElements) {
+      if (url.includes('/g') || url.includes('&data=%7B%22groupLinkId%22%3A')) {
+        element.innerHTML = 'This is a public group address on SimpleX&nbsp;network'
+      } else if (url.includes('/a') || url.includes('/contact')) {
+        element.innerHTML = 'This is a public address of the SimpleX&nbsp;network user'
+      } else if (url.includes('/i') || url.includes('/invitation')) {
+        element.innerHTML = 'This is a one-time link of the SimpleX&nbsp;network user'
+      } else if (url.includes('/c')) {
+        element.innerHTML = 'This is a public channel address on SimpleX&nbsp;network'
+      } else if (url.includes('/r')) {
+        element.innerHTML = 'This is a chat relay address on SimpleX&nbsp;network'
       }
     }
   </script>

apps/common/Web/static/media/contact.js

@@ -20,7 +20,18 @@
     parsedURI.pathname = "/" + action
     connURI = parsedURI.toString()
     console.log("connection URI: ", connURI)
-    mobileConnURIanchor.href = "simplex:" + parsedURI.pathname + parsedURI.hash
+    const hash = parsedURI.hash
+    const hostname = parsedURI.hostname
+    let appURI = "simplex:" + parsedURI.pathname
+    appURI += action.length > 1 // not short link
+              ? hash
+              : !hash.includes("?") // otherwise add server hostname
+              ? hash + "?h=" + hostname // no parameters
+              : !hash.includes("?h=") && !hash.includes("&h=")
+              ? hash + "&h=" + hostname // no "h" parameter
+              : hash.replace(/([?&])h=([^&]+)/, `$1h=${hostname},$2`) // add as the first hostname to "h" parameter
+    mobileConnURIanchor.href = appURI
+    console.log("app URI: ", appURI)
     connURIel.innerText = "/c " + connURI
     for (const connQRCode of connQRCodes) {
       try {

apps/ntf-server/Main.hs

@@ -15,7 +15,6 @@ logCfg = LogConfig {lc_file = Nothing, lc_stderr = True}
 
 main :: IO ()
 main = do
-  setLogLevel LogDebug -- change to LogError in production
   cfgPath <- getEnvPath "NTF_SERVER_CFG_PATH" defaultCfgPath
   logPath <- getEnvPath "NTF_SERVER_LOG_PATH" defaultLogPath
   withGlobalLogging logCfg $ ntfServerCLI cfgPath logPath

apps/smp-server/Main.hs

@@ -2,8 +2,9 @@ module Main where
 
 import Control.Logger.Simple
 import Simplex.Messaging.Server.CLI (getEnvPath)
-import Simplex.Messaging.Server.Main
-import qualified Static
+import Simplex.Messaging.Server.Main (smpServerCLI_)
+import Simplex.Messaging.Server.Web (serveStaticFiles, attachStaticFiles)
+import SMPWeb (smpGenerateSite)
 
 defaultCfgPath :: FilePath
 defaultCfgPath = "/etc/opt/simplex"
@@ -16,7 +17,6 @@ logCfg = LogConfig {lc_file = Nothing, lc_stderr = True}
 
 main :: IO ()
 main = do
-  setLogLevel LogDebug
   cfgPath <- getEnvPath "SMP_SERVER_CFG_PATH" defaultCfgPath
   logPath <- getEnvPath "SMP_SERVER_LOG_PATH" defaultLogPath
-  withGlobalLogging logCfg $ smpServerCLI_ Static.generateSite Static.serveStaticFiles cfgPath logPath
+  withGlobalLogging logCfg $ smpServerCLI_ smpGenerateSite serveStaticFiles attachStaticFiles cfgPath logPath

apps/smp-server/SMPWeb.hs

@@ -0,0 +1,43 @@
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module SMPWeb
+  ( smpGenerateSite,
+    serverInformation,
+  ) where
+
+import Data.ByteString (ByteString)
+import Data.String (fromString)
+import Web.Embedded (embeddedContent)
+import Simplex.Messaging.Encoding.String (strEncode)
+import Simplex.Messaging.Server.Information
+import Simplex.Messaging.Server.Main (simplexmqSource)
+import qualified Simplex.Messaging.Server.Web as Web
+import Simplex.Messaging.Server.Web (render, serverInfoSubsts, timedTTLText)
+import Simplex.Messaging.Transport.Client (TransportHost (..))
+
+smpGenerateSite :: ServerInformation -> Maybe TransportHost -> FilePath -> IO ()
+smpGenerateSite si onionHost path =
+  Web.generateSite embeddedContent (serverInformation si onionHost) smpLinkPages path
+
+smpLinkPages :: [String]
+smpLinkPages = ["contact", "invitation", "a", "c", "g", "r", "i"]
+
+serverInformation :: ServerInformation -> Maybe TransportHost -> ByteString
+serverInformation ServerInformation {config, information} onionHost = render (Web.indexHtml embeddedContent) substs
+  where
+    substs = [("smpConfig", Just "y"), ("xftpConfig", Nothing)] <> substConfig <> serverInfoSubsts simplexmqSource information <> [("onionHost", strEncode <$> onionHost), ("iniFileName", Just "smp-server.ini")]
+    substConfig =
+      [ ( "persistence",
+          Just $ case persistence config of
+            SPMMemoryOnly -> "In-memory only"
+            SPMQueues -> "Queues"
+            SPMMessages -> "Queues and messages"
+        ),
+        ("messageExpiration", Just $ maybe "Never" (fromString . timedTTLText) $ messageExpiration config),
+        ("statsEnabled", Just . yesNo $ statsEnabled config),
+        ("newQueuesAllowed", Just . yesNo $ newQueuesAllowed config),
+        ("basicAuthEnabled", Just . yesNo $ basicAuthEnabled config)
+      ]
+    yesNo True = "Yes"
+    yesNo False = "No"

apps/smp-server/static/contact/index.html

@@ -1 +0,0 @@
-../link.html

apps/smp-server/static/invitation/index.html

@@ -1 +0,0 @@
-../link.html

apps/smp-server/web/Static.hs

@@ -1,176 +0,0 @@
-{-# LANGUAGE LambdaCase #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-
-module Static where
-
-import Control.Logger.Simple
-import Control.Monad
-import Data.ByteString (ByteString)
-import qualified Data.ByteString as B
-import Data.Maybe (fromMaybe)
-import Data.String (fromString)
-import Data.Text.Encoding (encodeUtf8)
-import Network.Wai.Application.Static as S
-import Network.Wai.Handler.Warp as W
-import qualified Network.Wai.Handler.WarpTLS as W
-import Simplex.Messaging.Encoding.String (strEncode)
-import Simplex.Messaging.Server.Information
-import Simplex.Messaging.Server.Main (EmbeddedWebParams (..), WebHttpsParams (..))
-import Simplex.Messaging.Transport.Client (TransportHost (..))
-import Simplex.Messaging.Util (tshow)
-import Static.Embedded as E
-import System.Directory (createDirectoryIfMissing)
-import System.FilePath
-import UnliftIO.Concurrent (forkFinally)
-
-serveStaticFiles :: EmbeddedWebParams -> IO ()
-serveStaticFiles EmbeddedWebParams {webStaticPath, webHttpPort, webHttpsParams} = do
-  forM_ webHttpPort $ \port -> flip forkFinally (\e -> logError $ "HTTP server crashed: " <> tshow e) $ do
-    logInfo $ "Serving static site on port " <> tshow port
-    W.runSettings (mkSettings port) (S.staticApp $ S.defaultFileServerSettings webStaticPath)
-  forM_ webHttpsParams $ \WebHttpsParams {port, cert, key} -> flip forkFinally (\e -> logError $ "HTTPS server crashed: " <> tshow e) $ do
-    logInfo $ "Serving static site on port " <> tshow port <> " (TLS)"
-    W.runTLS (W.tlsSettings cert key) (mkSettings port) (S.staticApp $ S.defaultFileServerSettings webStaticPath)
-  where
-    mkSettings port = setPort port defaultSettings
-
-generateSite :: ServerInformation -> Maybe TransportHost -> FilePath -> IO ()
-generateSite si onionHost sitePath = do
-  createDirectoryIfMissing True sitePath
-  B.writeFile (sitePath </> "index.html") $ serverInformation si onionHost
-  createDirectoryIfMissing True $ sitePath </> "media"
-  forM_ E.mediaContent $ \(path, bs) -> B.writeFile (sitePath </> "media" </> path) bs
-  createDirectoryIfMissing True $ sitePath </> "contact"
-  B.writeFile (sitePath </> "contact" </> "index.html") E.linkHtml
-  createDirectoryIfMissing True $ sitePath </> "invitation"
-  B.writeFile (sitePath </> "invitation" </> "index.html") E.linkHtml
-  logInfo $ "Generated static site contents at " <> tshow sitePath
-
-serverInformation :: ServerInformation -> Maybe TransportHost -> ByteString
-serverInformation ServerInformation {config, information} onionHost = render E.indexHtml substs
-  where
-    substs = substConfig <> maybe [] substInfo information <> [("onionHost", strEncode <$> onionHost)]
-    substConfig =
-      [ ( "persistence",
-          Just $ case persistence config of
-            SPMMemoryOnly -> "In-memory only"
-            SPMQueues -> "Queues"
-            SPMMessages -> "Queues and messages"
-        ),
-        ("messageExpiration", Just $ maybe "Never" (fromString . timedTTLText) $ messageExpiration config),
-        ("statsEnabled", Just . yesNo $ statsEnabled config),
-        ("newQueuesAllowed", Just . yesNo $ newQueuesAllowed config),
-        ("basicAuthEnabled", Just . yesNo $ basicAuthEnabled config)
-      ]
-    yesNo True = "Yes"
-    yesNo False = "No"
-    substInfo spi =
-      concat
-        [ basic,
-          maybe [("usageConditions", Nothing), ("usageAmendments", Nothing)] conds (usageConditions spi),
-          maybe [("operator", Nothing)] operatorE (operator spi),
-          maybe [("admin", Nothing)] admin (adminContacts spi),
-          maybe [("complaints", Nothing)] complaints (complaintsContacts spi),
-          maybe [("hosting", Nothing)] hostingE (hosting spi),
-          server
-        ]
-      where
-        basic =
-          [ ("sourceCode", Just . encodeUtf8 $ sourceCode spi),
-            ("website", encodeUtf8 <$> website spi)
-          ]
-        conds ServerConditions {conditions, amendments} =
-          [ ("usageConditions", Just $ encodeUtf8 conditions),
-            ("usageAmendments", encodeUtf8 <$> amendments)
-          ]
-        operatorE Entity {name, country} =
-          [ ("operator", Just ""),
-            ("operatorEntity", Just $ encodeUtf8 name),
-            ("operatorCountry", encodeUtf8 <$> country)
-          ]
-        admin ServerContactAddress {simplex, email, pgp} =
-          [ ("admin", Just ""),
-            ("adminSimplex", strEncode <$> simplex),
-            ("adminEmail", encodeUtf8 <$> email),
-            ("adminPGP", encodeUtf8 . pkURI <$> pgp),
-            ("adminPGPFingerprint", encodeUtf8 . pkFingerprint <$> pgp)
-          ]
-        complaints ServerContactAddress {simplex, email, pgp} =
-          [ ("complaints", Just ""),
-            ("complaintsSimplex", strEncode <$> simplex),
-            ("complaintsEmail", encodeUtf8 <$> email),
-            ("complaintsPGP", encodeUtf8 . pkURI <$> pgp),
-            ("complaintsPGPFingerprint", encodeUtf8 . pkFingerprint <$> pgp)
-          ]
-        hostingE Entity {name, country} =
-          [ ("hosting", Just ""),
-            ("hostingEntity", Just $ encodeUtf8 name),
-            ("hostingCountry", encodeUtf8 <$> country)
-          ]
-        server =
-          [ ("serverCountry", fmap encodeUtf8 $ serverCountry =<< information)
-          ]
-
--- Copy-pasted from simplex-chat Simplex.Chat.Types.Preferences
-{-# INLINE timedTTLText #-}
-timedTTLText :: (Integral i, Show i) => i -> String
-timedTTLText 0 = "0 sec"
-timedTTLText ttl = do
-  let (m', s) = ttl `quotRem` 60
-      (h', m) = m' `quotRem` 60
-      (d', h) = h' `quotRem` 24
-      (mm, d) = d' `quotRem` 30
-  unwords $
-    [mms mm | mm /= 0]
-      <> [ds d | d /= 0]
-      <> [hs h | h /= 0]
-      <> [ms m | m /= 0]
-      <> [ss s | s /= 0]
-  where
-    ss s = show s <> " sec"
-    ms m = show m <> " min"
-    hs 1 = "1 hour"
-    hs h = show h <> " hours"
-    ds 1 = "1 day"
-    ds 7 = "1 week"
-    ds 14 = "2 weeks"
-    ds d = show d <> " days"
-    mms 1 = "1 month"
-    mms mm = show mm <> " months"
-
--- | Rewrite source with provided substitutions
-render :: ByteString -> [(ByteString, Maybe ByteString)] -> ByteString
-render src = \case
-  [] -> src
-  (label, content') : rest -> render (section_ label content' src) rest
-
--- | Rewrite section content inside @<x-label>...</x-label>@ markers.
--- Markers are always removed when found. Closing marker is mandatory.
--- If content is absent, whole section is removed.
--- Section content is delegated to `item_`. If no sections found, the whole source is delegated.
-section_ :: ByteString -> Maybe ByteString -> ByteString -> ByteString
-section_ label content' src =
-  case B.breakSubstring startMarker src of
-    (_, "") -> item_ label (fromMaybe "" content') src -- no section, just replace items
-    (before, afterStart') ->
-      -- found section start, search for end too
-      case B.breakSubstring endMarker $ B.drop (B.length startMarker) afterStart' of
-        (_, "") -> error $ "missing section end: " <> show endMarker
-        (inside, next') ->
-          let next = B.drop (B.length endMarker) next'
-           in case content' of
-                Nothing -> before <> next -- collapse section
-                Just content -> before <> item_ label content inside <> section_ label content' next
-  where
-    startMarker = "<x-" <> label <> ">"
-    endMarker = "</x-" <> label <> ">"
-
--- | Replace all occurences of @${label}@ with provided content.
-item_ :: ByteString -> ByteString -> ByteString -> ByteString
-item_ label content' src =
-  case B.breakSubstring marker src of
-    (done, "") -> done
-    (before, after') -> before <> content' <> item_ label content' (B.drop (B.length marker) after')
-  where
-    marker = "${" <> label <> "}"

apps/smp-server/web/Static/Embedded.hs

@@ -1,15 +0,0 @@
-{-# LANGUAGE TemplateHaskell #-}
-
-module Static.Embedded where
-
-import Data.FileEmbed (embedDir, embedFile)
-import Data.ByteString (ByteString)
-
-indexHtml :: ByteString
-indexHtml = $(embedFile "apps/smp-server/static/index.html")
-
-linkHtml :: ByteString
-linkHtml = $(embedFile "apps/smp-server/static/link.html")
-
-mediaContent :: [(FilePath, ByteString)]
-mediaContent = $(embedDir "apps/smp-server/static/media/")

apps/xftp-server/Main.hs

@@ -1,8 +1,10 @@
 module Main where
 
 import Control.Logger.Simple
+import Simplex.FileTransfer.Server.Main (xftpServerCLI_)
 import Simplex.Messaging.Server.CLI (getEnvPath)
-import Simplex.FileTransfer.Server.Main
+import Simplex.Messaging.Server.Web (serveStaticFiles)
+import XFTPWeb (xftpGenerateSite)
 
 defaultCfgPath :: FilePath
 defaultCfgPath = "/etc/opt/simplex-xftp"
@@ -18,4 +20,4 @@ main = do
   setLogLevel LogDebug -- change to LogError in production
   cfgPath <- getEnvPath "XFTP_SERVER_CFG_PATH" defaultCfgPath
   logPath <- getEnvPath "XFTP_SERVER_LOG_PATH" defaultLogPath
-  withGlobalLogging logCfg $ xftpServerCLI cfgPath logPath
+  withGlobalLogging logCfg $ xftpServerCLI_ xftpGenerateSite serveStaticFiles cfgPath logPath

apps/xftp-server/XFTPWeb.hs

@@ -0,0 +1,67 @@
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+module XFTPWeb
+  ( xftpGenerateSite,
+    xftpServerInformation,
+  ) where
+
+import Control.Monad (forM_)
+import qualified Data.ByteString.Char8 as B
+import Data.ByteString (ByteString)
+import Data.FileEmbed (embedDir, embedFile)
+import Data.Maybe (isJust)
+import Data.String (fromString)
+import Web.Embedded (embeddedContent)
+import Simplex.FileTransfer.Server.Env (XFTPServerConfig (..))
+import Simplex.Messaging.Encoding.String (strEncode)
+import Simplex.Messaging.Server.Expiration (ExpirationConfig (..))
+import Simplex.Messaging.Server.Information (ServerPublicInfo)
+import Simplex.Messaging.Server.Main (simplexmqSource)
+import qualified Simplex.Messaging.Server.Web as Web
+import Simplex.Messaging.Server.Web (render, serverInfoSubsts, timedTTLText)
+import Simplex.Messaging.Transport.Client (TransportHost (..))
+import System.Directory (createDirectoryIfMissing)
+import System.FilePath ((</>))
+
+xftpWebContent :: [(FilePath, ByteString)]
+xftpWebContent = $(embedDir "apps/xftp-server/static/xftp-web-bundle/")
+
+xftpMediaContent :: [(FilePath, ByteString)]
+xftpMediaContent = $(embedDir "apps/xftp-server/static/media/")
+
+xftpFilePageHtml :: ByteString
+xftpFilePageHtml = $(embedFile "apps/xftp-server/static/file.html")
+
+xftpGenerateSite :: XFTPServerConfig s -> Maybe ServerPublicInfo -> Maybe TransportHost -> FilePath -> IO ()
+xftpGenerateSite cfg info onionHost path = do
+  let substs = xftpSubsts cfg info onionHost
+  Web.generateSite embeddedContent (render (Web.indexHtml embeddedContent) substs) [] path
+  let xftpDir = path </> "xftp-web-bundle"
+      mediaDir = path </> "media"
+      fileDir = path </> "file"
+  filePage xftpDir xftpWebContent
+  filePage mediaDir xftpMediaContent
+  createDirectoryIfMissing True fileDir
+  B.writeFile (fileDir </> "index.html") $ render xftpFilePageHtml substs
+  where
+    filePage dir content_ = do
+      createDirectoryIfMissing True dir
+      forM_ content_ $ \(fp, content) -> B.writeFile (dir </> fp) content
+
+xftpServerInformation :: XFTPServerConfig s -> Maybe ServerPublicInfo -> Maybe TransportHost -> ByteString
+xftpServerInformation cfg info onionHost = render (Web.indexHtml embeddedContent) (xftpSubsts cfg info onionHost)
+
+xftpSubsts :: XFTPServerConfig s -> Maybe ServerPublicInfo -> Maybe TransportHost -> [(ByteString, Maybe ByteString)]
+xftpSubsts XFTPServerConfig {fileExpiration, logStatsInterval, allowNewFiles, newFileBasicAuth} information onionHost =
+  [("smpConfig", Nothing), ("xftpConfig", Just "y")] <> substConfig <> serverInfoSubsts simplexmqSource information <> [("onionHost", strEncode <$> onionHost), ("iniFileName", Just "file-server.ini")]
+  where
+    substConfig =
+      [ ("fileExpiration", Just $ maybe "Never" (fromString . timedTTLText . ttl) fileExpiration),
+        ("statsEnabled", Just . yesNo $ isJust logStatsInterval),
+        ("newUploadsAllowed", Just . yesNo $ allowNewFiles),
+        ("basicAuthEnabled", Just . yesNo $ isJust newFileBasicAuth)
+      ]
+    yesNo True = "Yes"
+    yesNo False = "No"

apps/xftp-server/static/media/xftp-protocol-dark.svg

@@ -0,0 +1,115 @@
+<svg width="440" height="520" viewBox="-20 0 440 520" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Sender browser -->
+  <rect x="120" y="16" width="160" height="56" rx="10" stroke="#70F0F9" stroke-width="1.5"/>
+  <text x="200" y="40" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#70F0F9">Sender's browser</text>
+  <text x="200" y="56" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="rgba(112,240,249,0.7)">encrypts file</text>
+
+  <!-- Arrow down from sender to chunks -->
+  <line x1="200" y1="72" x2="200" y2="120" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+
+  <!-- Chunks row -->
+  <rect x="112" y="120" width="176" height="40" rx="8" fill="none" stroke="#70F0F9" stroke-width="1" stroke-dasharray="4 3"/>
+  <text x="200" y="145" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#70F0F9">encrypted chunks</text>
+
+  <!-- Arrows from chunks to routers -->
+  <line x1="152" y1="160" x2="80" y2="220" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+  <line x1="200" y1="160" x2="200" y2="220" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+  <line x1="248" y1="160" x2="320" y2="220" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+
+  <!-- Router 1 (SimpleX) -->
+  <rect x="20" y="220" width="120" height="56" rx="6" fill="none" stroke="#70F0F9" stroke-width="1.5"/>
+  <g transform="translate(28, 227)">
+    <rect width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="6" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="12" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <circle cx="11" cy="2" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="8" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="14" r="1" fill="#70F0F9"/>
+  </g>
+  <text x="80" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#70F0F9">SimpleX</text>
+  <text x="80" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="rgba(112,240,249,0.7)">XFTP router</text>
+
+  <!-- Router 2 (Flux) -->
+  <rect x="155" y="220" width="90" height="56" rx="6" fill="none" stroke="#70F0F9" stroke-width="1.5"/>
+  <g transform="translate(163, 227)">
+    <rect width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="6" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="12" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <circle cx="11" cy="2" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="8" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="14" r="1" fill="#70F0F9"/>
+  </g>
+  <text x="200" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#70F0F9">Flux</text>
+  <text x="200" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="rgba(112,240,249,0.7)">XFTP router</text>
+
+  <!-- Router 3 (SimpleX) -->
+  <rect x="260" y="220" width="120" height="56" rx="6" fill="none" stroke="#70F0F9" stroke-width="1.5"/>
+  <g transform="translate(268, 227)">
+    <rect width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="6" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <rect y="12" width="14" height="4" rx="1" fill="rgba(112,240,249,0.5)"/>
+    <circle cx="11" cy="2" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="8" r="1" fill="#70F0F9"/>
+    <circle cx="11" cy="14" r="1" fill="#70F0F9"/>
+  </g>
+  <text x="320" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#70F0F9">SimpleX</text>
+  <text x="320" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="rgba(112,240,249,0.7)">XFTP router</text>
+
+  <!-- Arrows from routers down -->
+  <line x1="80" y1="276" x2="152" y2="336" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+  <line x1="200" y1="276" x2="200" y2="336" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+  <line x1="320" y1="276" x2="248" y2="336" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+
+  <!-- Re-encrypt label -->
+  <text x="330" y="310" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" fill="rgba(112,240,249,0.7)">re-encrypted</text>
+  <text x="330" y="322" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" fill="rgba(112,240,249,0.7)">per recipient</text>
+
+  <!-- Chunks row (download) -->
+  <rect x="112" y="336" width="176" height="40" rx="8" fill="none" stroke="#70F0F9" stroke-width="1" stroke-dasharray="4 3"/>
+  <text x="200" y="361" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#70F0F9">encrypted chunks</text>
+
+  <!-- Arrow down to recipient -->
+  <line x1="200" y1="376" x2="200" y2="424" stroke="#70F0F9" stroke-width="1.5" marker-end="url(#arrowC)"/>
+
+  <!-- Recipient browser -->
+  <rect x="120" y="424" width="160" height="56" rx="10" stroke="#70F0F9" stroke-width="1.5"/>
+  <text x="200" y="448" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#70F0F9">Recipient's browser</text>
+  <text x="200" y="464" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="rgba(112,240,249,0.7)">decrypts file</text>
+
+  <!-- Key path (dashed, side) -->
+  <path d="M120 44 L8 44 L8 452 L120 452" stroke="#70F0F9" stroke-width="1.5" stroke-dasharray="6 4" fill="none" marker-end="url(#arrowC)"/>
+  <text x="-6" y="240" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#70F0F9" transform="rotate(-90 -6 240)">key in URL fragment - never sent to page server or data router</text>
+
+
+  <!-- Closed padlock: encryption (between sender and chunks) -->
+  <g transform="translate(192, 88)">
+    <path d="M4,7 V4 C4,1.2 12,1.2 12,4 V7" stroke="#60a5fa" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+    <rect x="2" y="7" width="12" height="9" rx="2" fill="#60a5fa"/>
+    <circle cx="8" cy="12" r="1.2" fill="#0B2A59"/>
+  </g>
+
+  <!-- Open padlock: decryption (between chunks and recipient) -->
+  <g transform="translate(192, 392)">
+    <path d="M4,7 V4 C4,1.2 12,1.2 12,4 V2" stroke="#60a5fa" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+    <rect x="2" y="7" width="12" height="9" rx="2" fill="#60a5fa"/>
+    <circle cx="8" cy="12" r="1.2" fill="#0B2A59"/>
+  </g>
+
+  <!-- Key icon on dashed line -->
+  <g transform="translate(8, 410)">
+    <circle cx="0" cy="0" r="6" stroke="#FBBF24" stroke-width="2" fill="#FBBF24"/>
+    <circle cx="0" cy="0" r="2" fill="#0B2A59"/>
+    <line x1="6" y1="0" x2="16" y2="0" stroke="#FBBF24" stroke-width="2"/>
+    <line x1="14" y1="0" x2="14" y2="4" stroke="#FBBF24" stroke-width="2"/>
+    <line x1="11" y1="0" x2="11" y2="3.5" stroke="#FBBF24" stroke-width="2"/>
+  </g>
+
+  <!-- Annotation: no shared IDs -->
+  <text x="200" y="510" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="rgba(112,240,249,0.7)">Each file fragment uses unique anonymous credentials - no shared identifiers</text>
+
+  <defs>
+    <marker id="arrowC" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#70F0F9"/>
+    </marker>
+  </defs>
+</svg>

apps/xftp-server/static/media/xftp-protocol.svg

@@ -0,0 +1,130 @@
+<svg width="440" height="520" viewBox="-20 0 440 520" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Sender browser -->
+  <rect x="120" y="16" width="160" height="56" rx="10" fill="url(#gBox)" stroke="#606C71" stroke-width="1.5"/>
+  <text x="200" y="40" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#fff">Sender's browser</text>
+  <text x="200" y="56" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="rgba(255,255,255,0.8)">encrypts file</text>
+
+  <!-- Arrow down from sender to chunks -->
+  <line x1="200" y1="72" x2="200" y2="120" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+
+  <!-- Chunks row -->
+  <rect x="112" y="120" width="176" height="40" rx="8" fill="#f0f7ff" stroke="#0053D0" stroke-width="1" stroke-dasharray="4 3"/>
+  <text x="200" y="145" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#0053D0">encrypted chunks</text>
+
+  <!-- Arrows from chunks to routers -->
+  <line x1="152" y1="160" x2="80" y2="220" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+  <line x1="200" y1="160" x2="200" y2="220" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+  <line x1="248" y1="160" x2="320" y2="220" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+
+  <!-- Router 1 (SimpleX) -->
+  <rect x="20" y="220" width="120" height="56" rx="6" fill="#f0f4f8" stroke="#606C71" stroke-width="1.5"/>
+  <g transform="translate(28, 227)">
+    <rect width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="6" width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="12" width="14" height="4" rx="1" fill="#606C71"/>
+    <circle cx="11" cy="2" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="8" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="14" r="1" fill="#53C1FF"/>
+  </g>
+  <text x="80" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#3F484B">SimpleX</text>
+  <text x="80" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="#606C71">XFTP router</text>
+
+  <!-- Router 2 (Flux) -->
+  <rect x="155" y="220" width="90" height="56" rx="6" fill="#f0f4f8" stroke="#606C71" stroke-width="1.5"/>
+  <g transform="translate(163, 227)">
+    <rect width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="6" width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="12" width="14" height="4" rx="1" fill="#606C71"/>
+    <circle cx="11" cy="2" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="8" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="14" r="1" fill="#53C1FF"/>
+  </g>
+  <text x="200" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#3F484B">Flux</text>
+  <text x="200" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="#606C71">XFTP router</text>
+
+  <!-- Router 3 (SimpleX) -->
+  <rect x="260" y="220" width="120" height="56" rx="6" fill="#f0f4f8" stroke="#606C71" stroke-width="1.5"/>
+  <g transform="translate(268, 227)">
+    <rect width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="6" width="14" height="4" rx="1" fill="#606C71"/>
+    <rect y="12" width="14" height="4" rx="1" fill="#606C71"/>
+    <circle cx="11" cy="2" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="8" r="1" fill="#53C1FF"/>
+    <circle cx="11" cy="14" r="1" fill="#53C1FF"/>
+  </g>
+  <text x="320" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#3F484B">SimpleX</text>
+  <text x="320" y="258" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="#606C71">XFTP router</text>
+
+  <!-- Arrows from routers down -->
+  <line x1="80" y1="276" x2="152" y2="336" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+  <line x1="200" y1="276" x2="200" y2="336" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+  <line x1="320" y1="276" x2="248" y2="336" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+
+  <!-- Re-encrypt label -->
+  <text x="330" y="310" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" fill="#606C71">re-encrypted</text>
+  <text x="330" y="322" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" fill="#606C71">per recipient</text>
+
+  <!-- Chunks row (download) -->
+  <rect x="112" y="336" width="176" height="40" rx="8" fill="#f0f7ff" stroke="#0053D0" stroke-width="1" stroke-dasharray="4 3"/>
+  <text x="200" y="361" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#0053D0">encrypted chunks</text>
+
+  <!-- Arrow down to recipient -->
+  <line x1="200" y1="376" x2="200" y2="424" stroke="#606C71" stroke-width="1.5" marker-end="url(#arrowG)"/>
+
+  <!-- Recipient browser -->
+  <rect x="120" y="424" width="160" height="56" rx="10" fill="url(#gBox)" stroke="#606C71" stroke-width="1.5"/>
+  <text x="200" y="448" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#fff">Recipient's browser</text>
+  <text x="200" y="464" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="rgba(255,255,255,0.8)">decrypts file</text>
+
+  <!-- Key path (dashed, side) -->
+  <path d="M120 44 L8 44 L8 452 L120 452" stroke="#0053D0" stroke-width="1.5" stroke-dasharray="6 4" fill="none" marker-end="url(#arrowB)"/>
+  <text x="-6" y="240" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#0053D0" transform="rotate(-90 -6 240)">key in URL fragment - never sent to page server or data router</text>
+
+
+  <!-- Closed padlock: encryption (between sender and chunks) -->
+  <g transform="translate(192, 88)">
+    <path d="M4,7 V4 C4,1.2 12,1.2 12,4 V7" stroke="#0053D0" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+    <rect x="2" y="7" width="12" height="9" rx="2" fill="#0053D0"/>
+    <circle cx="8" cy="12" r="1.2" fill="#fff"/>
+  </g>
+
+  <!-- Open padlock: decryption (between chunks and recipient) -->
+  <g transform="translate(192, 392)">
+    <path d="M4,7 V4 C4,1.2 12,1.2 12,4 V2" stroke="#0053D0" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+    <rect x="2" y="7" width="12" height="9" rx="2" fill="#0053D0"/>
+    <circle cx="8" cy="12" r="1.2" fill="#fff"/>
+  </g>
+
+  <!-- Key icon on dashed line -->
+  <g transform="translate(8, 410)">
+    <circle cx="0" cy="0" r="6" stroke="#D97706" stroke-width="2" fill="#D97706"/>
+    <circle cx="0" cy="0" r="2" fill="#fff"/>
+    <line x1="6" y1="0" x2="16" y2="0" stroke="#D97706" stroke-width="2"/>
+    <line x1="14" y1="0" x2="14" y2="4" stroke="#D97706" stroke-width="2"/>
+    <line x1="11" y1="0" x2="11" y2="3.5" stroke="#D97706" stroke-width="2"/>
+  </g>
+
+  <!-- Annotation: no shared IDs -->
+  <text x="200" y="510" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#606C71">Each file fragment uses unique anonymous credentials - no shared identifiers</text>
+
+  <defs>
+    <linearGradient id="gBox" x1="120" y1="16" x2="280" y2="72" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0053D0"/>
+      <stop offset="1" stop-color="#53C1FF"/>
+    </linearGradient>
+    <linearGradient id="gSrv1" x1="20" y1="220" x2="140" y2="276" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0053D0"/>
+      <stop offset="1" stop-color="#53C1FF"/>
+    </linearGradient>
+    <linearGradient id="gSrv2" x1="155" y1="220" x2="245" y2="276" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0053D0"/>
+      <stop offset="1" stop-color="#53C1FF"/>
+    </linearGradient>
+    <marker id="arrowG" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#606C71"/>
+    </marker>
+    <marker id="arrowB" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#0053D0"/>
+    </marker>
+  </defs>
+</svg>

apps/xftp-server/static/xftp-web-bundle/index.css

@@ -0,0 +1,145 @@
+#app, [data-xftp-app] {
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #333;
+  width: 100%;
+  max-width: 480px;
+  padding: 16px;
+  box-sizing: border-box;
+  --xftp-ring-fg: #3b82f6;
+}
+
+:is(#app, [data-xftp-app]) .card {
+  background: #fff;
+  border-radius: 12px;
+  padding: 32px 24px;
+  box-shadow: 0 1px 3px rgba(0,0,0,.1);
+  text-align: center;
+}
+
+:is(#app, [data-xftp-app]) h1 {
+  font-size: 1.25rem;
+  font-weight: 600;
+  margin-bottom: 24px;
+}
+
+:is(#app, [data-xftp-app]) .stage { margin-top: 16px; }
+
+/* Drop zone */
+:is(#app, [data-xftp-app]) .drop-zone {
+  border: 2px dashed #ccc;
+  border-radius: 8px;
+  padding: 32px 16px;
+  transition: border-color .15s, background .15s;
+}
+:is(#app, [data-xftp-app]) .drop-zone.drag-over {
+  border-color: #3b82f6;
+  background: #eff6ff;
+}
+
+/* Buttons */
+:is(#app, [data-xftp-app]) .btn {
+  display: inline-block;
+  padding: 10px 24px;
+  border: none;
+  border-radius: 6px;
+  background: #3b82f6;
+  color: #fff;
+  font-size: .9rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background .15s;
+}
+:is(#app, [data-xftp-app]) .btn:hover { background: #2563eb; }
+:is(#app, [data-xftp-app]) .btn-secondary { background: #6b7280; }
+:is(#app, [data-xftp-app]) .btn-secondary:hover { background: #4b5563; }
+
+/* Hints */
+:is(#app, [data-xftp-app]) .hint { color: #999; font-size: .85rem; margin-top: 8px; }
+:is(#app, [data-xftp-app]) .expiry { margin-top: 12px; }
+
+/* Progress */
+:is(#app, [data-xftp-app]) .progress-ring { display: block; margin: 0 auto 12px; }
+:is(#app, [data-xftp-app]) #upload-status,
+:is(#app, [data-xftp-app]) #dl-status { font-size: .9rem; color: #666; margin-bottom: 12px; }
+
+/* Share link row */
+:is(#app, [data-xftp-app]) .link-row {
+  display: flex;
+  gap: 8px;
+  margin-top: 12px;
+}
+:is(#app, [data-xftp-app]) .link-row input {
+  flex: 1;
+  padding: 8px 10px;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+  font-size: .85rem;
+  background: #f9fafb;
+}
+
+/* Upload link */
+:is(#app, [data-xftp-app]) .upload-link {
+  margin-top: 12px;
+  color: #3b82f6;
+  font-size: .9rem;
+  text-decoration: none;
+  cursor: pointer;
+}
+:is(#app, [data-xftp-app]) .upload-link:not([hidden]) {
+  display: inline-block;
+}
+:is(#app, [data-xftp-app]) .upload-link:hover { text-decoration: underline; }
+
+/* Messages */
+:is(#app, [data-xftp-app]) .success { color: #16a34a; font-weight: 600; }
+:is(#app, [data-xftp-app]) .error { color: #dc2626; font-weight: 500; margin-bottom: 12px; }
+
+/* Security note */
+:is(#app, [data-xftp-app]) .security-note {
+  margin-top: 20px;
+  padding: 12px;
+  background: #f0fdf4;
+  border-radius: 6px;
+  font-size: .8rem;
+  color: #555;
+  text-align: left;
+}
+:is(#app, [data-xftp-app]) .security-note p + p { margin-top: 6px; }
+:is(#app, [data-xftp-app]) .security-note a { color: #3b82f6; text-decoration: none; }
+:is(#app, [data-xftp-app]) .security-note a:hover { text-decoration: underline; }
+
+/* ── Dark mode ─────────────────────────────────── */
+.dark :is(#app, [data-xftp-app]) {
+  color: #e5e7eb;
+  --xftp-ring-bg: #374151;
+  --xftp-ring-fg: #60a5fa;
+  --xftp-ring-text: #e5e7eb;
+  --xftp-ring-done: #4ade80;
+}
+.dark :is(#app, [data-xftp-app]) .card {
+  background: #1f2937;
+  box-shadow: 0 1px 3px rgba(0,0,0,.4);
+}
+.dark :is(#app, [data-xftp-app]) .drop-zone { border-color: #4b5563; }
+.dark :is(#app, [data-xftp-app]) .drop-zone.drag-over {
+  border-color: #60a5fa;
+  background: rgba(59,130,246,.15);
+}
+.dark :is(#app, [data-xftp-app]) .btn-secondary { background: #4b5563; }
+.dark :is(#app, [data-xftp-app]) .btn-secondary:hover { background: #374151; }
+.dark :is(#app, [data-xftp-app]) .hint { color: #9ca3af; }
+.dark :is(#app, [data-xftp-app]) #upload-status,
+.dark :is(#app, [data-xftp-app]) #dl-status { color: #9ca3af; }
+.dark :is(#app, [data-xftp-app]) .link-row input {
+  background: #374151;
+  border-color: #4b5563;
+  color: #e5e7eb;
+}
+.dark :is(#app, [data-xftp-app]) .success { color: #4ade80; }
+.dark :is(#app, [data-xftp-app]) .error { color: #f87171; }
+.dark :is(#app, [data-xftp-app]) .security-note {
+  background: rgba(34,197,94,.1);
+  color: #d1d5db;
+}
+.dark :is(#app, [data-xftp-app]) .upload-link { color: #60a5fa; }
+.dark :is(#app, [data-xftp-app]) .security-note a { color: #60a5fa; }

cabal.project

@@ -4,6 +4,15 @@ packages: .
 -- packages: . ../http2
 -- packages: . ../network-transport
 
+-- uncomment two sections below to run tests with coverage
+-- package *
+   -- coverage: True
+   -- library-coverage: True
+
+-- package attoparsec
+   -- coverage: False
+   -- library-coverage: False
+
 index-state: 2023-12-12T00:00:00Z
 
 package cryptostore
@@ -28,3 +37,17 @@ source-repository-package
     type: git
     location: https://github.com/simplex-chat/sqlcipher-simple.git
     tag: a46bd361a19376c5211f1058908fc0ae6bf42446
+
+-- waiting for published warp-tls-3.4.7
+source-repository-package
+    type: git
+    location: https://github.com/yesodweb/wai.git
+    tag: ec5e017d896a78e787a5acea62b37a4e677dec2e
+    subdir: warp-tls
+
+-- backported fork due http-5.0
+source-repository-package
+    type: git
+    location: https://github.com/simplex-chat/wai.git
+    tag: 2f6e5aa5f05ba9140ac99e195ee647b4f7d926b0
+    subdir: warp

contributing/CODE.md

@@ -0,0 +1,104 @@
+# Coding and building
+
+This file provides guidance on coding style and approaches and on building the code.
+
+## Code Security
+
+When designing code and planning implementations:
+- Apply adversarial thinking, and consider what may happen if one of the communicating parties is malicious.
+- Formulate an explicit threat model for each change - who can do which undesirable things and under which circumstances.
+
+## Code Quality Standards
+
+Haskell client and server code serves as system specification, not just implementation — we use type-driven design to reflect the business domain in types. Quality, conciseness, and clarity of Haskell code are critical.
+
+## Code Style, Formatting and Approaches
+
+The project uses **fourmolu** for Haskell code formatting. Configuration is in `fourmolu.yaml`.
+
+**Key formatting rules:**
+- 2-space indentation
+- Trailing function arrows, commas, and import/export style
+- Record brace without space: `{field = value}`
+- Single newline between declarations
+- Never use unicode symbols
+- Inline `let` style with right-aligned `in`
+
+**Format code before committing:**
+
+```bash
+# Format a single file
+fourmolu -i src/Simplex/Messaging/Protocol.hs
+```
+
+Some files that use CPP language extension cannot be formatted as a whole, so individual code fragments need to be formatted.
+
+**Follow existing code patterns:**
+- Match the style of surrounding code
+- Use qualified imports with short aliases (e.g., `import qualified Data.ByteString.Char8 as B`)
+- Use record syntax for types with multiple fields
+- Prefer explicit pattern matching over partial functions
+
+**Comments policy:**
+- Avoid redundant comments that restate what the code already says
+- Only comment on non-obvious design decisions or tricky implementation details
+- Function names and type signatures should be self-documenting
+- Do not add comments like "wire format encoding" (Encoding class is always wire format) or "check if X" when the function name already says that
+- Assume a competent Haskell reader
+
+**Diff and refactoring:**
+- Avoid unnecessary changes and code movements
+- Never do refactoring unless it substantially reduces cost of solving the current problem, including the cost of refactoring
+- Aim to minimize the code changes - do what is minimally required to solve users' problems
+
+**Document and code structure:**
+- **Never move existing code or sections around** - add new content at appropriate locations without reorganizing existing structure.
+- When adding new sections to documents, continue the existing numbering scheme.
+- Minimize diff size - prefer small, targeted changes over reorganization.
+
+**Code analysis and review:**
+- Trace data flows end-to-end: from origin, through storage/parameters, to consumption. Flag values that are discarded and reconstructed from partial data (e.g. extracted from a URI missing original fields) — this is usually a bug.
+- Read implementations of called functions, not just signatures — if duplication involves a called function, check whether decomposing it resolves the duplication.
+- Do not save time on analysis. Read every function in the data flow even when the interface seems clear — wrong assumptions about internals are the main source of missed bugs.
+
+### Haskell Extensions
+- `StrictData` enabled by default
+- Use STM for safe concurrency
+- Assume concurrency in PostgreSQL queries
+- Comprehensive warning flags with strict pattern matching
+
+## Build Commands
+
+```bash
+# Standard build
+cabal build
+
+# Fast build
+cabal build --ghc-options -O0
+
+# Build specific executables
+cabal build exe:smp-server exe:xftp-server exe:ntf-server exe:xftp
+
+# Build with PostgreSQL server support
+cabal build -fserver_postgres
+
+# Client-only library build (no server code)
+cabal build -fclient_library
+
+# Find binary location
+cabal list-bin exe:smp-server
+```
+
+### Cabal Flags
+
+- `swift`: Enable Swift JSON format
+- `client_library`: Build without server code
+- `client_postgres`: Use PostgreSQL instead of SQLite for agent persistence
+- `server_postgres`: PostgreSQL support for server queue/notification store
+
+## External Dependencies
+
+Custom forks specified in `cabal.project`:
+- `aeson`, `hs-socks` (SimpleX forks)
+- `direct-sqlcipher`, `sqlcipher-simple` (encrypted SQLite)
+- `warp`, `warp-tls` (HTTP server)

contributing/PROJECT.md

@@ -0,0 +1,105 @@
+# SimpleXMQ repository
+
+This file provides guidance on the project structure to help working with code in this repository.
+
+## Project Overview
+
+SimpleXMQ is a Haskell message broker implementing unidirectional (simplex) queues for privacy-preserving messaging. 
+
+Key components:
+
+- **SimpleX Messaging Protocol**: SMP protocol definition and encodings ([code](../src/Simplex/Messaging/Protocol.hs), [transport code](../src/Simplex/Messaging/Transport.hs), [spec](../protocol/simplex-messaging.md)).
+- **SMP Server**: Message broker with TLS, in-memory queues, optional persistence ([main code](../src/Simplex/Messaging/Server.hs), [all code files](../src/Simplex/Messaging/Server/), [executable](../apps/smp-server/)). For proxying SMP commands the server uses [lightweight SMP client](../src/Simplex/Messaging/Client/Agent.hs).
+- **SMP Client**: Functional API with STM-based message delivery ([code](../src/Simplex/Messaging/Client.hs)).
+- **SMP Agent**: High-level duplex connections via multiple simplex queues with E2E encryption ([code](../src/Simplex/Messaging/Agent.hs)). Implements Agent-to-agent protocol ([code](../src/Simplex/Messaging/Agent/Protocol.hs), [spec](../protocol/agent-protocol.md)) via intermediary agent client ([code](../src/Simplex/Messaging/Agent/Client.hs)).
+- **XFTP**: SimpleX File Transfer Protocol, server and CLI client ([code](../src/Simplex/FileTransfer/), [spec](../protocol/xftp.md)).
+- **XRCP**: SimpleX Remote Control Protocol ([code](`../src/Simplex/RemoteControl/`), [spec](../protocol/xrcp.md)).
+- **Notifications**: Push notifications server requires PostgreSQL ([code](../src/Simplex/Messaging/Notifications), [executable](../apps/ntf-server/)). Client protocol is used for clients to communicate with the server ([code](../src/Simplex/Messaging/Notifications/Protocol.hs), [spec](../protocol/push-notifications.md)). For subscribing to SMP notifications the server uses [lightweight SMP client](../src/Simplex/Messaging/Client/Agent.hs).
+
+## Architecture
+
+For general overview see `../protocol/overview-tjr.md`.
+
+SMP Protocol Layers:
+
+```
+TLS Transport → SMP Protocol → Agent Protocol → Application protocol
+```
+
+XFTP Protocol Layers:
+
+```
+TLS Transport (HTTP2 encoding) → XFTP Protocol → Out-of-band file descriptions
+```
+
+## Key Patterns
+
+1. **Persistence**: All queue state managed via Software Transactional Memory or via PostgreSQL
+   - `Simplex.Messaging.Server.MsgStore.STM` - in-memory messages
+   - `Simplex.Messaging.Server.QueueStore.STM` - in-memory queue state
+   - `Simplex.Messaging.Server.MsgStore.Postgres` - message storage
+   - `Simplex.Messaging.Server.QueueStore.Postgres` - queue storage
+
+2. **Append-Only Store Log**: Optional persistence via journal for in-memory storage
+   - `Simplex.Messaging.Server.StoreLog` - queue creation log
+   - Compacted on restart
+
+3. **Agent Storage**:
+   - SQLite (default) or PostgreSQL
+   - Migrations in `src/Simplex/Messaging/Agent/Store/{SQLite,Postgres}/Migrations/`
+
+4. **Protocol Versioning**: All layers support version negotiation
+   - `Simplex.Messaging.Version` - version range utilities
+
+5. **Double Ratchet E2E**: Per-connection encryption
+   - `Simplex.Messaging.Crypto.Ratchet`
+   - SNTRUP761 post-quantum KEM (`src/Simplex/Messaging/Crypto/SNTRUP761/`)
+
+## Source Layout
+
+```
+src/Simplex/
+├── Messaging/
+│   ├── Agent.hs          # Main agent (~210KB)
+│   ├── Server.hs         # SMP server (~130KB)
+│   ├── Client.hs         # Client API (~65KB)
+│   ├── Protocol.hs       # Protocol types (~77KB)
+│   ├── Crypto.hs         # E2E encryption (~52KB)
+│   ├── Transport.hs      # Transport encoding over TLS
+│   ├── Agent/Store/      # SQLite/Postgres persistence
+│   ├── Server/           # Server internals (QueueStore, MsgStore, Control)
+│   └── Notifications/    # Push notification system
+├── FileTransfer/         # XFTP implementation for file transfers
+└── RemoteControl/        # XRCP implementation for device discovery & control
+```
+
+## Protocol Documentation
+
+- `protocol/overview-tjr.md`: SMP protocols stack overview
+- `protocol/simplex-messaging.md`: SMP protocol spec (v19)
+- `protocol/agent-protocol.md`: Agent protocol spec (v7)
+- `protocol/xftp.md`: File transfer protocol
+- `protocol/xrcp.md`: Remote control protocol
+- `rfcs/`: Design RFCs for features
+
+## Testing
+
+```bash
+# Run all tests
+cabal test --test-show-details=streaming
+
+# Run specific test group (uses HSpec)
+cabal test --test-option=--match="/Core tests/Encryption tests/"
+
+# Run single test
+cabal test --test-option=--match="/SMP client agent/functional API/"
+```
+
+Tests require PostgreSQL running on `localhost:5432` when using `-fserver_postgres` or `-fclient_postgres`.
+
+Test files are in `tests/` with structure:
+- `Test.hs`: Main runner
+- `AgentTests/`: Agent protocol and connection tests
+- `CoreTests/`: Crypto, encoding, storage tests
+- `ServerTests.hs`: SMP server tests
+- `XFTPServerTests.hs`: File transfer tests

contributing/README.md

@@ -0,0 +1,23 @@
+# Contributing to SimpleX repositories
+
+## Focus on user problems
+
+We do not make code changes to improve code - any change must address a specific user problem or request.
+
+## Discuss the plans as early as possible
+
+Please discuss the problem you want to solve and your detailed implementation plan with the project team prior to contributing, to avoid wasted time and additional changes. Acceptance of your contribution depends on your willingness and ability to iterate the proposed contribution to achieve the required quality level, coding style, test coverage, and alignment with user requirements as they are understood by the project team.
+
+## Follow project structure, coding style and approaches
+
+./PROJECT.md has information about the structure of this `simplexmq` repository.
+
+./CODE.md has details about general requirements common for `simplexmq` and `simplex-chat` repositories.
+
+This files can be used with LLM prompts, e.g. if you use Claude Code you can create CLAUDE.md file in project root importing content from these files:
+
+```markdown
+@README.md
+@contributing/PROJECT.md
+@contributing/CODE.md
+```

install.sh

@@ -2,9 +2,6 @@
 set -eu
 
 # Links to scripts/configs
-bin="https://github.com/simplex-chat/simplexmq/releases/latest/download"
-remote_version="$(curl --proto '=https' --tlsv1.2 -sSf -L https://api.github.com/repos/simplex-chat/simplexmq/releases/latest | grep -i "tag_name" | awk -F \" '{print $4}')"
-
 scripts="https://raw.githubusercontent.com/simplex-chat/simplexmq/stable/scripts/main"
 scripts_systemd_smp="$scripts/smp-server.service"
 scripts_systemd_xftp="$scripts/xftp-server.service"
@@ -57,7 +54,7 @@ ${GRN}1.${NC} Install latest binaries from GitHub releases:
 ${GRN}2.${NC} Create server directories:
     - smp: ${YLW}${path_conf_smp}${NC}
     - xftp: ${YLW}${path_conf_xftp}${NC}
-${GRN}3.${NC} Setup user for each server:
+${GRN}3.${NC} Setup user for server:
     - xmp: ${YLW}${user_smp}${NC}
     - xftp: ${YLW}${user_xftp}${NC}
 ${GRN}4.${NC} Create systemd services:
@@ -67,9 +64,8 @@ ${GRN}5.${NC} Install stopscript (systemd), update and uninstallation script:
     - all: ${YLW}${path_bin_update}${NC}, ${YLW}${path_bin_uninstall}${NC}, ${YLW}${path_bin_stopscript}${NC}
 
 Press:
-  - ${GRN}ENTER${NC} to continue installing both xftp and smp servers
-  - ${GRN}1${NC} to install only smp server
-  - ${GRN}2${NC} to install only xftp server
+  - ${GRN}1${NC} to install smp server
+  - ${GRN}2${NC} to install xftp server
   - ${RED}Ctrl+C${NC} to cancel installation
   
 Selection: "
@@ -83,6 +79,21 @@ Please checkout our server guides:
 To uninstall with full clean-up, simply run: ${YLW}sudo /usr/local/bin/simplex-servers-uninstall${NC}
 "
 
+set_version() {
+  ver="${VER:-latest}"
+
+  case "$ver" in 
+    latest)
+      bin="https://github.com/simplex-chat/simplexmq/releases/latest/download"
+      remote_version="$(curl --proto '=https' --tlsv1.2 -sSf -L https://api.github.com/repos/simplex-chat/simplexmq/releases/latest | grep -i "tag_name" | awk -F \" '{print $4}')"
+      ;;
+    *)
+      bin="https://github.com/simplex-chat/simplexmq/releases/download/${ver}"
+      remote_version="${ver}"
+      ;;
+  esac
+}
+
 os_test() {
  . /etc/os-release
 
@@ -155,6 +166,7 @@ checks() {
   exit 1
  fi
  
+ set_version
  os_test
 
  mkdir -p $path_conf_info  
@@ -166,13 +178,11 @@ main() {
  printf "%b\n%b" "${BLU}$logo${NC}" "$welcome"
  read ans
 
- if [ "$ans" = '1' ]; then
-  setup='smp'
- elif [ "$ans" = '2' ]; then
-  setup='xftp'
- else
-  setup='smp xftp'
- fi
+ case "$ans" in
+  1) setup='smp' ;;
+  2) setup='xftp' ;;
+  *) printf 'Installation aborted.\n' && exit 0 ;;
+ esac
 
  printf "Installing binaries..."
  

notes-flow.txt

@@ -1,23 +0,0 @@
-common:
-  corrId - random BS, used as CbNonce
-  entityId - p2r tlsUniq
-
-# setup
-s->p: "proxy", uri, auth?
-  # unless connected
-  p->r: "p_handshake"
-  p<-r: "r_key", tls-signed dh pub
-s<-r: "r_key", tls-signed dh pub # reply entityId contains tlsUniq
-
-# working
-s ; generate random dh priv, make shared secret
-s->p: s2r("forward", random dh pub, SEND command blob)
-  p->r: p2r("forward", random dh pub, s2r("forward", ...)))
-    r->c@ "msg", ...
-  p<-r: p2r("r_res", s2r("ok" / "error", error))
-s<-p@ s2r("ok" / "error", error)
-
-# expired
-  p<-r@ p2r("error", "key expired")
-s<-p@ "error", "key expired"
-s ; reconnect

package.yaml

@@ -1,211 +0,0 @@
-name: simplexmq
-version: 6.0.3.0
-synopsis: SimpleXMQ message broker
-description: |
-  This package includes <./docs/Simplex-Messaging-Server.html server>,
-  <./docs/Simplex-Messaging-Client.html client> and
-  <./docs/Simplex-Messaging-Agent.html agent> for SMP protocols:
-  .
-  * <https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md SMP protocol>
-  * <https://github.com/simplex-chat/simplexmq/blob/master/protocol/agent-protocol.md SMP agent protocol>
-  .
-  See <https://github.com/simplex-chat/simplex-chat terminal chat prototype> built with SimpleXMQ broker.
-
-homepage: https://github.com/simplex-chat/simplexmq#readme
-license: AGPL-3
-author: simplex.chat
-maintainer: chat@simplex.chat
-copyright: 2020-2022 simplex.chat
-category: Chat, Network, Web, System, Cryptography
-extra-source-files:
-  - README.md
-  - CHANGELOG.md
-  - cbits/sha512.h
-  - cbits/sntrup761.h
-  - apps/smp-server/static/*.html
-  - apps/smp-server/static/media/*
-
-dependencies:
-  - aeson == 2.2.*
-  - ansi-terminal >= 0.10 && < 0.12
-  - asn1-encoding == 0.9.*
-  - asn1-types == 0.3.*
-  - async == 2.2.*
-  - attoparsec == 0.14.*
-  - base >= 4.14 && < 5
-  - base64-bytestring >= 1.0 && < 1.3
-  - case-insensitive == 1.2.*
-  - composition == 1.0.*
-  - constraints >= 0.12 && < 0.14
-  - containers == 0.6.*
-  - crypton == 0.34.*
-  - crypton-x509 == 1.7.*
-  - crypton-x509-store == 1.6.*
-  - crypton-x509-validation == 1.6.*
-  - cryptostore == 0.3.*
-  - data-default == 0.7.*
-  - direct-sqlcipher == 2.3.*
-  - directory == 1.3.*
-  - filepath == 1.4.*
-  - hourglass == 0.2.*
-  - http-types == 0.12.*
-  - http2 >= 4.2.2 && < 4.3
-  - ini == 0.4.1
-  - iproute == 1.7.*
-  - iso8601-time == 0.1.*
-  - memory == 0.18.*
-  - mtl >= 2.3.1 && < 3.0
-  - network >= 3.1.2.7 && < 3.2
-  - network-info >= 0.2 && < 0.3
-  - network-transport == 0.5.6
-  - network-udp >= 0.0 && < 0.1
-  - optparse-applicative >= 0.15 && < 0.17
-  - process == 1.6.*
-  - random >= 1.1 && < 1.3
-  - simple-logger == 0.1.*
-  - socks == 0.6.*
-  - sqlcipher-simple == 0.4.*
-  - stm == 2.5.*
-  - temporary == 1.3.*
-  - time == 1.12.*
-  - time-manager == 0.0.*
-  - tls >= 1.9.0 && < 1.10
-  - transformers == 0.6.*
-  - unliftio == 0.2.*
-  - unliftio-core == 0.2.*
-  - websockets == 0.12.*
-  - yaml == 0.11.*
-  - zstd == 0.1.3.*
-
-flags:
-  swift:
-    description: Enable swift JSON format
-    manual: True
-    default: False
-  use_crypton:
-    description: Use crypton etc. in cryptostore
-    manual: True
-    default: True
-
-# cpp-options:
-#   - -Dslow_servers
-
-when:
-  - condition: flag(swift)
-    cpp-options:
-      - -DswiftJSON
-  - condition: impl(ghc >= 9.6.2)
-    dependencies:
-      - bytestring == 0.11.*
-      - template-haskell == 2.20.*
-      - text >= 2.0.1 && < 2.2
-  - condition: impl(ghc < 9.6.2)
-    dependencies:
-      - bytestring == 0.10.*
-      - template-haskell == 2.16.*
-      - text >= 1.2.3.0 && < 1.3
-
-library:
-  source-dirs: src
-  c-sources:
-    - cbits/sha512.c
-    - cbits/sntrup761.c
-  include-dirs: cbits
-  extra-libraries: crypto
-
-executables:
-  smp-server:
-    source-dirs:
-    - apps/smp-server
-    - apps/smp-server/web
-    main: Main.hs
-    dependencies:
-      - file-embed
-      - simplexmq
-      - wai-app-static
-      - warp
-      - warp-tls
-    ghc-options:
-      - -threaded
-      - -rtsopts
-
-  ntf-server:
-    source-dirs: apps/ntf-server
-    main: Main.hs
-    dependencies:
-      - simplexmq
-    ghc-options:
-      - -threaded
-      - -rtsopts
-
-  xftp-server:
-    source-dirs: apps/xftp-server
-    main: Main.hs
-    dependencies:
-      - simplexmq
-    ghc-options:
-      - -threaded
-      - -rtsopts
-
-  xftp:
-    source-dirs: apps/xftp
-    main: Main.hs
-    dependencies:
-      - simplexmq
-    ghc-options:
-      - -threaded
-      - -rtsopts
-
-tests:
-  simplexmq-test:
-    source-dirs: tests
-    main: Test.hs
-    dependencies:
-      - simplexmq
-      - deepseq == 1.4.*
-      - generic-random == 1.5.*
-      - hspec == 2.11.*
-      - hspec-core == 2.11.*
-      - HUnit == 1.6.*
-      - QuickCheck == 2.14.*
-      - silently == 1.2.*
-      - main-tester == 0.2.*
-      - timeit == 2.0.*
-    ghc-options:
-      - -threaded
-      - -rtsopts
-      - -with-rtsopts=-A64M
-      - -with-rtsopts=-N1
-
-ghc-options:
-  # - -haddock
-  - -Weverything
-  - -Wno-missing-exported-signatures
-  - -Wno-missing-import-lists
-  - -Wno-missed-specialisations
-  - -Wno-all-missed-specialisations
-  - -Wno-unsafe
-  - -Wno-safe
-  - -Wno-missing-local-signatures
-  - -Wno-missing-kind-signatures
-  - -Wno-missing-deriving-strategies
-  - -Wno-monomorphism-restriction
-  - -Wno-prepositive-qualified-module
-  - -Wno-unused-packages
-  - -Wno-implicit-prelude
-  - -Wno-missing-safe-haskell-mode
-  - -Wno-missing-export-lists
-  - -Wno-partial-fields
-  - -Wcompat
-  - -Werror=incomplete-record-updates
-  - -Werror=incomplete-patterns
-  - -Werror=incomplete-uni-patterns
-  - -Werror=missing-methods
-  - -Werror=tabs
-  - -Wredundant-constraints
-  - -Wincomplete-record-updates
-  - -Wunused-type-patterns
-  - -O2
-
-default-extensions:
-  - StrictData

plans/2026-03-25-xftp-postgres-backend-design.md

@@ -0,0 +1,472 @@
+# XFTP Server PostgreSQL Backend
+
+## Overview
+
+Add PostgreSQL backend support to xftp-server, following the SMP server pattern. Supports bidirectional migration between STM (in-memory with StoreLog) and PostgreSQL backends.
+
+## Goals
+
+- PostgreSQL-backed file metadata storage as an alternative to STM + StoreLog
+- Polymorphic server code via `FileStoreClass` typeclass with IO-based methods (following `QueueStoreClass` pattern)
+- Bidirectional migration: StoreLog <-> PostgreSQL via CLI commands
+- Shared `server_postgres` cabal flag (same flag enables both SMP and XFTP Postgres support)
+- INI-based backend selection at runtime
+
+## Architecture
+
+### FileStoreClass Typeclass
+
+IO-based typeclass following the `QueueStoreClass` pattern — each method is a self-contained IO action, with the implementation responsible for its own atomicity (STM backend wraps in `atomically`, Postgres backend uses database transactions):
+
+```haskell
+class FileStoreClass s where
+  type FileStoreConfig s
+
+  -- Lifecycle
+  newFileStore :: FileStoreConfig s -> IO s
+  closeFileStore :: s -> IO ()
+
+  -- File operations
+  addFile :: s -> SenderId -> FileInfo -> RoundedFileTime -> ServerEntityStatus -> IO (Either XFTPErrorType ())
+  setFilePath :: s -> SenderId -> FilePath -> IO (Either XFTPErrorType ())
+  addRecipient :: s -> SenderId -> FileRecipient -> IO (Either XFTPErrorType ())
+  getFile :: s -> SFileParty p -> XFTPFileId -> IO (Either XFTPErrorType (FileRec, C.APublicAuthKey))
+  deleteFile :: s -> SenderId -> IO (Either XFTPErrorType ())
+  blockFile :: s -> SenderId -> BlockingInfo -> Bool -> IO (Either XFTPErrorType ())
+  deleteRecipient :: s -> RecipientId -> FileRec -> IO ()
+  ackFile :: s -> RecipientId -> IO (Either XFTPErrorType ())
+
+  -- Expiration (with LIMIT for Postgres; called in a loop until empty)
+  expiredFiles :: s -> Int64 -> Int -> IO [(SenderId, Maybe FilePath, Word32)]
+
+  -- Storage and stats (for init-time computation)
+  getUsedStorage :: s -> IO Int64
+  getFileCount :: s -> IO Int
+```
+
+- STM backend: each method wraps its STM transaction in `atomically` internally.
+- Postgres backend: each method runs its query via `withDB` / database connection internally.
+
+No polymorphic monad or `runStore` dispatcher needed — unlike `MsgStoreClass`, XFTP file operations are individually atomic and don't require grouping multiple operations into backend-dependent transactions.
+
+### PostgresFileStore Data Type
+
+```haskell
+data PostgresFileStore = PostgresFileStore
+  { dbStore :: DBStore,
+    dbStoreLog :: Maybe (StoreLog 'WriteMode)
+  }
+```
+
+- `dbStore` — connection pool created via `createDBStore`, runs schema migrations on init.
+- `dbStoreLog` — optional parallel log file (enabled by `db_store_log` INI setting). When present, every mutation (`addFile`, `setFilePath`, `deleteFile`, `blockFile`, `addRecipient`, `ackFile`) also writes to this log via a `withLog` wrapper. `withLog` is called AFTER the DB operation succeeds (so the log reflects committed state only). Log write failures are non-fatal (logged as warnings, do not fail the DB operation). This provides an audit trail and enables recovery via export.
+
+`closeFileStore` for Postgres calls `closeDBStore` (closes connection pool) then `mapM_ closeStoreLog dbStoreLog` (flushes and closes the parallel log). For STM, it closes the storeLog. Called from a `finally` block during server shutdown, matching SMP's `stopServer` → `closeMsgStore` → `closeQueueStore` pattern.
+
+### STMFileStore Type
+
+After extracting from current `Store.hs`, `STMFileStore` retains the file and recipient maps but no longer owns `usedStorage` (moved to `XFTPEnv`):
+
+```haskell
+data STMFileStore = STMFileStore
+  { files :: TMap SenderId FileRec,
+    recipients :: TMap RecipientId (SenderId, RcvPublicAuthKey)
+  }
+```
+
+`closeFileStore` for STM is a no-op (TMaps are garbage-collected; the env-level `storeLog` is closed separately by the server).
+
+### Error Handling
+
+Postgres operations follow SMP's `withDB` / `handleDuplicate` pattern:
+
+```haskell
+withDB :: Text -> PostgresFileStore -> (DB.Connection -> IO (Either XFTPErrorType a)) -> ExceptT XFTPErrorType IO a
+withDB op st action =
+  ExceptT $ E.try (withTransaction (dbStore st) action) >>= either logErr pure
+  where
+    logErr :: E.SomeException -> IO (Either XFTPErrorType a)
+    logErr e = logError ("STORE: " <> err) $> Left INTERNAL
+      where
+        err = op <> ", withDB, " <> tshow e
+
+handleDuplicate :: SqlError -> IO (Either XFTPErrorType a)
+handleDuplicate e = case constraintViolation e of
+  Just (UniqueViolation _) -> pure $ Left DUPLICATE_
+  _ -> E.throwIO e
+```
+
+- All DB operations wrapped in `withDB` — catches exceptions, logs, returns `INTERNAL`.
+- Unique constraint violations caught by `handleDuplicate` and mapped to `DUPLICATE_`.
+- UPDATE operations verified with `assertUpdated` — returns `AUTH` if 0 rows affected (matching SMP pattern, prevents silent failures when WHERE clause doesn't match).
+- Critical sections (DB write + TVar update) wrapped in `uninterruptibleMask_` to prevent async exceptions from leaving inconsistent state between DB and TVars.
+
+### FileRec and TVar Fields
+
+`FileRec` retains its `TVar` fields (matching SMP's `PostgresQueue` pattern):
+
+```haskell
+data FileRec = FileRec
+  { senderId :: SenderId,
+    fileInfo :: FileInfo,
+    filePath :: TVar (Maybe FilePath),
+    recipientIds :: TVar (Set RecipientId),
+    createdAt :: RoundedFileTime,
+    fileStatus :: TVar ServerEntityStatus
+  }
+```
+
+- **STM backend**: TVars are the source of truth, as currently.
+- **Postgres backend**: `getFile` reads from DB and creates a `FileRec` with fresh TVars populated from the DB row (matching SMP's `mkQ` pattern — `newTVarIO` per load). Mutation methods (`setFilePath`, `blockFile`, etc.) update both the DB (persistence) and the TVars (in-session consistency). The `recipientIds` TVar is initialized to `S.empty` — no subquery needed because no server code reads `recipientIds` directly; all recipient operations go through the typeclass methods (`addRecipient`, `deleteRecipient`, `ackFile`), which query the `recipients` table for Postgres.
+
+### usedStorage Ownership
+
+`usedStorage :: TVar Int64` moves from the store to `XFTPEnv`. The store typeclass does **not** manage `usedStorage` — it only provides `getUsedStorage` for init-time computation.
+
+- **STM init**: StoreLog replay calls `setFilePath` (which only sets the filePath TVar — the STM `setFilePath` implementation is changed to **not** update `usedStorage`). Similarly, STM `deleteFile` (Store.hs line 117) and `blockFile` (line 125) are changed to **not** update `usedStorage` — the server handles all `usedStorage` adjustments externally. After replay, `getUsedStorage` computes the sum over all file sizes (matching current `countUsedStorage` behavior).
+- **Postgres init**: `getUsedStorage` executes `SELECT COALESCE(SUM(file_size), 0) FROM files`.
+- **Runtime**: Server manages `usedStorage` TVar directly for reserve/commit/rollback during uploads, and adjusts after `deleteFile`/`blockFile` calls.
+
+**Note on `getUsedStorage` semantics**: The current STM `countUsedStorage` sums all file sizes unconditionally (including files without `filePath` set, i.e., created but not yet uploaded). The Postgres `getUsedStorage` matches this: `SELECT SUM(file_size) FROM files` (no `WHERE file_path IS NOT NULL`). In practice, orphaned files (created but never uploaded) are rare and short-lived (expired within 48h), so the difference is negligible. A future improvement could filter by `file_path IS NOT NULL` in both backends to reflect actual disk usage more accurately.
+
+### Server.hs Refactoring
+
+`Server.hs` becomes polymorphic over `FileStoreClass s`. Since all typeclass methods are IO, call sites replace `atomically` with direct IO calls to the store.
+
+**Call sites requiring changes** (exhaustive list):
+
+1. **`receiveServerFile`** (line 563): `atomically $ writeTVar filePath (Just fPath)` → `setFilePath store senderId fPath`. The `reserve` logic (line 551-555) stays as direct TVar manipulation on `usedStorage` from `XFTPEnv`.
+
+2. **`verifyXFTPTransmission`** (line 453): `atomically $ verify =<< getFile st party fId` — the `getFile` call and subsequent `readTVar fileStatus` are in a single `atomically` block. Refactored to: `getFile st party fId` (IO), then `readTVarIO (fileStatus fr)` from the returned `FileRec` (safe for both backends — STM TVar is the source of truth, Postgres TVar is a fresh snapshot from DB).
+
+3. **`retryAdd`** (line 516): Signature `XFTPFileId -> STM (Either XFTPErrorType a)` → `XFTPFileId -> IO (Either XFTPErrorType a)`. The `atomically` call (line 520) replaced with `liftIO`.
+
+4. **`deleteOrBlockServerFile_`** (line 620): Parameter `FileStore -> STM (Either XFTPErrorType ())` → `FileStoreClass s => s -> IO (Either XFTPErrorType ())`. The `atomically` call (line 626) removed — the store method is already IO. After the store action, server adjusts `usedStorage` TVar in `XFTPEnv` based on `fileInfo.size`.
+
+5. **`ackFileReception`** (line 605): `atomically $ deleteRecipient st rId fr` → `deleteRecipient st rId fr`.
+
+6. **Control port `CPDelete`/`CPBlock`** (lines 371, 377): `atomically $ getFile fs SFRecipient fileId` → `getFile fs SFRecipient fileId`.
+
+7. **`expireServerFiles`** (line 636): Replace per-file `expiredFilePath` iteration with batched `expiredFiles st old batchSize`, which returns `[(SenderId, Maybe FilePath, Word32)]` — the `Word32` file size is needed so the server can adjust the `usedStorage` TVar after each deletion. Called in a loop until the returned list is empty. The `itemDelay` between files applies to the deletion loop over each batch, not the query itself. STM backend ignores the batch size limit (returns all expired files from TMap scan); Postgres uses `LIMIT`.
+
+8. **`restoreServerStats`** (line 694): `FileStore {files, usedStorage} <- asks store` accesses store fields directly. Refactored to: `usedStorage` from `XFTPEnv` via `asks usedStorage`, file count via `getFileCount store`. STM: `M.size <$> readTVarIO files`. Postgres: `SELECT COUNT(*) FROM files`.
+
+### Store Config Selection
+
+GADT in `Env.hs`:
+
+```haskell
+data XFTPStoreConfig s where
+  XSCMemory :: Maybe FilePath -> XFTPStoreConfig STMFileStore
+#if defined(dbServerPostgres)
+  XSCDatabase :: PostgresFileStoreCfg -> XFTPStoreConfig PostgresFileStore
+#endif
+```
+
+`XFTPEnv` becomes polymorphic:
+
+```haskell
+data XFTPEnv s = XFTPEnv
+  { config :: XFTPServerConfig,
+    store :: s,
+    usedStorage :: TVar Int64,
+    storeLog :: Maybe (StoreLog 'WriteMode),
+    ...
+  }
+```
+
+The `M` monad (`ReaderT (XFTPEnv s) IO`) and all functions in `Server.hs` gain `FileStoreClass s =>` constraints.
+
+**StoreLog lifecycle per backend:**
+
+- **STM mode**: `storeLog = Just sl` (current behavior — append-only log for persistence and recovery).
+- **Postgres mode**: `storeLog = Nothing` (main storeLog disabled — Postgres is the source of truth). The optional parallel `dbStoreLog` inside `PostgresFileStore` provides audit/recovery if enabled via `db_store_log` INI setting.
+
+The existing `withFileLog` pattern in Server.hs continues to work unchanged — it maps over `Maybe (StoreLog 'WriteMode)`, which is `Nothing` in Postgres mode so the calls become no-ops.
+
+### Main.hs Store Type Dispatch
+
+The `Start` CLI command gains a `--confirm-migrations` flag (default `MCConsole` — manual prompt, matching SMP's `StartOptions`). For automated deployments, `--confirm-migrations up` auto-applies forward migrations. The import command uses `MCYesUp` (always auto-apply).
+
+Following SMP's existential dispatch pattern (`AStoreType` + `run`), `Main.hs` selects the store type from INI config and dispatches to the polymorphic server:
+
+```haskell
+runServer ini = do
+  let storeType = fromRight "memory" $ lookupValue "STORE_LOG" "store_files" ini
+  case storeType of
+    "memory" -> run $ XSCMemory (enableStoreLog $> storeLogFilePath)
+    "database" ->
+#if defined(dbServerPostgres)
+      run $ XSCDatabase PostgresFileStoreCfg {..}
+#else
+      exitError "server not compiled with Postgres support"
+#endif
+    _ -> exitError $ "Invalid store_files value: " <> storeType
+  where
+    run :: FileStoreClass s => XFTPStoreConfig s -> IO ()
+    run storeCfg = do
+      env <- newXFTPServerEnv storeCfg config
+      runReaderT (xftpServer config) env
+```
+
+**`newXFTPServerEnv` refactored signature:**
+
+```haskell
+newXFTPServerEnv :: FileStoreClass s => XFTPStoreConfig s -> XFTPServerConfig -> IO (XFTPEnv s)
+newXFTPServerEnv storeCfg config = do
+  (store, storeLog) <- case storeCfg of
+    XSCMemory storeLogPath -> do
+      st <- newFileStore ()
+      sl <- mapM (`readWriteFileStore` st) storeLogPath
+      pure (st, sl)
+    XSCDatabase dbCfg -> do
+      st <- newFileStore dbCfg
+      pure (st, Nothing)  -- main storeLog disabled for Postgres
+  usedStorage <- newTVarIO =<< getUsedStorage store
+  ...
+  pure XFTPEnv {config, store, usedStorage, storeLog, ...}
+```
+
+### Startup Config Validation
+
+Following SMP's `checkMsgStoreMode` pattern, `Main.hs` validates config before starting:
+
+- **`store_files=database` + StoreLog file exists** (without `db_store_log=on`): Error — "StoreLog file present but store_files is `database`. Use `xftp-server database import` to migrate, or set `db_store_log: on`."
+- **`store_files=database` + schema doesn't exist**: Error — "Create schema in PostgreSQL or use `xftp-server database import`."
+- **`store_files=memory` + Postgres schema exists**: Warning — "Postgres schema exists but store_files is `memory`. Data in Postgres will not be used."
+- **Binary compiled without `server_postgres` + `store_files=database`**: Error — "Server not compiled with Postgres support."
+
+## Module Structure
+
+```
+src/Simplex/FileTransfer/Server/
+  Store.hs                    -- FileStoreClass typeclass + shared types (FileRec, FileRecipient, etc.)
+  Store/
+    STM.hs                    -- STMFileStore (extracted from current Store.hs)
+    Postgres.hs               -- PostgresFileStore                [CPP-guarded]
+    Postgres/
+      Migrations.hs           -- Schema migrations                [CPP-guarded]
+      Config.hs               -- PostgresFileStoreCfg             [CPP-guarded]
+  StoreLog.hs                 -- Unchanged (interchange format for both backends + migration)
+  Env.hs                      -- XFTPStoreConfig GADT, polymorphic XFTPEnv
+  Main.hs                     -- Store selection, migration CLI commands
+  Server.hs                   -- Polymorphic over FileStoreClass
+```
+
+## PostgreSQL Schema
+
+Initial migration (`20260325_initial`):
+
+```sql
+CREATE TABLE files (
+  sender_id BYTEA NOT NULL PRIMARY KEY,
+  file_size INT4 NOT NULL,
+  file_digest BYTEA NOT NULL,
+  sender_key BYTEA NOT NULL,
+  file_path TEXT,
+  created_at INT8 NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active'
+);
+
+CREATE TABLE recipients (
+  recipient_id BYTEA NOT NULL PRIMARY KEY,
+  sender_id BYTEA NOT NULL REFERENCES files ON DELETE CASCADE,
+  recipient_key BYTEA NOT NULL
+);
+
+CREATE INDEX idx_recipients_sender_id ON recipients (sender_id);
+CREATE INDEX idx_files_created_at ON files (created_at);
+```
+
+- `file_size` is `INT4` matching `Word32` in `FileInfo.size`
+- `sender_key` and `recipient_key` stored as `BYTEA` using binary encoding via `C.encodePubKey` / `C.decodePubKey` (matching SMP's `ToField`/`FromField` instances for `APublicAuthKey` — includes algorithm type tag in the binary format)
+- `file_path` nullable (set after upload completes via `setFilePath`)
+- `ON DELETE CASCADE` for recipients when file is hard-deleted
+- `created_at` stores rounded epoch seconds (1-hour precision, `RoundedFileTime`)
+- `status` as TEXT via `StrEncoding` (`ServerEntityStatus`: `EntityActive`, `EntityBlocked info`, `EntityOff`)
+- Hard deletes (no `deleted_at` column)
+- No PL/pgSQL functions needed; `setFilePath` uses `WHERE file_path IS NULL` to prevent duplicate uploads (the `UPDATE` itself acquires a row-level lock)
+- `used_storage` computed on startup: `SELECT COALESCE(SUM(file_size), 0) FROM files` (matches STM `countUsedStorage` — all files, see usedStorage Ownership section)
+
+### Migrations Module
+
+Following SMP's `QueueStore/Postgres/Migrations.hs` pattern:
+
+```haskell
+module Simplex.FileTransfer.Server.Store.Postgres.Migrations
+  ( xftpServerMigrations,
+  )
+where
+
+import Data.List (sortOn)
+import Data.Text (Text)
+import Simplex.Messaging.Agent.Store.Shared
+import Text.RawString.QQ (r)
+
+xftpSchemaMigrations :: [(String, Text, Maybe Text)]
+xftpSchemaMigrations =
+  [ ("20260325_initial", m20260325_initial, Nothing)
+  ]
+
+xftpServerMigrations :: [Migration]
+xftpServerMigrations = sortOn name $ map migration xftpSchemaMigrations
+  where
+    migration (name, up, down) = Migration {name, up, down = down}
+
+m20260325_initial :: Text
+m20260325_initial =
+  [r|
+CREATE TABLE files (
+  sender_id BYTEA NOT NULL PRIMARY KEY,
+  ...
+);
+  |]
+```
+
+The `Migration` type (from `Simplex.Messaging.Agent.Store.Shared`) has fields `{name :: String, up :: Text, down :: Maybe Text}`. Initial migration has `Nothing` for `down`. Future migrations should include `Just down_migration` for rollback support. Called via `createDBStore dbOpts xftpServerMigrations (MigrationConfig confirmMigrations Nothing)`.
+
+### Postgres Operations
+
+Key query patterns:
+
+- **`addFile`**: `INSERT INTO files (...) VALUES (...)`, return `DUPLICATE_` on unique violation.
+- **`setFilePath`**: `UPDATE files SET file_path = ? WHERE sender_id = ? AND file_path IS NULL`, verified with `assertUpdated` (returns `AUTH` if 0 rows affected — file not found or already uploaded). The `WHERE file_path IS NULL` prevents duplicate uploads; the `UPDATE` acquires a row lock implicitly. Only persists the path; `usedStorage` managed by server.
+- **`addRecipient`**: `INSERT INTO recipients (...)`, plus check for duplicates. No need for `recipientIds` TVar update — Postgres derives it from the table.
+- **`getFile`** (sender): `SELECT ... FROM files WHERE sender_id = ?`, returns auth key from `sender_key` column.
+- **`getFile`** (recipient): `SELECT f.*, r.recipient_key FROM recipients r JOIN files f ON ... WHERE r.recipient_id = ?`.
+- **`deleteFile`**: `DELETE FROM files WHERE sender_id = ?` (recipients cascade).
+- **`blockFile`**: `UPDATE files SET status = ? WHERE sender_id = ?`. When `deleted = True`, the server adjusts `usedStorage` externally (matching current STM behavior where `blockFile` only updates status and storage, not `filePath`).
+- **`expiredFiles`**: `SELECT sender_id, file_path, file_size FROM files WHERE created_at + ? < ? LIMIT ?` — batched query replaces per-file iteration, includes `file_size` for `usedStorage` adjustment. Called in a loop until no rows returned.
+
+## INI Configuration
+
+New keys in `[STORE_LOG]` section:
+
+```ini
+[STORE_LOG]
+enable: on
+store_files: memory            # memory | database
+db_connection: postgresql://xftp@/xftp_server_store
+db_schema: xftp_server
+db_pool_size: 10
+db_store_log: off
+expire_files_hours: 48
+```
+
+`store_files` selects the backend (`store_files` rather than `store_queues` because XFTP stores files, not queues):
+- `memory` -> `XSCMemory` (current behavior)
+- `database` -> `XSCDatabase` (requires `server_postgres` build flag)
+
+### INI Template Generation (`xftp-server init`)
+
+The `iniFileContent` function in `Main.hs` must be updated to generate the new keys in the `[STORE_LOG]` section. Following SMP's `iniDbOpts` pattern with `optDisabled'` (prefixes `"# "` when value equals default), Postgres keys are generated commented out by default:
+
+```ini
+[STORE_LOG]
+enable: on
+
+# File storage mode: `memory` or `database` (PostgreSQL).
+store_files: memory
+
+# Database connection settings for PostgreSQL database (`store_files: database`).
+# db_connection: postgresql://xftp@/xftp_server_store
+# db_schema: xftp_server
+# db_pool_size: 10
+
+# Write database changes to store log file
+# db_store_log: off
+
+expire_files_hours: 48
+```
+
+Reuses `iniDBOptions` from `Simplex.Messaging.Server.CLI` for runtime parsing (falls back to defaults when keys are commented out or missing). `enableDbStoreLog'` pattern (`settingIsOn "STORE_LOG" "db_store_log"`) controls `dbStoreLogPath`.
+
+### PostgresFileStoreCfg
+
+```haskell
+data PostgresFileStoreCfg = PostgresFileStoreCfg
+  { dbOpts :: DBOpts,
+    dbStoreLogPath :: Maybe FilePath,
+    confirmMigrations :: MigrationConfirmation
+  }
+```
+
+No `deletedTTL` (hard deletes).
+
+### Default DB Options
+
+```haskell
+defaultXFTPDBOpts :: DBOpts
+defaultXFTPDBOpts =
+  DBOpts
+    { connstr = "postgresql://xftp@/xftp_server_store",
+      schema = "xftp_server",
+      poolSize = 10,
+      createSchema = False
+    }
+```
+
+## Migration CLI
+
+Bidirectional migration via StoreLog as interchange format:
+
+```
+xftp-server database import [--database DB_CONN] [--schema DB_SCHEMA] [--pool-size N]
+xftp-server database export [--database DB_CONN] [--schema DB_SCHEMA] [--pool-size N]
+```
+
+No `--table` flag needed (unlike SMP which has queues/messages/all) — XFTP has a single entity type (files + recipients, always migrated together).
+
+CLI options reuse `dbOptsP` parser from `Simplex.Messaging.Server.CLI`.
+
+### Import (StoreLog -> PostgreSQL)
+
+1. Confirm: prompt user with database connection details and StoreLog path
+2. Read and replay StoreLog into temporary `STMFileStore`
+3. Connect to PostgreSQL, run schema migrations (`createSchema = True`, `confirmMigrations = MCYesUp`)
+4. Batch-insert file records into `files` table using PostgreSQL COPY protocol (matching SMP's `batchInsertQueues` pattern for performance). Progress reported every 10k files.
+5. Batch-insert recipient records into `recipients` table using COPY protocol
+6. Verify counts: `SELECT COUNT(*) FROM files` / `recipients` — warn if mismatch
+7. Rename StoreLog to `.bak` (prevents accidental re-import, preserves original for rollback)
+8. Report counts
+
+### Export (PostgreSQL -> StoreLog)
+
+1. Confirm: prompt user with database connection details and output path. Fail if output file already exists.
+2. Connect to PostgreSQL
+3. Open new StoreLog file for writing
+4. Fold over all file records, writing per file (in this order, matching existing `writeFileStore`): `AddFile` (with `ServerEntityStatus` — this preserves `EntityBlocked` state), `AddRecipients`, then `PutFile` (if `file_path` is set)
+5. Report counts
+
+Note: `AddFile` carries `ServerEntityStatus` which includes `EntityBlocked info`, so blocking state is preserved through export/import without needing separate `BlockFile` log entries.
+
+File data on disk is untouched by migration — only metadata moves between backends.
+
+## Cabal Integration
+
+Shared `server_postgres` flag. New Postgres modules added to existing conditional block:
+
+```cabal
+if flag(server_postgres)
+  cpp-options: -DdbServerPostgres
+  exposed-modules:
+    ...existing SMP modules...
+    Simplex.FileTransfer.Server.Store.Postgres
+    Simplex.FileTransfer.Server.Store.Postgres.Migrations
+    Simplex.FileTransfer.Server.Store.Postgres.Config
+```
+
+CPP guards (`#if defined(dbServerPostgres)`) in:
+- `Store.hs` — Postgres `FromField`/`ToField` instances for XFTP-specific types if needed
+- `Env.hs` — `XSCDatabase` constructor
+- `Main.hs` — database CLI commands, store selection for `database` mode, Postgres imports
+- `Server.hs` — Postgres-specific imports if needed
+
+## Testing
+
+- **Parameterized server tests**: Existing `xftpServerTests` refactored to accept a store type parameter (following SMP's `SpecWith (ASrvTransport, AStoreType)` pattern). The same server tests run against both STM and Postgres backends — STM tests run unconditionally, Postgres tests added under `#if defined(dbServerPostgres)` with `postgressBracket` for database lifecycle (drop → create → test → drop).
+- **Unit tests**: `PostgresFileStore` operations — add/get/delete/block/expire, duplicate detection, auth errors
+- **Migration round-trip**: STM store → export to StoreLog → import to Postgres → export back → verify StoreLog equality (including blocked file status)
+- **Tests location**: in `tests/` alongside existing XFTP tests, guarded by `server_postgres` CPP flag
+- **Test database**: PostgreSQL on `localhost:5432`, using a dedicated `xftp_server_test` schema (dropped and recreated per test run via `postgressBracket`, following SMP's test database lifecycle pattern)
+- **Test fixtures**: `testXFTPStoreDBOpts :: DBOpts` with `createSchema = True`, `confirmMigrations = MCYesUp`, in `tests/XFTPClient.hs`

plans/2026-03-25-xftp-postgres-implementation-plan.md

@@ -0,0 +1,648 @@
+# XFTP PostgreSQL Backend — Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers-extended-cc:subagent-driven-development (if subagents available) or superpowers-extended-cc:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add PostgreSQL backend support to xftp-server as an alternative to STM + StoreLog, with bidirectional migration.
+
+**Architecture:** Introduce `FileStoreClass` typeclass (IO-based, following `QueueStoreClass` pattern). Extract current STM store into `Store/STM.hs`, make `Server.hs` polymorphic, then add `Store/Postgres.hs` behind `server_postgres` CPP flag. `usedStorage` moves from store to `XFTPEnv` so the server manages quota tracking externally.
+
+**Tech Stack:** Haskell, postgresql-simple, STM, fourmolu, cabal with CPP flags
+
+**Design spec:** `plans/2026-03-25-xftp-postgres-backend-design.md`
+
+---
+
+## File Structure
+
+**Existing files modified:**
+- `src/Simplex/FileTransfer/Server/Store.hs` — rewritten: becomes typeclass + shared types
+- `src/Simplex/FileTransfer/Server/Env.hs` — polymorphic `XFTPEnv s`, `XFTPStoreConfig` GADT
+- `src/Simplex/FileTransfer/Server.hs` — polymorphic over `FileStoreClass s`
+- `src/Simplex/FileTransfer/Server/StoreLog.hs` — update for IO store functions
+- `src/Simplex/FileTransfer/Server/Main.hs` — INI config, dispatch, CLI commands
+- `simplexmq.cabal` — new modules
+- `tests/XFTPClient.hs` — Postgres test fixtures
+- `tests/Test.hs` — Postgres test group
+
+**New files created:**
+- `src/Simplex/FileTransfer/Server/Store/STM.hs` — `STMFileStore` (extracted from current `Store.hs`)
+- `src/Simplex/FileTransfer/Server/Store/Postgres.hs` — `PostgresFileStore` [CPP-guarded]
+- `src/Simplex/FileTransfer/Server/Store/Postgres/Config.hs` — `PostgresFileStoreCfg` [CPP-guarded]
+- `src/Simplex/FileTransfer/Server/Store/Postgres/Migrations.hs` — schema SQL [CPP-guarded]
+- `tests/CoreTests/XFTPStoreTests.hs` — Postgres store unit tests [CPP-guarded]
+
+---
+
+## Task 1: Move `usedStorage` from `FileStore` to `XFTPEnv`
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Store.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+- Modify: `src/Simplex/FileTransfer/Server.hs`
+
+- [ ] **Step 1: Remove `usedStorage` from `FileStore` in `Store.hs`**
+
+  1. Remove `usedStorage :: TVar Int64` field from `FileStore` record (line 47).
+  2. Remove `usedStorage <- newTVarIO 0` from `newFileStore` (line 75) and drop the field from the record construction (line 76).
+  3. In `setFilePath` (line 92-97): remove `modifyTVar' (usedStorage st) (+ fromIntegral (size fileInfo))` — keep only `writeTVar filePath (Just fPath)`. Change pattern from `\FileRec {fileInfo, filePath}` to `\FileRec {filePath}` (fileInfo is now unused — `-Wunused-matches` error).
+  4. In `deleteFile` (line 112-119): remove `modifyTVar' usedStorage $ subtract (fromIntegral $ size fileInfo)`. Change outer pattern match from `FileStore {files, recipients, usedStorage}` to `FileStore {files, recipients}`. Change inner pattern from `Just FileRec {fileInfo, recipientIds}` to `Just FileRec {recipientIds}` (`fileInfo` is now unused — `-Wunused-matches` error).
+  5. In `blockFile` (line 122-127): remove `when deleted $ modifyTVar' usedStorage $ subtract (fromIntegral $ size fileInfo)`. Change pattern match from `st@FileStore {usedStorage}` to `st`. The `deleted` parameter and `fileInfo` in the inner pattern become unused — prefix with `_` or remove from pattern to avoid `-Wunused-matches`.
+
+- [ ] **Step 2: Add `usedStorage` to `XFTPEnv` in `Env.hs`**
+
+  1. Add `usedStorage :: TVar Int64` field to `XFTPEnv` record (between `store` and `storeLog`, line 93).
+  2. In `newXFTPServerEnv` (line 112-126): replace lines 117-118:
+     ```
+     used <- countUsedStorage <$> readTVarIO (files store)
+     atomically $ writeTVar (usedStorage store) used
+     ```
+     with:
+     ```
+     usedStorage <- newTVarIO =<< countUsedStorage <$> readTVarIO (files store)
+     ```
+  3. Add `usedStorage` to the `pure XFTPEnv {..}` construction.
+
+- [ ] **Step 3: Update all `usedStorage` access sites in `Server.hs`**
+
+  1. Line 552: `us <- asks $ usedStorage . store` → `us <- asks usedStorage`.
+  2. Line 569: `us <- asks $ usedStorage . store` → `us <- asks usedStorage`.
+  3. Line 639: `usedStart <- readTVarIO $ usedStorage st` → `usedStart <- readTVarIO =<< asks usedStorage`.
+  4. Line 647: `usedEnd <- readTVarIO $ usedStorage st` → `usedEnd <- readTVarIO =<< asks usedStorage`.
+  5. Line 694: `FileStore {files, usedStorage} <- asks store` → split into `FileStore {files} <- asks store` and `usedStorage <- asks usedStorage`.
+  6. In `deleteOrBlockServerFile_` (line 620): after `void $ atomically $ storeAction st`, add usedStorage adjustment — `us <- asks usedStorage` then `atomically $ modifyTVar' us $ subtract (fromIntegral $ size fileInfo)` when file had a path (check `path` from `readTVarIO filePath` earlier in the function).
+
+- [ ] **Step 4: Build and verify**
+
+  Run: `cabal build`
+
+- [ ] **Step 5: Run existing tests**
+
+  Run: `cabal test --test-show-details=streaming --test-option=--match="/XFTP/"`
+
+- [ ] **Step 6: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs
+  git add src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs
+  git commit -m "refactor(xftp): move usedStorage from FileStore to XFTPEnv"
+  ```
+
+---
+
+## Task 2: Add `getUsedStorage`, `getFileCount`, `expiredFiles` functions
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Store.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+- Modify: `src/Simplex/FileTransfer/Server.hs`
+
+- [ ] **Step 1: Add three new functions to `Store.hs`**
+
+  1. Add to exports: `getUsedStorage`, `getFileCount`, `expiredFiles`.
+  2. Remove `expiredFilePath` from exports AND delete the function definition (dead code → `-Wunused-binds` error). Also remove `($>>=)` from import `Simplex.Messaging.Util (ifM, ($>>=))` → `Simplex.Messaging.Util (ifM)` — `$>>=` was only used by `expiredFilePath`.
+  3. Add import: `qualified Data.Map.Strict as M` (needed for `M.foldl'` in `getUsedStorage` and `M.toList` in `expiredFiles`).
+  4. Implement:
+     ```haskell
+     getUsedStorage :: FileStore -> IO Int64
+     getUsedStorage FileStore {files} =
+       M.foldl' (\acc FileRec {fileInfo = FileInfo {size}} -> acc + fromIntegral size) 0 <$> readTVarIO files
+
+     getFileCount :: FileStore -> IO Int
+     getFileCount FileStore {files} = M.size <$> readTVarIO files
+
+     expiredFiles :: FileStore -> Int64 -> Int -> IO [(SenderId, Maybe FilePath, Word32)]
+     expiredFiles FileStore {files} old _limit = do
+       fs <- readTVarIO files
+       fmap catMaybes . forM (M.toList fs) $ \(sId, FileRec {fileInfo = FileInfo {size}, filePath, createdAt = RoundedSystemTime createdAt}) ->
+         if createdAt + fileTimePrecision < old
+           then do
+             path <- readTVarIO filePath
+             pure $ Just (sId, path, size)
+           else pure Nothing
+     ```
+  5. Add imports: `Data.Maybe (catMaybes)`, `Data.Word (Word32)` (note: `qualified Data.Map.Strict as M` already added in item 3).
+
+- [ ] **Step 2: Replace `countUsedStorage` in `Env.hs`**
+
+  1. Replace `countUsedStorage <$> readTVarIO (files store)` with `getUsedStorage store` in `newXFTPServerEnv`.
+  2. Remove `countUsedStorage` function definition and its export.
+  3. Remove `qualified Data.Map.Strict as M` import if no longer used.
+
+- [ ] **Step 3: Update `restoreServerStats` in `Server.hs` to use `getFileCount`**
+
+  In `restoreServerStats` (line 694-696): replace `FileStore {files} <- asks store` and `_filesCount <- M.size <$> readTVarIO files` with `st <- asks store` and `_filesCount <- liftIO $ getFileCount st` (eliminates the `FileStore` pattern match — `files` binding no longer needed).
+
+- [ ] **Step 4: Replace `expireServerFiles` iteration in `Server.hs`**
+
+  1. Replace the body of `expireServerFiles` (lines 636-660). Remove `files' <- readTVarIO (files st)` and the `forM_ (M.keys files')` loop.
+  2. New body: call `expiredFiles st old 10000` in a loop. For each `(sId, filePath_, fileSize)` in returned list: apply `itemDelay`, remove disk file if present, call `atomically $ deleteFile st sId`, adjust `usedStorage` TVar by `fileSize`, increment `filesExpired` stat. Loop until `expiredFiles` returns `[]`.
+  3. Remove `Data.Map.Strict` import from Server.hs if no longer needed (was used for `M.size` and `M.keys` — now replaced by `getFileCount` and `expiredFiles`).
+
+- [ ] **Step 5: Build and verify**
+
+  Run: `cabal build`
+
+- [ ] **Step 6: Run existing tests**
+
+  Run: `cabal test --test-show-details=streaming --test-option=--match="/XFTP/"`
+
+- [ ] **Step 7: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs
+  git add src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs
+  git commit -m "refactor(xftp): add getUsedStorage, getFileCount, expiredFiles store functions"
+  ```
+
+---
+
+## Task 3: Change `Store.hs` functions from STM to IO
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Store.hs`
+- Modify: `src/Simplex/FileTransfer/Server.hs`
+- Modify: `src/Simplex/FileTransfer/Server/StoreLog.hs`
+
+- [ ] **Step 1: Change all Store.hs function signatures from STM to IO**
+
+  For each of: `addFile`, `setFilePath`, `addRecipient`, `getFile`, `deleteFile`, `blockFile`, `deleteRecipient`, `ackFile`:
+  1. Change return type from `STM (Either XFTPErrorType ...)` to `IO (Either XFTPErrorType ...)` (or `STM ()` to `IO ()` for `deleteRecipient`).
+  2. Wrap the function body in `atomically $ do ...`.
+  3. Keep `withFile` and `newFileRec` as internal STM helpers (called inside the `atomically` blocks).
+
+- [ ] **Step 2: Update Server.hs call sites — remove `atomically` wrappers**
+
+  1. Line 563 (`receiveServerFile`): change `atomically $ writeTVar filePath (Just fPath)` → add `st <- asks store` then `void $ liftIO $ setFilePath st senderId fPath` (design call site #1 — `store` is not in scope in `receiveServerFile`'s `receive` helper, so bind via `asks`; `void` avoids `-Wunused-do-bind` warning on the `Either` result).
+  2. Line 453 (`verifyXFTPTransmission`): split `atomically $ verify =<< getFile st party fId` into: `liftIO (getFile st party fId)` (IO→M lift), then pattern match on result, use `readTVarIO (fileStatus fr)` instead of `readTVar`.
+  3. Lines 371, 377 (control port `CPDelete`/`CPBlock`): change `ExceptT $ atomically $ getFile fs SFRecipient fileId` → `ExceptT $ liftIO $ getFile fs SFRecipient fileId` (inside `unliftIO u $ do` block which runs in M monad — `liftIO` required to lift IO into M).
+  4. Line 508 (`addFile` in `createFile`): the `ExceptT $ addFile st sId file ts EntityActive` — `addFile` is now IO, `ExceptT` wraps IO directly. Remove any `atomically`.
+  5. Line 514 (`addRecipient`): same — `ExceptT . addRecipient st sId` works directly in IO.
+  6. Line 516 (`retryAdd`): change parameter type from `(XFTPFileId -> STM (Either XFTPErrorType a))` to `(XFTPFileId -> IO (Either XFTPErrorType a))`. Line 520: change `atomically (add fId)` to `liftIO (add fId)`.
+  7. Line 605 (`ackFileReception`): change `atomically $ deleteRecipient st rId fr` to `liftIO $ deleteRecipient st rId fr`.
+  8. Line 620 (`deleteOrBlockServerFile_`): change third parameter type from `(FileStore -> STM (Either XFTPErrorType ()))` to `(FileStore -> IO (Either XFTPErrorType ()))`. Line 626: change `void $ atomically $ storeAction st` to `void $ liftIO $ storeAction st`.
+  9. `expireServerFiles` `delete` helper: change `atomically $ deleteFile st sId` to `liftIO $ deleteFile st sId` (deleteFile is now IO; `liftIO` required because the helper runs in M monad, not IO).
+
+- [ ] **Step 3: Update `StoreLog.hs` — remove `atomically` from replay**
+
+  In `readFileStore` (line 93), function `addToStore`:
+  1. Change `atomically (addToStore lr)` to `addToStore lr` — store functions are now IO.
+  2. The `addToStore` body calls `addFile`, `setFilePath`, `deleteFile`, `blockFile`, `ackFile` — all IO now, no `atomically` needed.
+  3. For `AddRecipients`: `runExceptT $ mapM_ (ExceptT . addRecipient st sId) rcps` — `addRecipient` returns `IO (Either ...)`, so `ExceptT . addRecipient st sId` works directly.
+
+- [ ] **Step 4: Build and verify**
+
+  Run: `cabal build`
+
+- [ ] **Step 5: Run existing tests**
+
+  Run: `cabal test --test-show-details=streaming --test-option=--match="/XFTP/"`
+
+- [ ] **Step 6: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/StoreLog.hs
+  git add src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/StoreLog.hs
+  git commit -m "refactor(xftp): change file store operations from STM to IO"
+  ```
+
+---
+
+## Task 4: Extract `FileStoreClass` typeclass, move STM impl to `Store/STM.hs`
+
+**Files:**
+- Rewrite: `src/Simplex/FileTransfer/Server/Store.hs`
+- Create: `src/Simplex/FileTransfer/Server/Store/STM.hs`
+- Modify: `src/Simplex/FileTransfer/Server/StoreLog.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+- Modify: `src/Simplex/FileTransfer/Server.hs`
+- Modify: `simplexmq.cabal`
+
+- [ ] **Step 1: Create `Store/STM.hs` — move all implementation code**
+
+  1. Create directory `src/Simplex/FileTransfer/Server/Store/`.
+  2. Create `src/Simplex/FileTransfer/Server/Store/STM.hs`.
+  3. Move from `Store.hs`: `FileStore` data type (rename to `STMFileStore`), all function implementations, internal helpers (`withFile`, `newFileRec`), all STM-specific imports.
+  4. Rename all `FileStore` references to `STMFileStore` in the new file.
+  5. Module declaration: `module Simplex.FileTransfer.Server.Store.STM` exporting only `STMFileStore (..)` — do NOT export standalone functions (`addFile`, `setFilePath`, etc.) to avoid name collisions with the typeclass methods from `Store.hs`.
+
+- [ ] **Step 2: Rewrite `Store.hs` as the typeclass module**
+
+  1. Add `{-# LANGUAGE TypeFamilies #-}` pragma to `Store.hs` (required for `type FileStoreConfig s` associated type).
+  2. Keep in `Store.hs`: `FileRec (..)`, `FileRecipient (..)`, `RoundedFileTime`, `fileTimePrecision` definitions and their `StrEncoding` instance.
+  3. Add `FileStoreClass` typeclass:
+     ```haskell
+     class FileStoreClass s where
+       type FileStoreConfig s
+
+       -- Lifecycle
+       newFileStore :: FileStoreConfig s -> IO s
+       closeFileStore :: s -> IO ()
+
+       -- File operations
+       addFile :: s -> SenderId -> FileInfo -> RoundedFileTime -> ServerEntityStatus -> IO (Either XFTPErrorType ())
+       setFilePath :: s -> SenderId -> FilePath -> IO (Either XFTPErrorType ())
+       addRecipient :: s -> SenderId -> FileRecipient -> IO (Either XFTPErrorType ())
+       getFile :: s -> SFileParty p -> XFTPFileId -> IO (Either XFTPErrorType (FileRec, C.APublicAuthKey))
+       deleteFile :: s -> SenderId -> IO (Either XFTPErrorType ())
+       blockFile :: s -> SenderId -> BlockingInfo -> Bool -> IO (Either XFTPErrorType ())
+       deleteRecipient :: s -> RecipientId -> FileRec -> IO ()
+       ackFile :: s -> RecipientId -> IO (Either XFTPErrorType ())
+
+       -- Expiration
+       expiredFiles :: s -> Int64 -> Int -> IO [(SenderId, Maybe FilePath, Word32)]
+
+       -- Stats
+       getUsedStorage :: s -> IO Int64
+       getFileCount :: s -> IO Int
+     ```
+  4. Do NOT re-export from `Store/STM.hs` — this would create a circular module dependency (Store.hs imports Store/STM.hs, Store/STM.hs imports Store.hs). Consumers must import `Store.STM` directly where they need `STMFileStore`.
+  5. Remove all STM-specific imports that are no longer needed.
+
+- [ ] **Step 3: Add `FileStoreClass` instance in `Store/STM.hs`**
+
+  1. Import `FileStoreClass` from `Simplex.FileTransfer.Server.Store`.
+  2. Inline all implementations directly in the instance body (do NOT delegate to standalone functions — the standalone names collide with typeclass method names, causing ambiguous occurrences for importers):
+     ```haskell
+     instance FileStoreClass STMFileStore where
+       type FileStoreConfig STMFileStore = ()
+       newFileStore () = do
+         files <- TM.emptyIO
+         recipients <- TM.emptyIO
+         pure STMFileStore {files, recipients}
+       closeFileStore _ = pure ()
+       addFile st sId fileInfo createdAt status = atomically $ ...
+       setFilePath st sId fPath = atomically $ ...
+       -- ... (each method's body is the existing function body, inlined)
+     ```
+  3. Remove the standalone top-level function definitions — they are now instance methods. Keep only `withFile` and `newFileRec` as internal helpers used by the instance methods.
+
+- [ ] **Step 4: Update importers**
+
+  1. `Env.hs`: add `import Simplex.FileTransfer.Server.Store.STM (STMFileStore (..))`. Change `FileStore` → `STMFileStore` in `XFTPEnv` type and `newXFTPServerEnv`. Change `store <- newFileStore` to `store <- newFileStore ()` (typeclass method now takes `FileStoreConfig STMFileStore` which is `()`). Keep `import Simplex.FileTransfer.Server.Store` for `FileRec`, `FileRecipient`, `FileStoreClass`, etc.
+  2. `Server.hs`: add `import Simplex.FileTransfer.Server.Store.STM`. Change `FileStore` → `STMFileStore` in any explicit type annotations. Import `FileStoreClass` from `Simplex.FileTransfer.Server.Store`.
+  3. `StoreLog.hs`: add `import Simplex.FileTransfer.Server.Store.STM` to access concrete `STMFileStore` type and store functions used during log replay. Change `FileStore` → `STMFileStore` in `readWriteFileStore` and `writeFileStore` parameter types.
+
+- [ ] **Step 5: Update cabal file**
+
+  Add `Simplex.FileTransfer.Server.Store.STM` to `exposed-modules` in the `!flag(client_library)` section, alongside existing XFTP server modules.
+
+- [ ] **Step 6: Build and verify**
+
+  Run: `cabal build`
+
+- [ ] **Step 7: Run existing tests**
+
+  Run: `cabal test --test-show-details=streaming --test-option=--match="/XFTP/"`
+
+- [ ] **Step 8: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Store/STM.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/StoreLog.hs
+  git add src/Simplex/FileTransfer/Server/Store.hs src/Simplex/FileTransfer/Server/Store/STM.hs src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/StoreLog.hs simplexmq.cabal
+  git commit -m "refactor(xftp): extract FileStoreClass typeclass, move STM impl to Store.STM"
+  ```
+
+---
+
+## Task 5: Make `XFTPEnv` and `Server.hs` polymorphic over `FileStoreClass`
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+- Modify: `src/Simplex/FileTransfer/Server.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Main.hs`
+- Modify: `tests/XFTPClient.hs` (if it calls `runXFTPServerBlocking` directly)
+
+- [ ] **Step 1: Make `XFTPEnv` polymorphic in `Env.hs`**
+
+  1. Add `XFTPStoreConfig` GADT: `data XFTPStoreConfig s where XSCMemory :: Maybe FilePath -> XFTPStoreConfig STMFileStore`.
+  2. Change `data XFTPEnv` to `data XFTPEnv s` — field `store :: FileStore` becomes `store :: s`.
+  3. Change `newXFTPServerEnv :: XFTPServerConfig -> IO XFTPEnv` to `newXFTPServerEnv :: FileStoreClass s => XFTPStoreConfig s -> XFTPServerConfig -> IO (XFTPEnv s)`.
+  4. Pattern match on `XSCMemory storeLogPath` in `newXFTPServerEnv` body. Create store via `newFileStore ()`, storeLog via `mapM (`readWriteFileStore` st) storeLogPath`.
+
+- [ ] **Step 2: Make `Server.hs` polymorphic**
+
+  1. Change `type M a = ReaderT XFTPEnv IO a` to `type M s a = ReaderT (XFTPEnv s) IO a`.
+  2. Add `FileStoreClass s =>` constraint to all functions using `M s a`. Use `forall s.` in signatures of functions that have `where`-block bindings with `M s` type annotations — `ScopedTypeVariables` requires explicit `forall` to bring `s` into scope for inner type signatures (matching SMP's `smpServer :: forall s. MsgStoreClass s => ...` pattern). Full list: `xftpServer`, `processRequest`, `verifyXFTPTransmission`, `processXFTPRequest` and all its `where`-bound functions (`createFile`, `addRecipients`, `receiveServerFile`, `sendServerFile`, `deleteServerFile`, `ackFileReception`, `retryAdd`, `addFileRetry`, `addRecipientRetry`), `deleteServerFile_`, `blockServerFile`, `deleteOrBlockServerFile_`, `expireServerFiles`, `randomId`, `getFileId`, `withFileLog`, `incFileStat`, `saveServerStats`, `restoreServerStats`, `randomDelay` (inside `#ifdef slow_servers` CPP block). Also update `encodeXftp` (line 236) and `runCPClient` (line 339) which use explicit `ReaderT XFTPEnv IO` instead of the `M` alias — change to `ReaderT (XFTPEnv s) IO`.
+  3. Change `runXFTPServerBlocking` and `runXFTPServer` to take `XFTPStoreConfig s` parameter.
+  4. Add `closeFileStore store` call to the server shutdown path (in the `finally` block or `stopServer` equivalent — after saving stats, before logging "Server stopped"). This ensures Postgres connection pool and `dbStoreLog` are properly closed. For STM this is a no-op.
+
+- [ ] **Step 3: Update `Main.hs` dispatch**
+
+  1. In `runServer`: construct `XSCMemory (enableStoreLog $> storeLogFilePath)`.
+  2. Add dispatch function that calls the updated `runXFTPServer` (which creates `started` internally):
+     ```haskell
+     run :: FileStoreClass s => XFTPStoreConfig s -> IO ()
+     run storeCfg = runXFTPServer storeCfg serverConfig
+     ```
+  3. Call `run` with the `XSCMemory` config.
+
+- [ ] **Step 4: Update test helper if needed**
+
+  If `tests/XFTPClient.hs` calls `runXFTPServerBlocking` directly, update the call to pass an `XSCMemory` config. Check the `withXFTPServer` / `serverBracket` helper.
+
+- [ ] **Step 5: Build and verify**
+
+  Run: `cabal build && cabal build test:simplexmq-test`
+
+- [ ] **Step 6: Run existing tests**
+
+  Run: `cabal test --test-show-details=streaming --test-option=--match="/XFTP/"`
+
+- [ ] **Step 7: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/Main.hs
+  git add src/Simplex/FileTransfer/Server/Env.hs src/Simplex/FileTransfer/Server.hs src/Simplex/FileTransfer/Server/Main.hs tests/XFTPClient.hs simplexmq.cabal
+  git commit -m "refactor(xftp): make XFTPEnv and server polymorphic over FileStoreClass"
+  ```
+
+---
+
+## Task 6: Add Postgres config, migrations, and store skeleton
+
+**Files:**
+- Create: `src/Simplex/FileTransfer/Server/Store/Postgres/Config.hs`
+- Create: `src/Simplex/FileTransfer/Server/Store/Postgres/Migrations.hs`
+- Create: `src/Simplex/FileTransfer/Server/Store/Postgres.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+- Modify: `simplexmq.cabal`
+
+- [ ] **Step 1: Create `Store/Postgres/Config.hs`**
+
+  ```haskell
+  module Simplex.FileTransfer.Server.Store.Postgres.Config
+    ( PostgresFileStoreCfg (..),
+      defaultXFTPDBOpts,
+    )
+  where
+
+  import Simplex.Messaging.Agent.Store.Postgres.Options (DBOpts (..))
+  import Simplex.Messaging.Agent.Store.Shared (MigrationConfirmation)
+
+  data PostgresFileStoreCfg = PostgresFileStoreCfg
+    { dbOpts :: DBOpts,
+      dbStoreLogPath :: Maybe FilePath,
+      confirmMigrations :: MigrationConfirmation
+    }
+
+  defaultXFTPDBOpts :: DBOpts
+  defaultXFTPDBOpts =
+    DBOpts
+      { connstr = "postgresql://xftp@/xftp_server_store",
+        schema = "xftp_server",
+        poolSize = 10,
+        createSchema = False
+      }
+  ```
+
+- [ ] **Step 2: Create `Store/Postgres/Migrations.hs`**
+
+  Full migration module with `xftpServerMigrations :: [Migration]` and `m20260325_initial` containing CREATE TABLE SQL for `files` and `recipients` tables plus indexes. Follow SMP's `QueueStore/Postgres/Migrations.hs` pattern exactly: tuple list → `sortOn name . map migration`.
+
+- [ ] **Step 3: Create `Store/Postgres.hs` with stub instance**
+
+  1. Define `PostgresFileStore` with `dbStore :: DBStore` and `dbStoreLog :: Maybe (StoreLog 'WriteMode)`.
+  2. `instance FileStoreClass PostgresFileStore` with `error "not implemented"` for all methods except `newFileStore` (calls `createDBStore` + opens `dbStoreLog`) and `closeFileStore` (closes both). `type FileStoreConfig PostgresFileStore = PostgresFileStoreCfg`.
+  3. Add `withDB`, `handleDuplicate`, `assertUpdated`, `withLog` helpers.
+
+- [ ] **Step 4: Add `XSCDatabase` GADT constructor in `Env.hs` (CPP-guarded)**
+
+  ```haskell
+  #if defined(dbServerPostgres)
+  import Simplex.FileTransfer.Server.Store.Postgres (PostgresFileStore)
+  import Simplex.FileTransfer.Server.Store.Postgres.Config (PostgresFileStoreCfg)
+  #endif
+
+  data XFTPStoreConfig s where
+    XSCMemory :: Maybe FilePath -> XFTPStoreConfig STMFileStore
+  #if defined(dbServerPostgres)
+    XSCDatabase :: PostgresFileStoreCfg -> XFTPStoreConfig PostgresFileStore
+  #endif
+  ```
+
+- [ ] **Step 5: Update cabal**
+
+  Add to existing `if flag(server_postgres)` block:
+  ```
+  Simplex.FileTransfer.Server.Store.Postgres
+  Simplex.FileTransfer.Server.Store.Postgres.Config
+  Simplex.FileTransfer.Server.Store.Postgres.Migrations
+  ```
+
+- [ ] **Step 6: Build both ways**
+
+  Run: `cabal build && cabal build -fserver_postgres`
+
+- [ ] **Step 7: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store/Postgres.hs src/Simplex/FileTransfer/Server/Store/Postgres/Config.hs src/Simplex/FileTransfer/Server/Env.hs
+  git add src/Simplex/FileTransfer/Server/Store/Postgres.hs src/Simplex/FileTransfer/Server/Store/Postgres/Config.hs src/Simplex/FileTransfer/Server/Store/Postgres/Migrations.hs src/Simplex/FileTransfer/Server/Env.hs simplexmq.cabal
+  git commit -m "feat(xftp): add PostgreSQL store skeleton with schema migration"
+  ```
+
+---
+
+## Task 7: Implement `PostgresFileStore` operations
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Store/Postgres.hs`
+
+- [ ] **Step 1: Implement `addFile`**
+
+  `INSERT INTO files (sender_id, file_size, file_digest, sender_key, file_path, created_at, status) VALUES (?,?,?,?,NULL,?,?)`. Catch unique violation with `handleDuplicate` → `DUPLICATE_`. Call `withLog "addFile"` after.
+
+- [ ] **Step 2: Implement `getFile`**
+
+  For `SFSender`: `SELECT ... FROM files WHERE sender_id = ?`. Construct `FileRec` with `newTVarIO` per TVar field. `recipientIds = S.empty`.
+  For `SFRecipient`: `SELECT f.*, r.recipient_key FROM recipients r JOIN files f ON r.sender_id = f.sender_id WHERE r.recipient_id = ?`.
+
+- [ ] **Step 3: Implement `setFilePath`**
+
+  `UPDATE files SET file_path = ? WHERE sender_id = ? AND file_path IS NULL`. Use `assertUpdated`. Call `withLog "setFilePath"`.
+
+- [ ] **Step 4: Implement `addRecipient`**
+
+  `INSERT INTO recipients (recipient_id, sender_id, recipient_key) VALUES (?,?,?)`. `handleDuplicate` → `DUPLICATE_`. Call `withLog "addRecipient"`.
+
+- [ ] **Step 5: Implement `deleteFile`, `blockFile`**
+
+  `deleteFile`: `DELETE FROM files WHERE sender_id = ?` (CASCADE). `withLog "deleteFile"`.
+  `blockFile`: `UPDATE files SET status = ? WHERE sender_id = ?`. `assertUpdated`. `withLog "blockFile"`.
+
+- [ ] **Step 6: Implement `deleteRecipient`, `ackFile`**
+
+  `deleteRecipient`: `DELETE FROM recipients WHERE recipient_id = ?`. `withLog "deleteRecipient"`.
+  `ackFile`: same + return `Left AUTH` if 0 rows.
+
+- [ ] **Step 7: Implement `expiredFiles`, `getUsedStorage`, `getFileCount`**
+
+  `expiredFiles`: `SELECT sender_id, file_path, file_size FROM files WHERE created_at + ? < ? LIMIT ?`.
+  `getUsedStorage`: `SELECT COALESCE(SUM(file_size), 0) FROM files`.
+  `getFileCount`: `SELECT COUNT(*) FROM files`.
+
+- [ ] **Step 8: Add `ToField`/`FromField` instances**
+
+  For `RoundedFileTime` (Int64 wrapper), `ServerEntityStatus` (Text via StrEncoding), `C.APublicAuthKey` (Binary via `encodePubKey`/`decodePubKey`). Check SMP's `QueueStore/Postgres.hs` for existing instances to import.
+
+- [ ] **Step 9: Wrap mutation operations in `uninterruptibleMask_`**
+
+  Operations that combine a DB write with a TVar update (e.g., `getFile` constructs `FileRec` with `newTVarIO`) must be wrapped in `E.uninterruptibleMask_` to prevent async exceptions from leaving inconsistent state. Follow SMP's `addQueue_`, `deleteStoreQueue` pattern.
+
+- [ ] **Step 10: Build**
+
+  Run: `cabal build -fserver_postgres`
+
+- [ ] **Step 11: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Store/Postgres.hs
+  git add src/Simplex/FileTransfer/Server/Store/Postgres.hs
+  git commit -m "feat(xftp): implement PostgresFileStore operations"
+  ```
+
+---
+
+## Task 8: Add INI config, Main.hs dispatch, startup validation
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Main.hs`
+- Modify: `src/Simplex/FileTransfer/Server/Env.hs`
+
+- [ ] **Step 1: Update `iniFileContent` in `Main.hs`**
+
+  Add to `[STORE_LOG]` section: `store_files: memory`, commented-out `db_connection`, `db_schema`, `db_pool_size`, `db_store_log` keys. Follow SMP's `optDisabled'` pattern for commented defaults.
+
+- [ ] **Step 2: Add `StartOptions` and `--confirm-migrations` flag**
+
+  ```haskell
+  data StartOptions = StartOptions
+    { confirmMigrations :: MigrationConfirmation
+    }
+  ```
+  Add to `Start` command parser with default `MCConsole`. Thread through to `runServer`.
+
+- [ ] **Step 3: Add store_files INI parsing and CPP-guarded Postgres dispatch**
+
+  In `runServer`: read `store_files` from INI (`fromRight "memory" $ lookupValue "STORE_LOG" "store_files" ini`). Add `"database"` branch (CPP-guarded) that constructs `PostgresFileStoreCfg` using `iniDBOptions ini defaultXFTPDBOpts` and `enableDbStoreLog'` pattern. Non-postgres build: `exitError`.
+
+- [ ] **Step 4: Add `XSCDatabase` branch in `newXFTPServerEnv` (`Env.hs`)**
+
+  CPP-guarded pattern match on `XSCDatabase dbCfg`: `newFileStore dbCfg`, `storeLog = Nothing`.
+
+- [ ] **Step 5: Add startup config validation**
+
+  Add `checkFileStoreMode` (CPP-guarded) before `run`: validate conflicting storeLog file + database mode, missing schema, etc. per design doc.
+
+- [ ] **Step 6: Build both ways**
+
+  Run: `cabal build && cabal build -fserver_postgres`
+
+- [ ] **Step 7: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Main.hs src/Simplex/FileTransfer/Server/Env.hs
+  git add src/Simplex/FileTransfer/Server/Main.hs src/Simplex/FileTransfer/Server/Env.hs
+  git commit -m "feat(xftp): add PostgreSQL INI config, store dispatch, startup validation"
+  ```
+
+---
+
+## Task 9: Add database import/export CLI commands
+
+**Files:**
+- Modify: `src/Simplex/FileTransfer/Server/Main.hs`
+
+- [ ] **Step 1: Add `Database` CLI command (CPP-guarded)**
+
+  Add `Database StoreCmd DBOpts` constructor to `CliCommand`. Add `database` subcommand parser with `import`/`export` subcommands + `dbOptsP defaultXFTPDBOpts`.
+
+- [ ] **Step 2: Implement `importFileStoreToDatabase`**
+
+  1. `confirmOrExit` with database details.
+  2. Create temporary `STMFileStore`, replay StoreLog via `readWriteFileStore`.
+  3. Create `PostgresFileStore` with `createSchema = True`, `confirmMigrations = MCYesUp`.
+  4. Batch-insert files using PostgreSQL COPY protocol. Progress every 10k.
+  5. Batch-insert recipients using COPY protocol.
+  6. Verify counts: `SELECT COUNT(*)` — warn on mismatch.
+  7. Rename StoreLog to `.bak`.
+  8. Report counts.
+
+- [ ] **Step 3: Implement `exportDatabaseToStoreLog`**
+
+  1. `confirmOrExit`. Fail if output file exists.
+  2. Create `PostgresFileStore` from config.
+  3. Open StoreLog for writing.
+  4. Fold over file records: write `AddFile` (with status), `AddRecipients`, `PutFile` per file.
+  5. Close StoreLog, report counts.
+
+- [ ] **Step 4: Build**
+
+  Run: `cabal build -fserver_postgres`
+
+- [ ] **Step 5: Format and commit**
+
+  ```bash
+  fourmolu -i src/Simplex/FileTransfer/Server/Main.hs
+  git add src/Simplex/FileTransfer/Server/Main.hs
+  git commit -m "feat(xftp): add database import/export CLI commands"
+  ```
+
+---
+
+## Task 10: Add Postgres tests
+
+**Files:**
+- Modify: `tests/XFTPClient.hs`
+- Modify: `tests/Test.hs`
+- Create: `tests/CoreTests/XFTPStoreTests.hs`
+
+- [ ] **Step 1: Add test fixtures in `tests/XFTPClient.hs`**
+
+  ```haskell
+  testXFTPStoreDBOpts :: DBOpts
+  testXFTPStoreDBOpts =
+    DBOpts
+      { connstr = "postgresql://test_xftp_server_user@/test_xftp_server_db",
+        schema = "xftp_server_test",
+        poolSize = 10,
+        createSchema = True
+      }
+  ```
+  Add `testXFTPDBConnectInfo :: ConnectInfo` matching the connection string.
+
+- [ ] **Step 2: Add Postgres server test group in `tests/Test.hs`**
+
+  CPP-guarded block that runs existing `xftpServerTests` with Postgres store config, wrapped in `postgressBracket testXFTPDBConnectInfo`. Parameterize `withXFTPServer` to accept store config if needed.
+
+- [ ] **Step 3: Create `tests/CoreTests/XFTPStoreTests.hs` — unit tests**
+
+  Test `PostgresFileStore` operations directly:
+  - `addFile` + `getFile SFSender` round-trip.
+  - `addFile` duplicate → `DUPLICATE_`.
+  - `getFile` nonexistent → `AUTH`.
+  - `setFilePath` + verify `WHERE file_path IS NULL` guard.
+  - `addRecipient` + `getFile SFRecipient` round-trip.
+  - `deleteFile` cascades recipients.
+  - `blockFile` + verify status.
+  - `expiredFiles` batch semantics.
+  - `getUsedStorage`, `getFileCount` correctness.
+
+- [ ] **Step 4: Add migration round-trip test**
+
+  Create `STMFileStore` with test data (files + recipients + blocked status) → export to StoreLog → import to Postgres → export back → compare StoreLog files byte-for-byte.
+
+- [ ] **Step 5: Build and run tests**
+
+  ```bash
+  cabal build -fserver_postgres test:simplexmq-test
+  cabal test --test-show-details=streaming --test-option=--match="/XFTP/" -fserver_postgres
+  ```
+
+- [ ] **Step 6: Format and commit**
+
+  ```bash
+  fourmolu -i tests/CoreTests/XFTPStoreTests.hs tests/XFTPClient.hs
+  git add tests/CoreTests/XFTPStoreTests.hs tests/XFTPClient.hs tests/Test.hs
+  git commit -m "test(xftp): add PostgreSQL backend tests"
+  ```

plans/20260328_01_server_batched_sub_processing.md

@@ -0,0 +1,152 @@
+# Server: batched SUB command processing
+
+Implementation plan for Part 1 of [RFC 2026-03-28-subscription-performance](../rfcs/2026-03-28-subscription-performance.md).
+
+## Current state
+
+When a batch of ~135 SUB commands arrives, the server already batches:
+- Queue record lookups (`getQueueRecs` in `receive`, Server.hs:1151)
+- Command verification (`verifyLoadedQueue`, Server.hs:1152)
+
+But command processing is per-command (`foldrM process` in `client`, Server.hs:1372-1375). Each SUB calls `subscribeQueueAndDeliver` which calls `tryPeekMsg` - one DB query per queue. For Postgres, that's ~135 individual `SELECT ... FROM messages WHERE recipient_id = ? ORDER BY message_id ASC LIMIT 1` queries per batch.
+
+## Goal
+
+Replace ~135 individual message peek queries with 1 batched query per batch. No protocol changes.
+
+## Implementation
+
+### Step 1: Add `tryPeekMsgs` to MsgStoreClass
+
+File: `src/Simplex/Messaging/Server/MsgStore/Types.hs`
+
+Add to `MsgStoreClass`:
+
+```haskell
+tryPeekMsgs :: s -> [StoreQueue s] -> ExceptT ErrorType IO (Map RecipientId Message)
+```
+
+Returns a map from recipient ID to earliest pending message for each queue that has one. Queues with no messages are absent from the map.
+
+### Step 2: Parameterize `deliver` to accept pre-fetched message
+
+File: `src/Simplex/Messaging/Server.hs`
+
+Currently `deliver` (inside `subscribeQueueAndDeliver`, line 1641) calls `tryPeekMsg ms q`. Add a parameter for an optional pre-fetched message:
+
+```haskell
+deliver :: Maybe Message -> (Bool, Maybe Sub) -> M s ResponseAndMessage
+deliver prefetchedMsg (hasSub, sub_) = do
+  stats <- asks serverStats
+  fmap (either ((,Nothing) . err) id) $ liftIO $ runExceptT $ do
+    msg_ <- maybe (tryPeekMsg ms q) (pure . Just) prefetchedMsg
+    ...
+```
+
+When `Nothing` is passed, falls back to individual `tryPeekMsg` (existing behavior). When `Just msg` is passed, uses it directly (batched path).
+
+### Step 3: Pre-fetch messages before the processing loop
+
+File: `src/Simplex/Messaging/Server.hs`
+
+Currently (lines 1372-1375):
+
+```haskell
+forever $
+  atomically (readTBQueue rcvQ)
+    >>= foldrM process ([], [])
+    >>= \(rs_, msgs) -> ...
+```
+
+Add a pre-fetch step before the existing loop:
+
+```haskell
+forever $ do
+  batch <- atomically (readTBQueue rcvQ)
+  msgMap <- prefetchMsgs batch
+  foldrM (process msgMap) ([], []) batch
+    >>= \(rs_, msgs) -> ...
+```
+
+`prefetchMsgs` scans the batch, collects queues from SUB commands that have a verified queue (`q_ = Just (q, _)`), calls `tryPeekMsgs` once, returns the map. For batches with no SUBs it returns an empty map (no DB call).
+
+`process` passes the looked-up message (or Nothing) through to `processCommand` and down to `deliver`.
+
+The `foldrM process` loop, `processCommand`, `subscribeQueueAndDeliver`, and all other command handlers stay structurally the same. Only `deliver` gains one parameter, and the `client` loop gains one pre-fetch call.
+
+### Step 4: Review
+
+Review the typeclass signature and server usage. Confirm the interface has the right shape before implementing store backends.
+
+### Step 5: Implement for each store backend
+
+#### Postgres
+
+File: `src/Simplex/Messaging/Server/MsgStore/Postgres.hs`
+
+Single query using `DISTINCT ON`:
+
+```sql
+SELECT DISTINCT ON (recipient_id)
+  recipient_id, msg_id, msg_ts, msg_quota, msg_ntf_flag, msg_body
+FROM messages
+WHERE recipient_id IN ?
+ORDER BY recipient_id, message_id ASC
+```
+
+Build `Map RecipientId Message` from results.
+
+#### STM
+
+File: `src/Simplex/Messaging/Server/MsgStore/STM.hs`
+
+Loop over queues, call `tryPeekMsg` for each, collect into map.
+
+#### Journal
+
+File: `src/Simplex/Messaging/Server/MsgStore/Journal.hs`
+
+Loop over queues, call `tryPeekMsg` for each, collect into map.
+
+### Step 6: Handle edge cases
+
+1. **Mixed batches**: `prefetchMsgs` collects only SUB queues. Non-SUB commands get Nothing for the pre-fetched message and process unchanged.
+
+2. **Already-subscribed queues**: Include in pre-fetch - `deliver` is called for re-SUBs too (delivers pending message).
+
+3. **Service subscriptions**: The pre-fetch doesn't care about service state. `sharedSubscribeQueue` handles service association in STM; message peek is the same.
+
+4. **Error queues**: Verification errors from `receive` are Left values in the batch. `prefetchMsgs` only looks at Right values with SUB commands.
+
+5. **Empty pre-fetch**: If batch has no SUBs (e.g., all ACKs), `prefetchMsgs` returns empty map, no DB call made.
+
+### Step 7: Batch other commands (future, not in scope)
+
+The same pattern (pre-fetch before loop, parameterize handler) can extend to:
+- `ACK` with `tryDelPeekMsg` - batch delete+peek
+- `GET` with `tryPeekMsg` - same map lookup
+
+Lower priority since these don't have the N-at-once pattern of subscriptions.
+
+## File changes summary
+
+| File | Change |
+|---|---|
+| `src/Simplex/Messaging/Server/MsgStore/Types.hs` | Add `tryPeekMsgs` to typeclass |
+| `src/Simplex/Messaging/Server/MsgStore/Postgres.hs` | Implement `tryPeekMsgs` with batch SQL |
+| `src/Simplex/Messaging/Server/MsgStore/STM.hs` | Implement `tryPeekMsgs` as loop |
+| `src/Simplex/Messaging/Server/MsgStore/Journal.hs` | Implement `tryPeekMsgs` as loop |
+| `src/Simplex/Messaging/Server.hs` | Add `prefetchMsgs`, parameterize `deliver` |
+
+## Testing
+
+1. Existing server tests must pass unchanged (correctness preserved).
+2. Add a test that subscribes a batch of queues (some with pending messages, some without) and verifies all get correct SOK + MSG responses.
+3. Prometheus metrics: existing `qSub` stat should still increment correctly.
+
+## Performance expectation
+
+For 300K queues across ~2200 batches:
+- Before: ~300K individual DB queries
+- After: ~2200 batched DB queries (one per batch of ~135)
+- ~136x reduction in DB round-trips

plans/20260401_01_batch_queue_associations.md

@@ -0,0 +1,126 @@
+# Server: batch queue service associations
+
+When a batch of SUB or NSUB commands arrives from a service client, each command that needs a new or removed service association calls `setQueueService` individually - one DB write per command. For 135 commands per batch, that's 135 individual `UPDATE msg_queues` queries.
+
+## Goal
+
+Reduce to at most 2 DB queries per batch (one for rcv associations, one for ntf associations), using `UPDATE ... RETURNING recipient_id` to identify which queues were actually updated.
+
+Also fuse message pre-fetch and association batching into a single batch preparation step with a clean contract.
+
+## Contract
+
+```haskell
+prepareBatch :: Maybe ServiceId -> NonEmpty (VerifiedTransmission s) -> M s (Either ErrorType (Map RecipientId (Maybe Message, Maybe (Either ErrorType ()))))
+```
+
+`Left e` = batch-level failure (message pre-fetch or association query failed entirely). All SUBs/NSUBs in the batch get this error.
+
+`Right map` = per-queue results as a tuple:
+- `Maybe Message` - pre-fetched message for SUB queues, `Nothing` for NSUB or no message
+- `Maybe (Either ErrorType ())` - association result. `Nothing` = no update needed. `Just (Right ())` = update succeeded. `Just (Left e)` = update failed for this queue.
+
+One map, one lookup per queue. `processCommand` passes both values to `subscribeQueueAndDeliver` / `subscribeNotifications` -> `sharedSubscribeQueue`.
+
+Queues not in the map (non-SUB/NSUB commands, failed verification) are not affected.
+
+## prepareBatch implementation
+
+One accumulating fold over the batch, collecting three lists:
+- `subMsgQs :: [StoreQueue s]` - SUB queues for message pre-fetch
+- `rcvAssocQs :: [StoreQueue s]` - SUB queues needing `rcv_service_id` update (`clntServiceId /= rcvServiceId qr`)
+- `ntfAssocQs :: [StoreQueue s]` - NSUB queues needing `ntf_service_id` update (`clntServiceId /= ntfServiceId` from `NtfCreds`)
+
+Classification reads from the already-loaded `QueueRec` in `VerifiedTransmission` - no extra DB query.
+
+Then three store calls (each skipped if its list is empty):
+1. `tryPeekMsgs ms subMsgQs` -> `Map RecipientId Message`
+2. `setRcvQueueServices (queueStore ms) clntServiceId rcvAssocQs` -> `Set RecipientId`
+3. `setNtfQueueServices (queueStore ms) clntServiceId ntfAssocQs` -> `Set RecipientId`
+
+Then one pass to merge results into `Map RecipientId (Maybe Message, Maybe (Either ErrorType ()))`:
+- For each SUB queue: `(M.lookup rId msgMap, assocResult rId rcvUpdated rcvAssocQs)`
+- For each NSUB queue: `(Nothing, assocResult rId ntfUpdated ntfAssocQs)`
+
+Where `assocResult rId updated assocQs` = if the queue was in `assocQs` (needed update), then `Just (Right ())` if `rId` is in `updated`, else `Just (Left AUTH)`. If not in `assocQs` (no update needed), `Nothing`.
+
+If any of the three calls fails entirely, return `Left e`.
+
+## Store interface
+
+Replace the polymorphic `setQueueServices` with two plain functions in `QueueStoreClass`:
+
+```haskell
+setRcvQueueServices :: s -> Maybe ServiceId -> [q] -> IO (Set RecipientId)
+setNtfQueueServices :: s -> Maybe ServiceId -> [q] -> IO (Set RecipientId)
+```
+
+No `SParty p` polymorphism. Each function knows its column.
+
+### Postgres implementation
+
+`setRcvQueueServices`:
+```sql
+UPDATE msg_queues SET rcv_service_id = ?
+WHERE recipient_id IN ? AND deleted_at IS NULL
+RETURNING recipient_id
+```
+
+`setNtfQueueServices`:
+```sql
+UPDATE msg_queues SET ntf_service_id = ?
+WHERE recipient_id IN ? AND notifier_id IS NOT NULL AND deleted_at IS NULL
+RETURNING recipient_id
+```
+
+After each batch query, for each queue in the returned set:
+1. Read QueueRec TVar, update with new serviceId
+2. Write store log entry
+
+### STM implementation
+
+Loop over queues, call existing per-item logic, collect succeeded `RecipientId`s into a Set.
+
+## Downstream changes in Server.hs
+
+### processCommand
+
+Gains one parameter: `Map RecipientId (Maybe Message, Maybe (Either ErrorType ()))`.
+
+SUB case: `M.lookup entId prepared` gives `Just (msg_, assocResult)` or `Nothing`. Pass both to `subscribeQueueAndDeliver`.
+
+NSUB case: `M.lookup entId prepared` gives `Just (Nothing, assocResult)` or `Nothing`. Pass `assocResult` to `subscribeNotifications`.
+
+Forwarded commands: pass `M.empty`.
+
+### subscribeQueueAndDeliver
+
+Takes `Maybe Message` and `Maybe (Either ErrorType ())` as before. No change in how it uses them.
+
+### sharedSubscribeQueue
+
+Takes `Maybe (Either ErrorType ())`. On paths needing association update:
+- `Just (Left e)` -> return error
+- `Just (Right ())` -> skip `setQueueService`, proceed with STM work
+- `Nothing` -> no update needed, proceed with existing logic
+
+## Implementation order (top-down)
+
+1. Define the `prepareBatch` contract and thread one map through `processCommand` -> `subscribeQueueAndDeliver` / `subscribeNotifications` -> `sharedSubscribeQueue` (Server.hs)
+2. Implement `prepareBatch` with the fold, three calls, and merge (Server.hs)
+3. Add `setRcvQueueServices` and `setNtfQueueServices` to `QueueStoreClass` (Types.hs)
+4. Implement for Postgres with batch `UPDATE ... RETURNING` (Postgres.hs)
+5. Implement for STM as loop (STM.hs)
+6. Implement for Journal as delegation (Journal.hs)
+
+At step 2, store functions can initially be stubs returning empty sets. Steps 3-6 fill in the real implementations.
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `src/Simplex/Messaging/Server.hs` | `prepareBatch` with fold + merge; one map parameter through `processCommand` -> `subscribeQueueAndDeliver` / `subscribeNotifications` -> `sharedSubscribeQueue` |
+| `src/Simplex/Messaging/Server/QueueStore/Types.hs` | Add `setRcvQueueServices`, `setNtfQueueServices` to `QueueStoreClass` |
+| `src/Simplex/Messaging/Server/QueueStore/Postgres.hs` | Implement with batch `UPDATE ... RETURNING` + per-item TVar/log updates |
+| `src/Simplex/Messaging/Server/QueueStore/STM.hs` | Implement as loop |
+| `src/Simplex/Messaging/Server/MsgStore/Journal.hs` | Delegate to underlying store |

plans/done/2024-09-01-smp-message-storage.md

@@ -0,0 +1,180 @@
+
+# SMP router message storage
+
+## Problem
+
+Currently SMP routers store all queues in router memory. As the traffic grows, so does the number of undelivered messages. What is worse, Haskell is not avoiding heap fragmentation when messages are allocated and then de-allocated - undelivered messages use ByteString and GC cannot move them around, as they use pinned memory.
+
+## Possible solutions
+
+### Solution 1: solve only GC fragmentation problem
+
+Move from ByteString to some other primitive to store messages in memory long term, e.g. ShortByteString, or manage allocation/de-allocation of stored messages manually in some other way.
+
+Pros: the simplest solution that avoids substantial re-engineering of the router.
+
+Cons:
+- not a long term solution, as memory growth still has limits.
+- may be ineffective, as it introduces additional copying of bytes.
+
+### Solution 2: move message storage to hard drive
+
+Use files or RocksDB to store messages.
+
+Pros:
+- much lower memory usage.
+- no message loss in case of abnormal router termination (important until clients have delivery redundancy).
+- this is a long term solution, and at some point it might need to be done anyway.
+
+Cons:
+- substantial re-engineering costs and risks.
+- metadata privacy. Currently we only save undelivered messages when router is restarted, with this approach all messages will be stored for some time. this argument is limited, as hosting providers of VMs can make memory snapshots too, on the other hand they are harder to analyze than files. On another hand, with this approach messages will be stored for a shorter time.
+
+#### RocksDB and other key-value stores
+
+The downside of any key-value stores is that they don't seem to have efficient primitives for sequential delivery. While sequential delivery can be modelled with linked lists, they would require 1 key insert (on send), 3 key updates (1 update to update queue data on send, 1 update of the last message to point to the next, 1 update on delivery or message expiration) and 1 key deletion (on delivery or message expiration) for each delivered message.
+
+This might result in substantial write amplification and compacting costs.
+
+In general, tree structures that are efficient for quick lookups and updates, given approximately fixed value size, are inefficient for modelling queues.
+
+#### Files
+
+The upside of files is that they are well suited for sequential delivery and don't result in the same churn, with careful design, as trees do.
+
+The downside of filesystem is that it does not scale well with the large number of files in a folder, so queues will have to be spread across multiple folders, following tree-like structure.
+
+I could not find an available library that efficiently models sequential delivery in highly concurrent environment.
+
+A possible design could be the following.
+
+##### Queue folder and files
+
+Each message queue is stored in its own folder (see below on folder locations). Folder would contain these files:
+
+- `messages.abcd.log` - the file that is used to read messages from, sequentially
+- `messages.efgh.log` - the optional file that is used to write messages, in case it is different from read file.
+- `queue.log` - append-only file where the last line represents the current queue state
+- `queue.timestamp.log` - previous states of queue.log file
+
+Each line in "queue.log" file has this syntax
+
+```abnf
+queueLogLine =
+    %s"read_file=" base64
+    %s"read_msg=" digits
+    %s"read_byte=" digits
+    %s"write_file=" base64
+    %s"write_msg=" digits
+```
+
+When queue is first requested by the router:
+
+```c
+if queue folder exists:
+    read queue state from last line of queue.log
+    if queue.log contained more than one line: // compaction
+        copy queue.log to queue.timestamp.log
+        write one line queue state to queue.log
+else:
+    create queue folder
+    create messages.abcd.log (abcd is some random string)
+    read_msg = 0
+    read_byte = 0
+    create queue.log with one line: "read_file=abcd read_msg=0 read_byte=0 write_files=abcd write_msg=0"
+open read_file in ReadMode and seek to read_byte position
+nextReadByte = read_byte
+nextReadMsg = read_msg
+open write_file in AppendMode
+```
+
+When message is added to the queue (assumes that queue state is loaded to router memory, if not the previous section will be done first):
+
+```c
+if write_msg > max_queue_messages:
+    return quota error
+else if write_msg = max_queue_messages:
+    add quota_exceeded message to write_file
+    update queue state: write_msg += 1
+    append updated queue state to queue.log
+else
+    // It is required that `max_queue_messages < max_file_messages`,
+    // so that we never need more than one additional write file.
+    if write_msg >= max_file_messages: // queue file rotation
+        create messages.efgh.log // efgh is some random string
+        update queue state: write_file=efgh write_msg=0 // read file remains the same as it was
+        append updated queue state to queue.log
+        copy queue.log to queue.timestamp.log
+        // `old` needs to be defined to limit the number and storage duration,
+        // preserving not more than N files, and not more than M days files, "and then some"
+        // (that is if the queue has high churn, we have file from M days before in any case, for any debugging).
+        delete `old` `queue.timestamp.log` files
+        write one line queue state to queue.log // compaction
+
+    add message to write_file
+    update queue state: write_msg += 1
+    append updated queue state to queue.log
+```
+
+The above algorithm assumes `max_queue_messages < than max_file_messages`, so that we never need more than one write file.
+
+When message is delivered, it is simply read from the read queue, queue state does not change yet:
+
+```c
+if nextReadMsg > read_msg:
+    deliver cached message, no need to read it again
+else
+    read message from read_file handle
+    nextReadMsg = read_msg + 1
+    nextReadByte = current position in file
+```
+
+When message delivery is acknowledged, the read queue needs to be advanced, and possibly switched to read from the current write queue:
+
+```c
+if nextReadByte == read_byte:
+    return error // nothing was delivered
+else if nextReadByte = EOF:
+    // end of file is reached, possibly some other condition,
+    // but it should allow changing max_file_messages on server restart
+    currReadFile = read_file
+    read_file = write_file
+    read_msg = 0
+    read_byte = 0
+    append updated queue state to queue.log
+    delete currReadFile
+else
+    read_msg += 1
+    read_byte = nextReadByte
+    // `seek` should not be necessary, as the handle is already at nextReadByte position here
+    // seek to read_byte
+    append updated queue state to queue.log
+```
+
+The above algorithm delegates the problem of compaction and fragmentation management to file system, that is very optimized for such scenarios.
+
+Also, read and write files will grow to almost a constant size, so the space they used may be re-used.
+
+An important consideration is that writes to queue.log and message.log files and queue state modifications have to be sequential, without concurrency - it can be managed with the usual locks.
+
+##### Queue folders structure
+
+Most Linux systems use EXT4 filesystem where the file lookup time scales linearly to the number of files. While alternatives with logarithmic lookup time exist (XFS), they may be very complex to configure on the existing systems.
+
+So storing all queue folders in one folder won't scale.
+
+To solve this problem we could use recipient queue ID in base64url format not as a folder name, but as a folder path, splitting it to path fragments of some length. The number of fragments can be configurable and migration to a different fragment size can be supported as the number of queues on a given router grows.
+
+Currently, queue ID is 24 bytes random number, thus allowing 2^192 possible queue IDs. If we assume that a router must hold 1b queues, it means that we have ~2^162 possible addresses for each existing queue. 24 bytes in base64 is 32 characters that can be split into say 8 fragments with 4 characters each, so that queue folder path for queue with ID `abcdefghijklmnopqrstuvwxyz012345` would be:
+
+`/var/opt/simplex/messages/abcd/efgh/ijkl/mnop/qrst/uvwx/yz01/2345`
+
+The maximum theoretic number of the folders on the 1st level is 64^4, or 2^24 ~ 16m - this is probably still a large number of subfolders for EXT4. Given that addresses are random, all the possible combinations in the first folder can be used with a large number of queues.
+
+So we could use an unequal split of path, two letters each and the last being long:
+
+`/var/opt/simplex/messages/ab/cd/ef/ghijklmnopqrstuvwxyz012345`
+
+The first three levels in this case can have 4096 subfolders each, and it gives 68b possible subfolders (64^2^3), so the last level will be sparse in case of 1b queues on the router. So we could make it 4 levels with 2 letters to never think about it, accounting for a large variance of the random numbers distribution:
+
+`/var/opt/simplex/messages/ab/cd/ef/gh/ijklmnopqrstuvwxyz012345`

plans/done/2024-09-15-shared-port.md

@@ -0,0 +1,162 @@
+
+# Sharing protocol ports with HTTPS
+
+Some networks block all ports other than web ports, including port 5223 used for SMP protocol by default. Running SMP routers on a common web port 443 would allow them to work on more networks. The routers would need to provide an HTTPS page for browsers (and probes).
+
+## Problem
+
+Browsers and tools rely on system CA bundles instead of certificate pinning.
+The crypto parameters used by HTTPS are different from what the protocols use.
+Public certificate providers like LetsEncrypt can only sign specific types of keys and Ed25519 isn't one of them.
+
+This means a router should distinguish browser and protocol clients and adjust its behavior to match.
+
+## Solution
+
+`tls` package has a server hook that allows producing a different set of `TLS.Credentials` according to a client-provided "Server Name Indication" extension.
+
+Since LE certificates are only handed out to domain names, TLS client will be sending the SNI.
+However client transports are constructed over connected sockets and the SNI wouldn't be present unless explicitly requested.
+When a client sends SNI, then it's a browser and web credentials should be used.
+Otherwise it's a protocol client to be offered the self-signed ca, cert and key.
+
+When a transport colocated with a HTTPS, its ALPN list should be extended with `h2 http/1.1`.
+The browsers will send it, and it should be checked before running transport client.
+If HTTP ALPN is detected, then the client connection is served with HTTP `Application` instead (the same "router information" page).
+
+If some client connects to router IP, doesn't send SNI and doesn't send ALPN, it will look like a pre-handshake client.
+In that case a router will send its handshake first.
+This can be mitigated by delaying its handshake and letting the probe to issue its HTTP request.
+
+## Implementation plan
+
+An unmodified client should be able to use protocols on port 443 right away.
+
+The switchover happens inside `runTransportServerState` before `runClient`:
+
+```haskell
+runServer (tcpPort, ATransport t) = do
+  -- ...
+  runTransportServerState_ ss started tcpPort serverParams tCfg $ \socket h -> do -- expose raw socket for warp-tls internals to attach
+    negotiated <- getSessionALPN
+    if allowHTTP t && isHTTP negotiated -- only attempt the switch for the TLS transport
+      then runHTTP socket (tlsContext h)-- ... collect data and produce values needed to run WAI Application
+      else runClient serverSignKey t h `runReaderT` env -- performs serverHandshake etc as usual
+```
+
+The web app and router live outside, so `runHttp` has to be provided by the `runSMPServer` caller.
+Additonally, Warp is using its `InternalInfo` object that's scoped to `withII` bracket.
+
+```haskell
+  runServer ini = do
+    -- ...
+
+    runWebServer ini ServerInformation {config, information} $ if sharedHttps then Nothing else webHttpsParams -- suppress serving https
+    if sharedHttps
+      then withRunHTTP staticFilesPath \attachStatic -> runSMPServer cfg (Just attachStatic) -- provide wrapped application runner
+      else runSMPServer cfg Nothing
+```
+
+### Upstream
+
+The implementation relies on a few modification to upstream code:
+- `warp-tls`: The library provides `httpOverTls`, but it wants to do handshake itself.
+  Since we have to do the handshake to switch on ALPN, the setup function has to be split.
+  This is a resonable change that may be upstreamed and nothing blocks us from using the recent version.
+- `warp`: Only the re-export of `serveConnection` is needed.
+  Unfortunately the most recent `warp` version can't be used right away due to dependency cascade around `http-5` and `auto-update-2`.
+  So a fork containing the backported re-export has to be used until the dependencies are refreshed.
+### TLS.ServerParams
+
+When a router has port sharing enabled, a new set of TLS params is loaded and combined with transport params:
+
+```haskell
+newEnv config = do
+  -- ...
+  tlsServerParams <- loadTLSServerParams caCertificateFile certificateFile privateKeyFile (alpn transportConfig)
+  sharedServerParams <- forM ((,) <$> sharedHttpsCredentials config <*> alpn transportConfig) $ \((chain, key), alpn) ->
+    let ca = Nothing -- It is possible to provide CA certificate, but it is typical for web server to use combined certificate chains
+    loadHTTPSServerParams tlsServerParams ca chain key alpn
+```
+
+`loadHTTPSServerParams` extends params with:
+1. `onALPNClientSuggest` hook gets `["h2", "http/1.1"]` added to the ALPN list which is now required.
+2. `onServerNameIndication` hook added, which upon detecting client SNI prepends the web credentials.
+3. `sharedCredentials = T.Credentials []` should be done to prevent transport credentials confusing browsers.
+    But that aborts key exchange somewhere in tls internals, so disabled for now.
+    As a workaround, another set of dummy credentials can be provided in the hope that any sane browser would reject them.
+    Like, RC4 ciphers, "impossible" digest combination, etc.
+
+### supportedParameters
+
+TLS certificate chains provided by LetsEncrypt use ECDSA/P256 and that requires extending `supportedParameters` with things disabled in transports:
+
+```haskell
+    browserCiphers =
+      [ TE.cipher_TLS13_AES128CCM8_SHA256
+      , TE.cipher_ECDHE_ECDSA_AES128CCM8_SHA256
+      , TE.cipher_ECDHE_ECDSA_AES256CCM8_SHA256
+      ]
+    browserGroups =
+      [ T.P256
+      ]
+    browserSigs =
+      [ (T.HashSHA256, T.SignatureECDSA),
+        (T.HashSHA384, T.SignatureECDSA)
+      ]
+```
+
+This may not be enough for other certificate providers.
+
+## Configuration
+
+> XXX: This is for the current implementation and should be updated.
+
+Web certificate chain is picked up from the WEB section:
+
+```ini
+[TRANSPORT]
+port: 443
+
+[WEB]
+https: 443
+cert: /etc/opt/simplex/web.cert
+key: /etc/opt/simplex/web.key
+
+# Alternatively, with a proper access configuration, the paths can point to the LE creds directly:
+# cert: /etc/letsencrypt/live/smp.hostname.tld/fullchain.pem
+# key: /etc/letsencrypt/live/smp.hostname.tld/privkey.pem
+```
+
+When `TRANSPORT.port` matches `WEB.https` the transport router becomes shared.
+
+Perhaps a more desirable option would be explicit configuration resulting in additional transported to run:
+
+```ini
+[TRANSPORT]
+port: 5223 ; pure protocol transport
+# control_port: 5224
+shared_port: 443 ; variant 1: register in TRANSPORT
+
+[WEB]
+https: 443
+cert: /etc/opt/simplex/web.cert
+key: /etc/opt/simplex/web.key
+# transport: on ; variant 2:
+```
+
+## Caveats
+
+Serving static files and the protocols together may pose a problem for those who currently use dedicated web servers as they should switch to embedded http handlers.
+
+As before, using embedded HTTP server is increasing attack surface.
+
+Users who want to run everything on a single host will have to add an extra IP address and bind routers to specific IPs instead of 0.0.0.0.
+An amalgamated router binary can be provided that would contain both SMP and XFTP routers, where transport will dispatch connections by handshake ALPN.
+
+## Alternative: Use transports routable with reverse-proxies
+
+An "industrial" reverse proxy may do the ALPN routing, serving HTTP by itself and delegating `smp` and `xftp` to protocol servers.
+Same with the `websockets`.
+
+Since this in effect does TLS termination, the protocol routers will have to rely on credentials from protocol handshakes.

plans/done/2024-11-25-journal-expiration.md

@@ -0,0 +1,16 @@
+
+# Expiring messages in journal storage
+
+## Problem
+
+The journal storage routers recently migrated to do not delete delivered or expired messages, they only update pointers to journal file lines. The messages are actually deleted when the whole journal file is deleted (when fully deleted or fully expired).
+
+The problem is that in case the queue stops receiving the new messages then writing of messages won't switch to the new journal file, and the current journal file containing delivered or expired messages would never be deleted.
+
+## Solution
+
+Remove current journal file and update queue_state.log during message expiration of "idle" queue (that is, without any new messages received or delivered within 3 hours) in case when:
+- the queue is "empty" after the expiration
+- the queue contains only quota marker(s), in which case move them to a new journal file and update the queue_state accordingly. Quota markers can be kept indefinitely to prevent writing the new messages to the dormant queues that reached capacity, so it's important to handle this case.
+
+Also remove current journal file when the queue is opened in case it is empty (as it would not be ever expired in case it remains empty), and also update queue_state.log

plans/done/2026-02-17-fix-subq-deadlock.md

@@ -0,0 +1,416 @@
+
+# Fix subQ deadlock: blocking writeTBQueue inside connLock
+
+## Problem
+
+Users report that message reception silently and permanently stops across all connections, with no error alerts. The app appears functional but no messages arrive. Recovery requires restart.
+
+Root cause: a deadlock between worker threads holding `connLock` and the `agentSubscriber` (sole `subQ` reader).
+
+### The deadlock mechanism
+
+`subQ` (`TBQueue ATransmission`, capacity 4096 on mobile / 1024 on desktop) is the single pipeline between the agent layer and the chat layer. The `agentSubscriber` thread (`Commands.hs:4373`) is its **sole reader**.
+
+Three code sites hold `connLock` and call blocking `writeTBQueue subQ` without a fullness check. When `subQ` is full, these block while holding the lock. If `agentSubscriber` simultaneously needs the same `connLock` (via `sendMessagesB_` → `withConnLocks`), it blocks too — creating a circular wait:
+
+- **Worker**: holds `connLock(X)`, waits for `subQ` space (needs `agentSubscriber` to read)
+- **agentSubscriber**: sole `subQ` reader, waits for `connLock(X)` (needs worker to release)
+- **Result**: permanent silent deadlock — no exception, no alert, all connections blocked
+
+### Confirmed deadlock scenarios
+
+**Scenario 1**: Delivery worker during queue rotation test
+
+```
+Delivery worker:                    agentSubscriber (sole subQ reader):
+  withConnLock(X) [2187]              readTBQueue subQ → processAgentMessageConn
+  ...DB operations...                 → sendPendingGroupMessages (on CON/SENT/QCONT)
+  notify → writeTBQueue subQ [2238]   → batchSendConnMessages → deliverMessagesB
+  [BLOCKED — subQ full]               → withAgent sendMessagesB [synchronous]
+                                      → sendMessagesB_ → withConnLocks({..X..}) [1708]
+                                      [BLOCKED — connLock(X) held]
+```
+
+**Scenario 2**: Async command worker during message ACK with notification
+
+```
+Async cmd worker:                   agentSubscriber (sole subQ reader):
+  tryWithLock "ICAck" [1930→1824]     readTBQueue subQ → processAgentMessageConn
+  → withConnLock(X)                   → sendPendingGroupMessages
+  → ack → ackQueueMessage [1899]      → sendMessagesB_ → withConnLocks({..X..})
+  → sendMsgNtf [2381]                [BLOCKED — connLock(X) held]
+  → writeTBQueue subQ [2386]
+  [BLOCKED — subQ full]
+```
+
+**Scenario 3**: Synchronous `ackMessage'` API (same mechanism as Scenario 2 but from external API caller)
+
+```
+ackMessage' caller:                 agentSubscriber (sole subQ reader):
+  withConnLock(X) [2254]              → sendMessagesB_ → withConnLocks({..X..})
+  → ack → ackQueueMessage [2267]      [BLOCKED — connLock(X) held]
+  → sendMsgNtf [2381]
+  → writeTBQueue subQ [2386]
+  [BLOCKED — subQ full]
+```
+
+### ConnId overlap verified
+
+No guard prevents a connection undergoing queue rotation (AM_QTEST_) or ACK processing from being included in `sendMessagesB_`'s batch. During these operations, the connection has `connStatus == ConnReady`, passing all filters in `memberSendAction`.
+
+### Cascade amplification
+
+Once any single deadlock triggers, `subQ` never drains. ALL other threads that attempt `writeTBQueue subQ` block progressively — their locks are held forever too. The entire threading system freezes within seconds.
+
+### Affected code sites (blocking `writeTBQueue subQ` inside `connLock`)
+
+| Site | File | Lock line | Write line | Events written |
+|------|------|-----------|------------|----------------|
+| `runSmpQueueMsgDelivery::notify` | Agent.hs | 2187 | 2238 | SWITCH SPCompleted, ERR INTERNAL |
+| `runSmpQueueMsgDelivery::internalErr/notifyDel` | Agent.hs | 2187 | 2238 (via notifyDel→notify) | ERR INTERNAL + delMsg |
+| `ackQueueMessage::sendMsgNtf` | Agent.hs | 2254 or 1930 | 2386 | MSGNTF |
+
+### Safe patterns that already exist in the codebase
+
+1. **`isFullTBQueue` + pending TVar** (used at `runCommandProcessing` lines 1782-1784/1937, and `runProcessSMP` lines 3027-3029/3216):
+   ```haskell
+   -- Before processing (e.g. line 1782):
+   pending <- newTVarIO []
+   -- During processing — safe notify (e.g. line 1937):
+   notify cmd =
+     let t = (corrId, connId, AEvt (sAEntity @e) cmd)
+      in atomically $ ifM (isFullTBQueue subQ) (modifyTVar' pendingCmds (t :)) (writeTBQueue subQ t)
+   -- After processing — flush (e.g. line 1784):
+   mapM_ (atomically . writeTBQueue subQ) . reverse =<< readTVarIO pending
+   ```
+
+2. **`nonBlockingWriteTBQueue`** (used at Client.hs:789, NtfSubSupervisor.hs:507):
+   ```haskell
+   nonBlockingWriteTBQueue q x = do
+     sent <- atomically $ tryWriteTBQueue q x
+     unless sent $ void $ forkIO $ atomically $ writeTBQueue q x
+   ```
+   Note: `nonBlockingWriteTBQueue` does NOT preserve ordering — the spawned background thread may complete out of order relative to subsequent direct writes from the same calling thread.
+
+### Exhaustive proof: no other deadlock scenarios exist
+
+All 15 `withConnLock` sites in Agent.hs were analyzed. Only 3 write to `subQ`:
+
+| withConnLock site | Writes subQ? | Safe? |
+|-------------------|-------------|-------|
+| switchConnectionAsync' (899) | No | ✓ |
+| setConnShortLinkAsync' (995) | No | ✓ |
+| setConnShortLink' (1031) | No | ✓ |
+| deleteConnShortLink' (1075) | No | ✓ |
+| allowConnection' (1407) | No | ✓ |
+| acceptContact' (1417) | No | ✓ |
+| sendMessagesB_ (1708, `withConnLocks`) | No | ✓ |
+| tryWithLock/runSmpCommand (1930) | Yes (1937) | ✓ — `isFullTBQueue` check |
+| tryMoveableWithLock/runSmpCommand (1931) | Yes (1937) | ✓ — `isFullTBQueue` check |
+| **runSmpQueueMsgDelivery AM_QTEST_ (2187)** | **Yes (2238)** | **✗ — DEADLOCK** |
+| **ackMessage' (2254)** | **Yes (2386)** | **✗ — DEADLOCK** |
+| switchConnection' (2298) | No | ✓ |
+| abortConnectionSwitch' (2328) | No | ✓ |
+| synchronizeRatchet' (2351) | No | ✓ |
+| suspendConnection' (2390) | No | ✓ |
+| **processSMP (3037)** | Yes (3216) | ✓ — `isFullTBQueue` check |
+
+Note: `processSMP` (line 3037) holds `connLock` and its local `notify` (line 3216) writes to `subQ`, but it uses the safe `isFullTBQueue` pattern. Its `ack` (line 3196) uses `enqueueCmd` (DB-only), NOT `ackQueueMessage`. The actual `ackQueueMessage` runs later from the async command worker via ICAck/ICAckDel.
+
+Other lock pairs checked — no circular dependencies:
+- `connLock × DB MVar`: DB never acquires connLock
+- `entityLock × connLock`: consistent ordering (entity first in chat, conn in agent)
+- `connLock(X) × connLock(Y)`: single agentSubscriber thread, one `withConnLocks` at a time
+
+---
+
+## Deadlock call graph: agentSubscriber → connLock
+
+All deadlock paths require `agentSubscriber` to synchronously acquire `connLock`. Exhaustive analysis shows that **every such path converges on a single agent function**: `sendMessagesB_` → `withConnLocks` (Agent.hs:1708). No other agent API function called synchronously from the agentSubscriber acquires connLock.
+
+Verified (FACT): `ackMessageAsync` → `enqueueCommand` only (no connLock). `toggleConnectionNtfs` → no lock. `deleteConnectionAsync` → `deleteLock` not `connLock`. `joinConnectionAsync` → `withInvLock` not `connLock`.
+
+Also verified (FACT): `Lock = TMVar Text` (Lock.hs:24) is **non-reentrant** — double acquisition on the same thread deadlocks.
+
+### All 22 trigger paths
+
+Every path goes through `deliverMessage`/`deliverMessages`/`deliverMessagesB` → `withAgent sendMessagesB` → `sendMessagesB_` → `withConnLocks`:
+
+| # | Trigger | Chat function | ConnIds locked | Risk |
+|---|---------|--------------|----------------|------|
+| 1 | Group CON (Invitee) | `introduceToAll` → broadcast XGrpMemNew | **ALL member connIds** | **HIGHEST** |
+| 2 | Group MSG XGrpLinkAcpt | `introduceToRemaining` → broadcast | **ALL member connIds** | **HIGHEST** |
+| 3 | Group CON (Invitee) | `sendIntroductions` → batch intros to new member | new member connId | Medium |
+| 4 | Group CON (Invitee) | `sendHistory` → batch to new member | new member connId | Medium |
+| 5 | Group CON | `sendPendingGroupMessages` | member connId | Medium |
+| 6 | Group SENT | `sendPendingGroupMessages` | member connId | Medium |
+| 7 | Group QCONT | `sendPendingGroupMessages` | member connId | Medium |
+| 8 | Group CON (PendingReview) | `introduceToModerators` → to moderators | moderator connIds | Medium |
+| 9 | Group CON (PreMember) | `sendXGrpMemCon` → to host | host connId | Low |
+| 10 | Group CON (PreMember) | `probeMatchingMemberContact` → probes + hashes | member + N matching connIds | Medium |
+| 11 | Direct CON | `probeMatchingMembers` → probes + hashes | contact + N matching connIds | Medium |
+| 12 | Direct JOINED | `sendAutoReply` | contact connId | Low |
+| 13 | Group JOINED | `sendGroupAutoReply` | member connId | Low |
+| 14 | Group INV | `sendXGrpMemInv` → to host | host connId | Low |
+| 15 | Group INV (legacy) | `sendGrpInvitation` → to contact | contact connId | Low |
+| 16 | Group MSG XGrpMemInv | `xGrpMemInv` → `sendGroupMemberMessage` | re-member connId | Low |
+| 17 | Group MSG XGrpMemDel | `forwardToMember` | deleted member connId | Low |
+| 18 | Group MSG XGrpLinkMem | `probeMatchingMemberContact` | member + N matching connIds | Medium |
+| 19 | Group MSG (dup relay) | `saveGroupRcvMsg` error → `sendDirectMemberMessage` | forwarder connId | Low |
+| 20 | SFDONE | `sendFileDescriptions` → to recipients | recipient connIds | Medium |
+| 21 | Group MSG XGrpLinkAcpt | `sendHistory` → to accepted member | accepted member connId | Medium |
+| 22 | Direct MSG (autoAccept) | `autoAcceptFile` → inline accept reply | contact connId | Low (test-only config) |
+
+### Key observations
+
+1. **Single bottleneck**: All 22 paths converge on `sendMessagesB_` → `withConnLocks` (Agent.hs:1708). The deadlock is between this lock acquisition and any worker thread holding `connLock` + blocking on `writeTBQueue subQ`.
+
+2. **Highest-risk paths** (#1, #2): Broadcasting to ALL group members in `introduceToAll` / `introduceToRemaining` acquires `withConnLocks` on ALL member connIds in a single batch. For large groups, this holds the agentSubscriber thread for a long time, during which subQ fills, which causes worker threads holding connLock on any of those connIds to deadlock.
+
+3. **Medium-risk paths** (#5-7): `sendPendingGroupMessages` fires on every CON/SENT/QCONT. These are frequent and lock the member's connId, which is the SAME connId that a delivery worker or ACK worker may hold while writing to subQ.
+
+---
+
+## Analysis: `withConnLocks` in `sendMessagesB_`
+
+### FACT: the lock protects ratchet encryption state
+
+`sendMessagesB_` (Agent.hs:1708-1713) acquires `withConnLocks` and executes:
+
+1. **`getConn_`** — reads connection metadata, send queues from DB
+2. **`setConnPQSupport`** — updates PQ encryption flag per connection
+3. **`enqueueMessagesB`** → `enqueueMessageB` → `storeSentMsg_` which calls:
+   - **`updateSndIds`** (AgentStore.hs:899) — increments `internalSndId` (sequential send counter)
+   - **`agentRatchetEncryptHeader`** (Agent.hs:3698) — reads current ratchet via `getRatchetForUpdate`, encrypts message header via `rcEncryptHeader`, writes advanced ratchet state via `updateRatchet`
+   - **`createSndMsg`** + **`createSndMsgDelivery`** — inserts message and delivery records
+
+All operations run within `unsafeWithStore` → `withTransaction` (single DB transaction per batch).
+
+### FACT: the lock CANNOT be removed
+
+Without `withConnLocks`, concurrent `sendMessagesB_` calls targeting the same connection would:
+- Read the same ratchet state, both encrypt, one overwrite the other → **ratchet desync** (unrecoverable)
+- Get duplicate `internalSndId` values → **message ID collision**
+- Race on `setConnPQSupport` → **PQ state inconsistency**
+
+The lock serializes ALL operations on the connection's encryption state. Removing it would introduce data corruption.
+
+Note: `sendMessage` (singular, line 530) uses the same `sendMessagesB_` function — there is no lock-free send path.
+
+### Eliminated strategies
+
+- **Strategy C (remove lock)**: The lock protects ratchet encryption. Removing it causes unrecoverable ratchet desync. Eliminated.
+- **Strategy A (async dispatch)**: All 22 chat-layer callers use `deliverMessagesB` return values (delivery IDs, PQ state) synchronously. `forkIO` loses results. Eliminated.
+- **Strategy W (isFullTBQueue + pending TVar)**: The existing pattern (lines 1937, 3216) buffers events in a local TVar and flushes after lock release. Between lock release and flush, another thread can acquire the same connLock and write events to subQ — reordering events within the same connection. This trades a visible deadlock for invisible ordering bugs. Eliminated.
+- **Strategy O (per-connection overflow queues)**: Bounded overflow queues with "drop when full" were analyzed. Drop consequences are unacceptable at 5 of 6 write sites — CONF, INFO, CON cause permanent connection failure after ACK; INV loses connection invitations; SENT/MERR leave messages stuck forever. Unbounded overflow defeats backpressure. Eliminated.
+
+---
+
+## Solution: move subQ writes outside connLock
+
+### Root cause
+
+The `writeTBQueue subQ` calls at the 3 deadlock sites are inside `connLock` by accident of code structure, not necessity. `connLock` protects ratchet encryption state and DB consistency. The `notify` calls write informational events to `subQ` — they do not modify any state that `connLock` protects.
+
+Moving the writes outside the lock scope eliminates the deadlock: blocking `writeTBQueue subQ` without holding `connLock` is safe — agentSubscriber is free to acquire the lock, process events, and drain `subQ`.
+
+### Why reordering doesn't matter at these sites
+
+The chat layer handlers for the 3 deadlock site events do NOT advance the ratchet:
+
+| Event | Chat handler | Calls sendMessagesB_? |
+|-------|-------------|----------------------|
+| SWITCH SPCompleted | Creates internal chat item, updates UI | **No** |
+| ERR INTERNAL | Logs error to view | **No** |
+| MSGNTF | `toView CEvtNtfMessage` → empty output | **No** |
+
+Events that DO trigger ratchet advances (CON, SENT, QCONT → `sendPendingGroupMessages` → `sendMessagesB_`) are all already written OUTSIDE `connLock` in the current code.
+
+Ratchet state lives in the DB, not in subQ events. agentSubscriber processes events sequentially regardless of arrival order. The SENT-before-SWITCH race already exists in the current code (new queue worker writes SENT outside connLock while old queue worker writes SWITCH inside connLock).
+
+### Fix: Site 1 — `runSmpQueueMsgDelivery` AM_QTEST_ (line 2187)
+
+Restructure `withConnLock` to return the event, write outside.
+
+**Current code** (Agent.hs:2187-2214):
+```haskell
+AM_QTEST_ -> withConnLock c connId "runSmpQueueMsgDelivery AM_QTEST_" $ do
+  withStore' c $ \db -> setSndQueueStatus db sq Active
+  SomeConn _ conn <- withStore c (`getConn` connId)
+  case conn of
+    DuplexConnection cData' rqs sqs -> do
+      let addr = qAddress sq
+      case findQ addr sqs of
+        Just SndQueue {dbReplaceQueueId = Just replacedId, primary} ->
+          case removeQP (\sq' -> dbQId sq' == replacedId && not (sameQueue addr sq')) sqs of
+            Nothing -> internalErr msgId "sent QTEST: queue not found in connection"
+            Just (sq', sq'' : sqs') -> do
+              checkSQSwchStatus sq' SSSendingQTEST
+              atomically $ TM.delete (qAddress sq') $ smpDeliveryWorkers c
+              withStore' c $ \db -> do
+                when primary $ setSndQueuePrimary db connId sq
+                deletePendingMsgs db connId sq'
+                deleteConnSndQueue db connId sq'
+              let sqs'' = sq'' :| sqs'
+                  conn' = DuplexConnection cData' rqs sqs''
+              cStats <- connectionStats c conn'
+              notify $ SWITCH QDSnd SPCompleted cStats       -- DEADLOCK
+            _ -> internalErr msgId "sent QTEST: ..."         -- DEADLOCK (via notifyDel → notify)
+        _ -> internalErr msgId "sent QTEST: ..."             -- DEADLOCK
+    _ -> internalErr msgId "QTEST sent not in duplex ..."    -- DEADLOCK
+```
+
+**New code:**
+```haskell
+AM_QTEST_ -> do
+  evt_ <- withConnLock c connId "runSmpQueueMsgDelivery AM_QTEST_" $ do
+    withStore' c $ \db -> setSndQueueStatus db sq Active
+    SomeConn _ conn <- withStore c (`getConn` connId)
+    case conn of
+      DuplexConnection cData' rqs sqs -> do
+        let addr = qAddress sq
+        case findQ addr sqs of
+          Just SndQueue {dbReplaceQueueId = Just replacedId, primary} ->
+            case removeQP (\sq' -> dbQId sq' == replacedId && not (sameQueue addr sq')) sqs of
+              Nothing -> pure $ Left "sent QTEST: queue not found in connection"
+              Just (sq', sq'' : sqs') -> do
+                checkSQSwchStatus sq' SSSendingQTEST
+                atomically $ TM.delete (qAddress sq') $ smpDeliveryWorkers c
+                withStore' c $ \db -> do
+                  when primary $ setSndQueuePrimary db connId sq
+                  deletePendingMsgs db connId sq'
+                  deleteConnSndQueue db connId sq'
+                let sqs'' = sq'' :| sqs'
+                    conn' = DuplexConnection cData' rqs sqs''
+                cStats <- connectionStats c conn'
+                pure $ Right $ SWITCH QDSnd SPCompleted cStats
+              _ -> pure $ Left "sent QTEST: there is only one queue in connection"
+          _ -> pure $ Left "sent QTEST: queue not in connection or not replacing another queue"
+      _ -> pure $ Left "QTEST sent not in duplex connection"
+  -- subQ write is now OUTSIDE connLock — blocking writeTBQueue is safe
+  case evt_ of
+    Right evt -> notify evt
+    Left err -> internalErr msgId err
+```
+
+All DB operations remain inside the lock. Only `notify`/`internalErr` (which write to subQ) move outside. `internalErr` calls `notifyDel` = `notify >> delMsg` — both `notify` (subQ write) and `delMsg` (`deleteSndMsgDelivery`, keyed on unique msgId) are safe outside the lock. The existing double-delete pattern (`delMsg` inside `internalErr` + `delMsgKeep` at line 2216) is preserved.
+
+### Fix: Sites 2 & 3 — `ackQueueMessage::sendMsgNtf` (line 2386)
+
+Change `ackQueueMessage` to return the MSGNTF event instead of writing it to subQ. Callers write to subQ after releasing connLock.
+
+**Current code** (Agent.hs:2371-2386):
+```haskell
+ackQueueMessage :: AgentClient -> RcvQueue -> SMP.MsgId -> AM ()
+ackQueueMessage c rq@RcvQueue {userId, connId, server} srvMsgId = do
+  atomically $ incSMPServerStat c userId server ackAttempts
+  tryAllErrors (sendAck c rq srvMsgId) >>= \case
+    Right _ -> sendMsgNtf ackMsgs
+    Left (SMP _ SMP.NO_MSG) -> sendMsgNtf ackNoMsgErrs
+    Left e -> ...
+  where
+    sendMsgNtf stat = do
+      atomically $ incSMPServerStat c userId server stat
+      whenM (liftIO $ hasGetLock c rq) $ do
+        atomically $ releaseGetLock c rq
+        brokerTs_ <- eitherToMaybe <$> tryAllErrors (withStore c $ \db -> getRcvMsgBrokerTs db connId srvMsgId)
+        atomically $ writeTBQueue (subQ c) ("", connId, AEvt SAEConn $ MSGNTF srvMsgId brokerTs_)
+```
+
+**New code** — return `Maybe ATransmission` instead of writing:
+```haskell
+ackQueueMessage :: AgentClient -> RcvQueue -> SMP.MsgId -> AM (Maybe ATransmission)
+ackQueueMessage c rq@RcvQueue {userId, connId, server} srvMsgId = do
+  atomically $ incSMPServerStat c userId server ackAttempts
+  tryAllErrors (sendAck c rq srvMsgId) >>= \case
+    Right _ -> sendMsgNtf ackMsgs
+    Left (SMP _ SMP.NO_MSG) -> sendMsgNtf ackNoMsgErrs
+    Left e -> ... >> pure Nothing
+  where
+    sendMsgNtf stat = do
+      atomically $ incSMPServerStat c userId server stat
+      ifM (liftIO $ hasGetLock c rq)
+        (do atomically $ releaseGetLock c rq
+            brokerTs_ <- eitherToMaybe <$> tryAllErrors (withStore c $ \db -> getRcvMsgBrokerTs db connId srvMsgId)
+            pure $ Just ("", connId, AEvt SAEConn $ MSGNTF srvMsgId brokerTs_))
+        (pure Nothing)
+```
+
+**Caller 1: `ackMessage'`** (Agent.hs:2253-2267) — return event from `withConnLock`, write after:
+```haskell
+ackMessage' c connId msgId rcptInfo_ = do
+  t_ <- withConnLock c connId "ackMessage" $ do
+    SomeConn _ conn <- withStore c (`getConn` connId)
+    case conn of
+      DuplexConnection {} -> do
+        t_ <- ack
+        sendRcpt conn
+        del
+        pure t_
+      RcvConnection {} -> do
+        t_ <- ack
+        del
+        pure t_
+      SndConnection {} -> throwE $ CONN SIMPLEX "ackMessage"
+      ContactConnection {} -> throwE $ CMD PROHIBITED "ackMessage: ContactConnection"
+      NewConnection _ -> throwE $ CMD PROHIBITED "ackMessage: NewConnection"
+  -- subQ write is OUTSIDE connLock
+  case t_ of
+    Just t -> atomically $ writeTBQueue (subQ c) t
+    Nothing -> pure ()
+```
+
+**Caller 2: `ICAck` / `ICAckDel`** (Agent.hs:1823-1824) — inline `tryWithLock` as `tryCommand` + `withConnLock`, write subQ between the two scopes:
+
+`tryWithLock name = tryCommand . withConnLock c connId name` — by inlining, the subQ write can be placed outside `withConnLock` but inside `tryCommand` (retaining retry/error handling).
+
+```haskell
+ICAck rId srvMsgId -> withServer $ \srv ->
+  tryCommand $ do
+    t_ <- withConnLock c connId "ICAck" $ ack srv rId srvMsgId
+    -- subQ write is OUTSIDE connLock — cannot deadlock with agentSubscriber
+    forM_ t_ $ atomically . writeTBQueue subQ
+
+ICAckDel rId srvMsgId msgId -> withServer $ \srv ->
+  tryCommand $ do
+    t_ <- withConnLock c connId "ICAckDel" $ do
+      t_ <- ack srv rId srvMsgId
+      withStore' c (\db -> deleteMsg db connId msgId)
+      pure t_
+    -- subQ write is OUTSIDE connLock — cannot deadlock with agentSubscriber
+    forM_ t_ $ atomically . writeTBQueue subQ
+```
+
+Where `ack` now returns `AM (Maybe ATransmission)`:
+```haskell
+ack srv rId srvMsgId = do
+  rq <- withStore c $ \db -> getRcvQueue db connId srv rId
+  ackQueueMessage c rq srvMsgId
+```
+
+All subQ writes for MSGNTF are now outside connLock. FIFO ordering is preserved — no `nonBlockingWriteTBQueue`, no forked threads. The same thread that held the lock writes to subQ sequentially after releasing it.
+
+### Race analysis
+
+Window between connLock release and subQ write at Site 1:
+
+| Thread | Can acquire connLock(X)? | Writes subQ? | Consequence |
+|--------|-------------------------|-------------|-------------|
+| agentSubscriber via sendMessagesB_ | Yes | **No** (encrypts only) | No race |
+| processSMP for connId X | Yes | Yes (pending flush) | MSG before SWITCH — cosmetic |
+| runCommandProcessing for connId X | Yes | Yes (pending flush) | Command response before SWITCH — cosmetic |
+| New queue delivery worker | No (SENT outside lock) | Yes | SENT before SWITCH — cosmetic, **already exists in current code** |
+
+All races are cosmetic UI ordering. None affect ratchet state, protocol correctness, or message delivery.
+
+### Summary of changes
+
+| File | Change | Lines affected |
+|------|--------|---------------|
+| Agent.hs | Restructure AM_QTEST_ to return event from `withConnLock`, write outside | ~2187-2214 |
+| Agent.hs | Change `ackQueueMessage` return type to `AM (Maybe ATransmission)`, return event instead of writing | ~2371-2386 |
+| Agent.hs | `ackMessage'`: return event from `withConnLock`, write outside | ~2253-2267 |
+| Agent.hs | `ICAck`/`ICAckDel`: inline `tryCommand` + `withConnLock`, write subQ between scopes | ~1823-1824 |
+| Agent.hs | `ack` helper: propagate new return type | ~1899-1901 |
+
+No new data structures. No new modules. No changes to other write sites (1937, 3216 — already safe). ~25 lines changed total.

protocol/agent-protocol.md

@@ -1,4 +1,4 @@
-Version 5, 2024-06-22
+Version 7, 2025-01-24
 
 # SMP agent protocol - duplex communication over SMP protocol
 
@@ -6,9 +6,10 @@ Version 5, 2024-06-22
 
 - [Abstract](#abstract)
 - [SMP agent](#smp-agent)
-- [SMP servers management](#smp-servers-management)
+- [SMP routers management](#smp-routers-management)
 - [SMP agent protocol scope](#smp-agent-protocol-scope)
 - [Duplex connection procedure](#duplex-connection-procedure)
+- [Fast duplex connection procedure](#fast-duplex-connection-procedure)
 - [Contact addresses](#contact-addresses)
 - [Communication between SMP agents](#communication-between-smp-agents)
   - [Message syntax](#messages-between-smp-agents)
@@ -20,41 +21,58 @@ Version 5, 2024-06-22
     - [Rotating messaging queue](#rotating-messaging-queue)
 - [End-to-end encryption](#end-to-end-encryption)
 - [Connection link: 1-time invitation and contact address](#connection-link-1-time-invitation-and-contact-address)
-- [Appendix A: SMP agent API](#smp-agent-api)
+  - [Full connection link syntax](#full-connection-link-syntax)
+  - [Short connection link syntax](#short-connection-link-syntax)
+- [Short links](#short-links)
+  - [Link key derivation](#link-key-derivation)
+  - [Link data encryption](#link-data-encryption)
+  - [Short link resolution](#short-link-resolution)
+  - [Link data management](#link-data-management)
+- [Appendix A: SMP agent API](#appendix-a-smp-agent-api)
   - [API functions](#api-functions)
   - [API events](#api-events)
 
 ## Abstract
 
-The purpose of SMP agent protocol is to define the syntax and the semantics of communications between the client and the agent that connects to [SMP](./simplex-messaging.md) servers.
+The purpose of SMP agent protocol is to define the syntax and the semantics of communications between the client and the agent that connects to [SMP](./simplex-messaging.md) routers.
 
 It provides:
-- API to create and manage bi-directional (duplex) connections between the users of SMP agents consisting of two (or more) separate unidirectional (simplex) SMP queues, abstracting away multiple steps required to establish bi-directional connections and any information about the servers location from the users of the agent protocol.
+- API to create and manage bi-directional (duplex) connections between the users of SMP agents consisting of two (or more) separate unidirectional (simplex) SMP queues, abstracting away multiple steps required to establish bi-directional connections and any information about the routers location from the users of the agent protocol.
 - management of E2E encryption between SMP agents, generating ephemeral asymmetric keys for each connection.
-- SMP command authentication on SMP servers, generating ephemeral keys for each SMP queue.
-- TCP/TLS transport handshake with SMP servers.
+- SMP command authentication on SMP routers, generating ephemeral keys for each SMP queue.
+- TCP/TLS transport handshake with SMP routers.
 - validation of message integrity.
 
 SMP agent API provides no security between the agent and the client - it is assumed that the agent is executed in the trusted and secure environment, via the agent library, when the agent logic is included directly into the client application - [SimpleX Chat for terminal](https://github.com/simplex-chat/simplex-chat) uses this approach.
 
+This document describes SMP agent protocol version 7. The version history:
+
+- v1: initial version
+- v2: duplex handshake - allows including reply queue(s) in the initial confirmation
+- v3: ratchet sync - supports re-negotiating double ratchet encryption
+- v4: delivery receipts - supports acknowledging message delivery to the sender
+- v5: post-quantum - supports post-quantum key exchange in double ratchet (PQDR)
+- v6: sender auth key - supports sender authentication key in confirmations
+- v7: ratchet on confirmation - initializes double ratchet during confirmation
+
 ## SMP agent
 
-SMP agents communicate with each other via SMP servers using [simplex messaging protocol (SMP)](./simplex-messaging.md) according to the API calls used by the client applications. This protocol is a middle layer in SimpleX protocols (above SMP protocol but below any application level protocol) - it is intended to be used by client-side applications that need secure asynchronous bi-directional communication channels ("connections").
+SMP agents communicate with each other via SMP routers using [simplex messaging protocol (SMP)](./simplex-messaging.md) according to the API calls used by the client applications. This protocol is a middle layer in SimpleX protocols (above SMP protocol but below any application level protocol) - it is intended to be used by client-side applications that need secure asynchronous bi-directional communication channels ("connections").
 
 The agent must have a persistent storage to manage the states of known connections and of the client-side information of SMP queues that each connection consists of, and also the buffer of the most recent sent and received messages. The number of the messages that should be stored is implementation specific, depending on the error management approach that the agent implements; at the very least the agent must store the hashes and IDs of the last received and sent messages.
 
-## SMP servers management
+## SMP routers management
 
-SMP agent API does not use the addresses of the SMP servers that the agent will use to create and use the connections (excluding the server address in queue URIs used in JOIN command). The list of the servers is a part of the agent configuration and can be dynamically changed by the agent implementation:
+SMP agent API does not use the addresses of the SMP routers that the agent will use to create and use the connections (excluding the router address in queue URIs used in JOIN command). The list of the routers is a part of the agent configuration and can be dynamically changed by the agent implementation:
 - by the client applications via any API that is outside of scope of this protocol.
-- by the agents themselves based on availability and latency of the configured servers.
+- by the agents themselves based on availability and latency of the configured routers.
 
 ## SMP agent protocol scope
 
 SMP agent protocol has 2 main parts:
 
 - the messages that SMP agents exchange with each other in order to:
-  - negotiate establishing unidirectional (simplex) encrypted queues on SMP servers.
+  - negotiate establishing unidirectional (simplex) encrypted queues on SMP routers.
   - exchange client messages and delivery notifications, providing sequential message IDs and message integrity (by including the hash of the previous message).
   - re-negotiate messaging queues to use and connection e2e encryption.
 - the messages that the clients of SMP agents should send out-of-band (as pre-shared "invitation" including queue URIs) to protect [E2E encryption][1] from active attacks ([MITM attacks][2]).
@@ -67,40 +85,40 @@ SMP agent protocol has 2 main parts:
 
 ![Duplex connection procedure](./diagrams/duplex-messaging/duplex-creating.svg)
 
-The procedure of establishing a duplex connection is explained on the example of Alice and Bob creating a bi-directional connection consisting of two unidirectional (simplex) queues, using SMP agents (A and B) to facilitate it, and two different SMP servers (which could be the same server). It is shown on the diagram above and has these steps:
+The procedure of establishing a duplex connection is explained on the example of Alice and Bob creating a bi-directional connection consisting of two unidirectional (simplex) queues, using SMP agents (A and B) to facilitate it, and two different SMP routers (which could be the same router). It is shown on the diagram above and has these steps:
 
 1. Alice requests the new connection from the SMP agent A using agent `createConnection` api function.
-2. Agent A creates an SMP queue on the server (using [SMP protocol](./simplex-messaging.md) `NEW` command) and responds to Alice with the invitation that contains queue information and the encryption keys Bob's agent B should use. The invitation format is described in [Connection link](connection-link-1-time-invitation-and-contact-address).
+2. Agent A creates an SMP queue on the router (using [SMP protocol](./simplex-messaging.md) `NEW` command) and responds to Alice with the invitation that contains queue information and the encryption keys Bob's agent B should use. The invitation format is described in [Connection link](connection-link-1-time-invitation-and-contact-address).
 3. Alice sends the [connection link](#connection-link-1-time-invitation-and-contact-address) to Bob via any secure channel (out-of-band message) - as a link or as a QR code.
 4. Bob uses agent `joinConnection` api function with the connection link as a parameter to agent B to accept the connection.
-5. Agent B creates Bob's SMP reply queue with SMP server `NEW` command.
-6. Agent B confirms the connection: sends an "SMP confirmation" with SMP server `SEND` command to the SMP queue specified in the connection link - SMP confirmation is an unauthenticated message with an ephemeral key that will be used to authenticate Bob's commands to the queue, as described in SMP protocol, and Bob's info (profile, public key for E2E encryption, and the connection link to this 2nd queue to Agent A - this connection link SHOULD use "simplex" URI scheme). This message is encrypted using key passed in the connection link (or with the derived shared secret, in which case public key for key derivation should be sent in clear text).
-6. Alice confirms and continues the connection:
-  - Agent A receives the SMP confirmation containing Bob's key, reply queue and info as SMP server `MSG`.
+5. Agent B creates Bob's SMP reply queue with SMP router `NEW` command.
+6. Agent B confirms the connection: sends an "SMP confirmation" with SMP router `SEND` command to the SMP queue specified in the connection link - SMP confirmation is an unauthenticated message with an ephemeral key that will be used to authenticate Bob's commands to the queue, as described in SMP protocol, and Bob's info (profile, public key for E2E encryption, and the connection link to this 2nd queue to Agent A - this connection link SHOULD use "simplex" URI scheme). This message is encrypted using key passed in the connection link (or with the derived shared secret, in which case public key for key derivation should be sent in clear text).
+7. Alice confirms and continues the connection:
+  - Agent A receives the SMP confirmation containing Bob's key, reply queue and info as SMP router `MSG`.
   - Agent A notifies Alice sending `CONF` notification with Bob's info.
   - Alice allows connection to continue with agent `allowConnection` api function.
-  - Agent A secures the queue with SMP server `KEY` command.
+  - Agent A secures the queue with SMP router `KEY` command.
   - Agent A sends SMP confirmation with ephemeral sender key, ephemeral public encryption key and profile (but without reply queue).
-7. Agent B confirms the connection:
+8. Agent B confirms the connection:
   - receives the confirmation.
   - sends the notification `INFO` with Alice's information to Bob.
   - secures SMP queue that it sent to Alice in the first confirmation with SMP `KEY` command .
   - sends `HELLO` message via SMP `SEND` command. This confirms that the reply queue is secured and also validates that Agent A secured the first SMP queue
-8. Agent A notifies Alice.
+9. Agent A notifies Alice.
   - receives `HELLO` message from Agent B.
   - sends `HELLO` message to Agent B via SMP `SEND` command.
   - sends `CON` notification to Alice, confirming that the connection is established.
-9. Agent B notifies Bob.
+10. Agent B notifies Bob.
   - Once Agent B receives `HELLO` from Agent A, it sends to Bob `CON` notification as well.
 
 At this point the duplex connection between Alice and Bob is established, they can use `SEND` command to send messages. The diagram also shows how the connection status changes for both parties, where the first part is the status of the SMP queue to receive messages, and the second part - the status of the queue to send messages.
 
-The most communication happens between the agents and servers, from the point of view of Alice and Bob there are 4 steps (not including notifications):
+The most communication happens between the agents and routers, from the point of view of Alice and Bob there are 4 steps (not including notifications):
 
 1. Alice requests a new connection with `createConnection` agent API function and receives the connection link.
 2. Alice passes connection link out-of-band to Bob.
 3. Bob accepts the connection with `joinConnection` agent API function with the connection link to his agent.
-4. Alice accepts the connection with `ACPT` agent API function.
+4. Alice accepts the connection with `allowConnection` agent API function.
 5. Both parties receive `CON` notification once duplex connection is established.
 
 Clients SHOULD support establishing duplex connection asynchronously (when parties are intermittently offline) by persisting intermediate states and resuming SMP queue subscriptions.
@@ -118,14 +136,14 @@ Faster duplex connection process is possible with the `SKEY` command added in v9
 ![Fast duplex connection procedure](./diagrams/duplex-messaging/duplex-creating-fast.svg)
 
 1. Alice requests the new connection from the SMP agent A using agent `createConnection` api function
-2. Agent A creates an SMP queue on the server (using [SMP protocol](./simplex-messaging.md) `NEW` command with the flag allowing the sender to secure the queue) and responds to Alice with the invitation that contains queue information and the encryption keys Bob's agent B should use. The invitation format is described in [Connection link](connection-link-1-time-invitation-and-contact-address).
+2. Agent A creates an SMP queue on the router (using [SMP protocol](./simplex-messaging.md) `NEW` command with the flag allowing the sender to secure the queue) and responds to Alice with the invitation that contains queue information and the encryption keys Bob's agent B should use. The invitation format is described in [Connection link](connection-link-1-time-invitation-and-contact-address).
 3. Alice sends the [connection link](connection-link-1-time-invitation-and-contact-address) to Bob via any secure channel (out-of-band message) - as a link or as a QR code. This link contains the flag that the queue can be secured by the sender.
 4. Bob uses agent `joinConnection` api function with the connection link as a parameter to agent B to accept the connection.
 5. Agent B secures Alice's queue with SMP command `SKEY` - this command can be proxied.
-6. Agent B creates Bob's SMP reply queue with SMP server `NEW` command (with the flag allowing the sender to secure the queue).
-7. Agent B confirms the connection: sends an "SMP confirmation" with SMP server `SEND` command to the SMP queue specified in the connection link - SMP confirmation is an unauthenticated message with an ephemeral key that will be used to authenticate Bob's commands to the queue, as described in SMP protocol, and Bob's info (profile, public key for E2E encryption, and the connection link to this 2nd queue to Agent A - this connection link SHOULD use "simplex" URI scheme). This message is encrypted using key passed in the connection link (or with the derived shared secret, in which case public key for key derivation should be sent in clear text).
+6. Agent B creates Bob's SMP reply queue with SMP router `NEW` command (with the flag allowing the sender to secure the queue).
+7. Agent B confirms the connection: sends an "SMP confirmation" with SMP router `SEND` command to the SMP queue specified in the connection link - SMP confirmation is an unauthenticated message with an ephemeral key that will be used to authenticate Bob's commands to the queue, as described in SMP protocol, and Bob's info (profile, public key for E2E encryption, and the connection link to this 2nd queue to Agent A - this connection link SHOULD use "simplex" URI scheme). This message is encrypted using key passed in the connection link (or with the derived shared secret, in which case public key for key derivation should be sent in clear text).
 8. Alice confirms the connection:
-  - Agent A receives the SMP confirmation containing Bob's key, reply queue and info as SMP server `MSG`.
+  - Agent A receives the SMP confirmation containing Bob's key, reply queue and info as SMP router `MSG`.
   - Agent A notifies Alice sending `CONF` notification with Bob's info (that indicates that Agent B already secured the queue).
   - Alice allows connection to continue with agent `allowConnection` api function.
   - Agent A secures Bob's queue with SMP command `SKEY`.
@@ -140,11 +158,11 @@ Faster duplex connection process is possible with the `SKEY` command added in v9
 
 SMP agents support creating a special type of connection - a contact address - that allows to connect to multiple network users who can send connection requests by sending 1-time connection links to the message queue. 
 
-This connection address uses a messaging queue on SMP server to receive invitations to connect - see `agentInvitation` message below. Once connection request is accepted, a new connection is created and the address itself is no longer used to send the messages - deleting this address does not disrupt the connections that were created via it.
+This connection address uses a messaging queue on SMP router to receive invitations to connect - see `agentInvitation` message below. Once connection request is accepted, a new connection is created and the address itself is no longer used to send the messages - deleting this address does not disrupt the connections that were created via it.
 
 ## Communication between SMP agents
 
-To establish duplex connections and to send messages on behalf of their clients, SMP agents communicate via SMP servers.
+To establish duplex connections and to send messages on behalf of their clients, SMP agents communicate via SMP routers.
 
 Agents use SMP message client body (the part of the SMP message after header - see [SMP protocol](./simplex-messaging.md)) to transmit agent client messages and exchange messages between each other.
 
@@ -152,13 +170,13 @@ These messages are encrypted with per-queue shared secret using NaCL crypto_box
 - `agentConfirmation` - used when confirming SMP queues, contains connection information encrypted with double ratchet. This envelope can only contain `agentConnInfo` or `agentConnInfoReply` encrypted with double ratchet.
 - `agentMsgEnvelope` - contains different agent messages encrypted with double ratchet, as defined in `agentMessage`.
 - `agentInvitation` - sent to SMP queue that is used as contact address, does not use double ratchet.
-- `agentRatchetKey` - used to re-negotiate double ratchet encryption - can contain additional information in `agentRatchetKey`.
+- `agentRatchetKey` - used to re-negotiate double ratchet encryption - can contain additional information in `agentRatchetInfo`.
 
 ```abnf
 decryptedSMPClientMessage = agentConfirmation / agentMsgEnvelope / agentInvitation / agentRatchetKey
 agentConfirmation = agentVersion %s"C" ("0" / "1" sndE2EEncryptionParams) encConnInfo
 agentVersion = 2*2 OCTET
-sndE2EEncryptionParams = TODO
+sndE2EEncryptionParams = <sender E2E ratchet parameters, see pqdr.md>
 encConnInfo = doubleRatchetEncryptedMessage
 
 agentMsgEnvelope = agentVersion %s"M" encAgentMessage
@@ -166,13 +184,25 @@ encAgentMessage = doubleRatchetEncryptedMessage
 
 agentInvitation = agentVersion %s"I" connReqLength connReq connInfo
 connReqLength = 2*2 OCTET ; Word16
+connReq = *OCTET ; URI text encoding of connection link, length given by connReqLength
+connInfo = *OCTET ; opaque connection information (remaining bytes)
 
-agentRatchetKey = agentVersion %s"R" rcvE2EEncryptionParams agentRatchetInfo
-rcvE2EEncryptionParams = TODO
+agentRatchetKey = agentVersion %s"R" rcvE2EEncryptionParams ratchetKeyInfo
+rcvE2EEncryptionParams = <receiver E2E ratchet parameters, see pqdr.md>
+ratchetKeyInfo = *OCTET ; additional ratchet renegotiation info (remaining bytes)
 
-doubleRatchetEncryptedMessage = TODO
+doubleRatchetEncryptedMessage = <double ratchet encrypted message, see pqdr.md>
 ```
 
+The maximum size of the encrypted connection info and agent message depend on whether post-quantum key exchange is used:
+
+| Constant | PQ on | PQ off |
+|----------|-------|--------|
+| `e2eEncConnInfoLength` | 11106 | 14832 |
+| `e2eEncAgentMsgLength` | 13618 | 15840 |
+
+The PQ-on sizes are smaller because the ratchet header and reply link include larger PQ keys (SNTRUP761).
+
 This syntax of decrypted SMP client message body is defined by `decryptedAgentMessage` below.
 
 Decrypted SMP message client body can be one of 4 types:
@@ -182,14 +212,15 @@ Decrypted SMP message client body can be one of 4 types:
 - `agentMessage` - all other agent messages.
 
 `agentMessage` contains these parts:
-- `agentMsgHeader` - agent message header that contains sequential agent message ID for a particular SMP queue, agent timestamp (ISO8601) and the hash of the previous message.
+- `agentMsgHeader` - agent message header that contains sequential agent message ID for a particular SMP queue and the hash of the previous message.
 - `aMessage` - a command/message to the other SMP agent:
   - to confirm the connection (`HELLO`).
   - to send and to confirm reception of user messages (`A_MSG`, `A_RCVD`).
   - to confirm that the new double ratchet encryption is agreed (`EREADY`).
   - to notify another party that it can continue sending messages after queue capacity was exceeded (`A_QCONT`).
   - to manage SMP queue rotation (`QADD`, `QKEY`, `QUSE`, `QTEST`).
-- `msgPadding` - an optional message padding to make all SMP messages have constant size, to prevent servers from observing the actual message size. The only case the message padding can be absent is when the message has exactly the maximum size, in all other cases the message MUST be padded to a fixed size.
+
+The encoded `agentMessage` is padded to a fixed size by the double ratchet encryption layer (see [ratchet message wire format](./pqdr.md#ratchet-message-wire-format)) to make all SMP messages have constant size, preventing routers from observing the actual message size.
 
 ### Messages between SMP agents
 
@@ -200,9 +231,11 @@ decryptedAgentMessage = agentConnInfo / agentConnInfoReply / agentRatchetInfo /
 agentConnInfo = %s"I" connInfo
 connInfo = *OCTET
 agentConnInfoReply = %s"D" smpQueues connInfo
+smpQueues = length 1*newQueueInfo ; NonEmpty list of reply queues
 agentRatchetInfo = %s"R" ratchetInfo
+ratchetInfo = *OCTET
 
-agentMessage = %s"M" agentMsgHeader aMessage msgPadding
+agentMessage = %s"M" agentMsgHeader aMessage
 agentMsgHeader = agentMsgId prevMsgHash
 agentMsgId = 8*8 OCTET ; Int64
 prevMsgHash = shortString
@@ -213,10 +246,13 @@ aMessage = HELLO / A_MSG / A_RCVD / EREADY / A_QCONT /
 HELLO = %s"H"
 
 A_MSG = %s"M" userMsgBody
-userMsgBody = *OCTET
+userMsgBody = *OCTET ; remaining bytes
 
-A_RCVD = %s"V" msgReceipt
+A_RCVD = %s"V" msgReceipts
+msgReceipts = length 1*msgReceipt ; NonEmpty list
 msgReceipt = agentMsgId msgHash rcptLength rcptInfo
+msgHash = shortString
+rcptInfo = *OCTET ; opaque receipt info, length given by rcptLength (Word16)
 
 EREADY = %s"E" agentMsgId
 
@@ -224,14 +260,14 @@ A_QCONT = %s"QC" sndQueueAddr
 
 QADD = %s"QA" sndQueues
 sndQueues = length 1*(newQueueUri replacedSndQueue)
-newQueueUri = clientVRange smpServer senderId dhPublicKey [sndSecure]
+newQueueUri = clientVRange smpRouter senderId dhPublicKey [queueMode]
 dhPublicKey = length x509encoded
-sndSecure = "T"
+queueMode = %s"M" / %s"C" ; M - messaging (sender can secure), C - contact
 replacedSndQueue = "0" / "1" sndQueueAddr
 
 QKEY = %s"QK" sndQueueKeys
 sndQueueKeys = length 1*(newQueueInfo senderKey)
-newQueueInfo = version smpServer senderId dhPublicKey [sndSecure]
+newQueueInfo = version smpRouter senderId dhPublicKey [queueMode]
 senderKey = length x509encoded
 
 QUSE = %s"QU" sndQueuesReady
@@ -241,8 +277,8 @@ primary = %s"T" / %s"F"
 QTEST = %s"QT" sndQueueAddrs
 sndQueueAddrs = length 1*sndQueueAddr
 
-sndQueueAddr = smpServer senderId
-smpServer = hosts port keyHash
+sndQueueAddr = smpRouter senderId
+smpRouter = hosts port keyHash
 hosts = length 1*host
 host = shortString
 port = shortString
@@ -252,7 +288,6 @@ senderId = shortString
 clientVRange = version version
 version = 2*2 OCTET
 
-msgPadding = *OCTET
 rcptLength = 2*2 OCTET
 shortString = length *OCTET
 length = 1*1 OCTET
@@ -266,11 +301,11 @@ This message is not used with [fast duplex connection](#fast-duplex-connection-p
 
 #### A_MSG message
 
-This is the agent envelope used to send client messages once the connection is established. This is different from the MSG sent by SMP server to the agent and MSG event from SMP agent to the client that are sent in different contexts.
+This is the agent envelope used to send client messages once the connection is established. This is different from the MSG sent by SMP router to the agent and MSG event from SMP agent to the client that are sent in different contexts.
 
 #### A_RCVD message
 
-This message is sent to confirm the client message reception. It includes received message number and message hash.
+This message is sent to confirm the client message reception. It includes a list of message receipts, each containing the received message number, message hash and receipt info.
 
 #### EREADY message
 
@@ -282,7 +317,7 @@ This message is sent to notify the sender client that it can continue sending th
 
 ### Rotating messaging queue
 
-SMP agents SHOULD support 4 messages to rotate message reception to another messaging server:
+SMP agents SHOULD support 4 messages to rotate message reception to another messaging router:
 `QADD`: add the new queue address(es) to the connection - sent by the client that initiates rotation.
 `QKEY`: pass sender's key via existing connection (SMP confirmation message will not be used, to avoid the same "race" of the initial key exchange that would create the risk of intercepting the queue for the attacker) - sent by the client accepting the rotation
 `QUSE`: instruct the sender to use the new queue with sender's queue ID as parameter. From this point some messages can be sent to both the new queue and the old queue.
@@ -345,31 +380,191 @@ To summarize, the upgrade to DH+KEM secret happens in a sent message that has PQ
 
 Connection links are generated by SMP agent in response to `createConnection` api call, used by another party user with `joinConnection` api, and then another connection link is sent by the agent in `agentConnInfoReply` and used by the first party agent to connect to the reply queue (the second part of the process is invisible to the users).
 
-Connection link syntax:
+### Full connection link syntax
 
 ```
-connectionLink = connectionScheme "/" connLinkType "#/?smp=" smpQueues "&e2e=" e2eEncryption
+connectionLink = connectionScheme "/" connLinkType "#/?v=" versionRange "&smp=" smpQueues ["&e2e=" e2eEncryption] ["&data=" clientData]
 connLinkType = %s"invitation" / %s"contact"
-connectionScheme = (%s"https://" clientAppServer) | %s"simplex:"
+connectionScheme = (%s"https://" clientAppServer) / %s"simplex:"
 clientAppServer = hostname [ ":" port ]
 ; client app server, e.g. simplex.chat
-e2eEncryption = encryptionScheme ":" publicKey
-encryptionScheme = %s"rsa" ; end-to-end encryption and key exchange protocols,
-                           ; the current hybrid encryption scheme (RSA-OAEP/AES-256-GCM-SHA256)
-                           ; will be replaced with double ratchet protocol and DH key exchange.
-publicKey = <base64url X509 SPKI key encoding>
-smpQueues = smpQueue [ "," 1*smpQueue ] ; SMP queues for the connection
+versionRange = 1*DIGIT / 1*DIGIT "-" 1*DIGIT ; agent version range
+e2eEncryption = <e2e encryption parameters for double ratchet>
+smpQueues = smpQueue *(";" smpQueue) ; SMP queues for the connection (semicolon-separated)
 smpQueue = <URL-encoded queueURI defined in SMP protocol>
+clientData = <URL-encoded application-specific data>
 ```
 
-All parameters are passed via URI hash to avoid sending them to the server (in case "https" scheme is used) - they can be used by the client-side code and processed by the client application. Parameters `smp` and `e2e` can be present in any order, any unknown additional parameters SHOULD be ignored.
+All parameters are passed via URI hash to avoid sending them to the router (in case "https" scheme is used) - they can be used by the client-side code and processed by the client application. Parameters can be present in any order, any unknown additional parameters SHOULD be ignored.
 
-`clientAppServer` is not an SMP server - it is a server that shows the instruction on how to download the client app that will connect using this connection link. This server can also host a mobile or desktop app manifest so that this link is opened directly in the app if it is installed on the device.
+`clientAppServer` is not an SMP router - it is a server that shows the instruction on how to download the client app that will connect using this connection link. This server can also host a mobile or desktop app manifest so that this link is opened directly in the app if it is installed on the device.
 
-"simplex" URI scheme in `connectionProtocol` can be used instead of client app server, to connect without creating any web traffic. Client apps MUST support this URI scheme.
+"simplex" URI scheme in `connectionProtocol` can be used instead of client app router, to connect without creating any web traffic. Client apps MUST support this URI scheme.
 
 See SMP protocol [out-of-band messages](./simplex-messaging.md#out-of-band-messages) for syntax of `queueURI`.
 
+### Short connection link syntax
+
+Short links provide a more compact representation by storing connection data on the router:
+
+```
+shortLink = shortLinkScheme "/" linkType "#" [linkId "/"] linkKey ["?" shortLinkParams]
+shortLinkScheme = %s"simplex:" / (%s"https://" serverHost)
+linkType = %s"i" / contactType ; i - invitation, or contact type
+contactType = %s"a" / %s"c" / %s"g" / %s"r" ; a - contact, c - channel, g - group, r - relay
+linkId = base64url ; only for invitation links
+linkKey = base64url ; SHA3-256 hash of fixed data, used to decrypt link data
+shortLinkParams = hostParam ["&" portParam] ["&" keyHashParam]
+hostParam = %s"h=" hostList
+hostList = host *("," host)
+portParam = %s"p=" port
+keyHashParam = %s"c=" base64url ; router certificate fingerprint
+```
+
+Contact types:
+- `a` (CCTContact) - direct contact connection
+- `c` (CCTChannel) - channel connection
+- `g` (CCTGroup) - group connection
+- `r` (CCTRelay) - relay connection
+
+Short links can use either the `simplex:` scheme or `https://` with a router hostname. When using the simplex scheme, router information is included in query parameters.
+
+## Short links
+
+Short links provide a compact representation of connection links by storing encrypted connection data on the SMP router. The link key in the URI fragment (after `#`) is never sent to the router, ensuring the router cannot decrypt the stored connection data.
+
+### Link key derivation
+
+The link key is derived from the fixed link data using SHA3-256 hash function:
+
+```
+linkKey = SHA3-256(fixedLinkData)
+```
+
+The fixed link data includes:
+- Agent version range
+- Root public key (Ed25519) for signing
+- SMP queue connection request (router, queue IDs, encryption keys)
+- Optional link entity ID
+
+For contact links, the link ID and encryption key are derived from the link key using HKDF:
+
+```
+(linkId, encryptionKey) = HKDF(info="SimpleXContactLink", key=linkKey, outputLen=56)
+; linkId = first 24 bytes, encryptionKey = remaining 32 bytes
+```
+
+For invitation links, the link ID is stored separately (usually included in the URI), and only the encryption key is derived:
+
+```
+encryptionKey = HKDF(info="SimpleXInvLink", key=linkKey, outputLen=32)
+```
+
+### Link data encryption
+
+Link data stored on the router consists of two encrypted parts: fixed data and user data. Both are encrypted using NaCl secret_box (XSalsa20-Poly1305) with the derived encryption key:
+
+```abnf
+queueLinkData = encFixedData encUserData
+encFixedData = largeString ; encrypted padded(signedFixedData, 2008)
+encUserData = largeString ; encrypted padded(signedUserData, 13784)
+
+signedFixedData = signature fixedData
+signedUserData = signature userData
+signature = length 64*64 OCTET ; Ed25519 signature
+
+fixedData = agentVersionRange rootKey linkConnReq [linkEntityId]
+agentVersionRange = version version ; min and max agent protocol version
+version = 2*2 OCTET
+rootKey = length x509encoded ; Ed25519 public key
+linkConnReq = invitationConnReq / contactConnReq ; binary encoding of connection request
+invitationConnReq = %s"I" connReqData e2eRatchetParams
+contactConnReq = %s"C" connReqData
+linkEntityId = shortString
+userData = invitationLinkData / contactLinkData
+invitationLinkData = %s"I" agentVersionRange userLinkData
+contactLinkData = %s"C" agentVersionRange userContactData
+userLinkData = shortString / (%xFF largeString) ; opaque application data (e.g., user profile)
+  ; shortString length byte 0x00-0xFE (max 254 bytes); 0xFF is reserved as largeString sentinel
+userContactData = direct ownersList relaysList userLinkData
+direct = %s"T" / %s"F" ; whether direct connection via connReq is allowed
+ownersList = length *ownerAuth
+ownerAuth = shortString ; length-prefixed encoding of (ownerId ownerKey authOwnerSig)
+ownerId = shortString ; application-specific owner ID (e.g., MemberId)
+ownerKey = length x509encoded ; Ed25519 public key
+authOwnerSig = length 64*64 OCTET ; Ed25519 signature of (ownerId || ownerKey) by previous owner
+relaysList = length *connShortLink ; alternative relay short links
+
+; Binary encoding of connection request (used in linkConnReq)
+connReqData = agentVersionRange smpQueueUris clientData
+smpQueueUris = length 1*smpQueueUri
+clientData = %s"0" / (%s"1" largeString) ; Maybe (Large ByteString)
+smpQueueUri = smpClientVersionRange smpServer senderId smpDhPublicKey [queueMode]
+smpClientVersionRange = version version ; min and max SMP client versions
+smpServer = hosts port serverKeyHash
+hosts = length 1*host
+host = shortString ; text-encoded hostname or IP address
+port = shortString ; text-encoded port number
+serverKeyHash = shortString ; CA certificate fingerprint
+senderId = shortString ; queue sender ID
+smpDhPublicKey = length x509encoded ; X25519 DH public key
+queueMode = %s"M" / %s"C" ; messaging or contact (version-dependent trailing field)
+e2eRatchetParams = e2eVersionRange e2eDhKey e2eDhKey kemParams
+e2eVersionRange = version version ; min and max e2e encryption versions
+e2eDhKey = length x509encoded ; X448 DH public key
+kemParams = %s"0" / (%s"1" ratchetKEMParams)
+ratchetKEMParams = %s"P" kemPublicKey / %s"A" kemCiphertext kemPublicKey
+kemPublicKey = largeString ; sntrup761 public key
+kemCiphertext = largeString ; sntrup761 ciphertext
+
+; Binary encoding of short link (used in relaysList)
+connShortLink = invShortLink / contactShortLink
+invShortLink = %s"I" smpServer linkId linkKey
+contactShortLink = %s"C" contactConnType smpServer linkKey
+contactConnType = %s"A" / %s"C" / %s"G" / %s"R" ; contact / channel / group / relay
+linkId = shortString
+linkKey = shortString
+
+x509encoded = *OCTET ; DER-encoded X.509 SubjectPublicKeyInfo
+largeString = 2*2 OCTET *OCTET ; Word16 length prefix
+length = 1*1 OCTET
+shortString = length *OCTET
+```
+
+The fixed data is signed with the root key and its hash becomes the link key. The user data is signed either with the root key (for invitations) or with an owner key (for contact addresses).
+
+### Short link resolution
+
+When a user receives a short link, the agent resolves it as follows:
+
+1. Extract the link key from the URI fragment
+2. Send `LGET` command to the SMP router with the link ID
+3. Receive encrypted link data from the router
+4. Decrypt the link data using the link key
+5. Extract the full connection information (SMP queue URI, encryption keys, profile)
+6. Proceed with the standard connection procedure using `joinConnection`
+
+For invitation links, the `LKEY` command is used to set the sender key when getting link data. Repeated `LKEY` would require using the same key.
+
+### Link data management
+
+The recipient who created the queue can manage the short link data:
+
+- **LSET** - Set or update the link data associated with a queue. This is used when creating a short link or updating the user data (e.g., profile changes).
+- **LDEL** - Delete the link data from the router. This effectively invalidates the short link.
+
+Short links support different connection modes:
+- **invitation** - One-time invitation links that can only be used once
+- **contact** - Reusable contact address links that can be used multiple times
+
+For contact addresses, the link data includes additional information about the contact type:
+- **contact** - Direct contact connection
+- **channel** - Channel connection
+- **group** - Group connection
+- **relay** - Relay connection
+
+The agent maintains the link data and updates it when connection parameters change, ensuring short links remain valid and reflect current connection information.
+
 ## Appendix A: SMP agent API
 
 The exact specification of agent library API and of the events that the agent sends to the client application is out of scope of the protocol specification.
@@ -380,7 +575,7 @@ The list of some of the API functions and events below is supported by the refer
 
 The list of APIs below is not exhaustive and provided for information only. Please consult the source code for more information.
 
-#### Create conection
+#### Create connection
 
 `createConnection` api is used to create a connection - it returns the connection link that should be sent out-of-band to another protocol user (the joining party). It should be used by the client of the agent that initiates creating a duplex connection (the initiating party).
 
@@ -408,13 +603,13 @@ Client can `acceptContact` and `rejectContact`, with `OK` and `ERR` events in ca
 
 #### Send message
 
-`sendMessage` api is always asynchronous. The api call returns message ID, `SENT` event once the message is sent to the server, `MWARN` event in case of temporary delivery failure that can be resolved by the user (e.g., by connecting via Tor or by upgrading the client) and `MERR` in case of permanent delivery failure.
+`sendMessage` api is always asynchronous. The api call returns message ID, `SENT` event once the message is sent to the router, `MWARN` event in case of temporary delivery failure that can be resolved by the user (e.g., by connecting via Tor or by upgrading the client) and `MERR` in case of permanent delivery failure.
 
 #### Acknowledge received message
 
 Messages are delivered to the client application via `MSG` event.
 
-Client application must always `ackMessage` to receive the next one - failure to call it in reference implementation will prevent the delivery of subsequent messages until the client reconnects to the server.
+Client application must always `ackMessage` to receive the next one - failure to call it in reference implementation will prevent the delivery of subsequent messages until the client reconnects to the router.
 
 This api is also used to acknowledge message delivery to the sending party - that party client application will receive `RCVD` event.
 
@@ -426,9 +621,17 @@ This api is also used to acknowledge message delivery to the sending party - tha
 
 `getNotificationMessage` is used by push notification subsystem of the client application to receive the message from a specific messaging queue mentioned in the notification. The client application would receive `MSG` and any other events from the agent, and then `MSGNTF` event once the message related to this notification is received.
 
-#### Rotate message queue to another server
+#### Set short link data
 
-`switchConnection` api is used to rotate connection queues to another messaging server.
+`setConnectionLink` api (`LSET` command) is used to set or update short link data associated with a contact address queue. Returns `LINK` event with the short link URI.
+
+#### Get short link data
+
+`getConnectionLink` api (`LGET` command) is used to retrieve and decrypt the short link data from the router. Returns `LDATA` event with the decrypted link data.
+
+#### Rotate message queue to another router
+
+`switchConnection` api is used to rotate connection queues to another messaging router.
 
 #### Renegotiate e2e encryption
 
@@ -436,7 +639,7 @@ This api is also used to acknowledge message delivery to the sending party - tha
 
 #### Delete connection
 
-`deleteConnection` api is used to delete connection. In case of asynchronous call, the connection deletion will be confirmed with `DEL_RCVQ` and `DEL_CONN` events.
+`deleteConnection` api is used to delete connection. In case of asynchronous call, the connection deletion will be confirmed with `DEL_RCVQS` and `DEL_CONNS` events.
 
 #### Suspend connection
 
@@ -451,25 +654,80 @@ Agent API uses these events dispatch to notify client application about events r
 - `INFO` - information from the party that initiated the connection with `createConnection` sent to the party accepting the connection with `joinConnection`.
 - `CON` - notification that connection is established sent to both parties of the connection.
 - `END` - notification that connection subscription is terminated when another client subscribed to the same messaging queue.  
-- `DOWN` - notification that connection server is temporarily unavailable.
-- `UP` - notification that the subscriptions made in the current client session are resumed after the server became available.
+- `DOWN` - notification that connection router is temporarily unavailable.
+- `UP` - notification that the subscriptions made in the current client session are resumed after the router became available.
 - `SWITCH` - notification about queue rotation process.
 - `RSYNC` - notification about e2e encryption re-negotiation process.
-- `SENT` - notification to confirm that the message was delivered to at least one of SMP servers. This notification contains the same message ID as returned to `sendMessage` api. `SENT` notification, depending on network availability, can be sent at any time later, potentially in the next client session.
+- `SENT` - notification to confirm that the message was delivered to at least one of SMP routers. This notification contains the same message ID as returned to `sendMessage` api. `SENT` notification, depending on network availability, can be sent at any time later, potentially in the next client session.
 - `MWARN` - temporary delivery failure that can be resolved by the user (e.g., by connecting via Tor or by upgrading the client).
 - `MERR` - notification about permanent message delivery failure.
 - `MERRS` - notification about permanent message delivery failure for multiple messages (e.g., when multiple messages expire).
-- `MSG` - sent when agent receives the message from the SMP server.
+- `MSG` - sent when agent receives the message from the SMP router.
 - `MSGNTF` - sent after agent received and processed the message referenced in the push notification.
 - `RCVD` - notification confirming message receipt by another party.
 - `QCONT` - notification that the agent continued sending messages after queue capacity was exceeded and recipient received all messages.
-- `DEL_RCVQ` - confirmation that message queue was deleted.
-- `DEL_CONN` - confirmation that connection was deleted.
+- `LINK` - short link URI created or updated for a contact address.
+- `LDATA` - decrypted short link data received from the router.
+- `DELD` - notification that the connection was deleted.
+- `JOINED` - notification that a member joined via a contact address.
+- `STAT` - connection statistics event.
+- `DEL_RCVQS` - confirmation that receiver message queues were deleted.
+- `DEL_CONNS` - confirmation that connections were deleted.
 - `OK` - confirmation that asynchronous api call was successful.
 - `ERR` - error of asynchronous api call or some other error event.
 
 This list of events is not exhaustive and provided for information only. Please consult the source code for more information.
 
+## Threat model
+
+This threat model complements SimpleX Messaging Protocol [threat model](./security.md#threat-model) with agent-level concerns: duplex connections, end-to-end encryption with [post-quantum double ratchet](./pqdr.md), message integrity, connection establishment and queue rotation. Only additional properties not covered in the SMP threat model are listed below.
+
+#### Additional global assumptions
+
+ - The connection link is shared via a trusted out-of-band channel.
+ - Both agents support post-quantum double ratchet (PQDR).
+
+#### A passive adversary
+
+*cannot:*
+ - learn the contents of packets, which are additionally encrypted with the double ratchet independently from per-queue encryption.
+
+#### Destination router (chosen by the receiving client application)
+
+*can:*
+ - correlate queues belonging to the same duplex connection when queue rotation creates a new queue on the same router.
+ - when both peers of a connection chose the same router, correlate the two directions of the duplex connection.
+
+*cannot:*
+ - compromise end-to-end encryption even with full access to the per-queue NaCl DH secret.
+ - correlate queues belonging to the same connection after queue rotation to a different router.
+
+#### An attacker who obtained a client application's (decrypted) database
+
+*can:*
+ - learn the full communication graph: all communication peers, associated router addresses, and queue identifiers.
+
+*cannot:*
+ - decrypt future messages once the client application resumes communication and the double ratchet completes a new ratchet step, provided PQDR is active.
+
+#### A communication peer
+
+*can:*
+ - send malformed agent messages that may affect the client application processing them.
+ - skip message IDs, causing the recipient to generate and store excessive intermediate ratchet keys.
+ - prevent double ratchet advancement by not sending messages, delaying break-in recovery.
+
+*cannot:*
+ - disrupt packet delivery in other queues.
+
+#### An attacker who obtained a connection link
+
+*can:*
+ - learn the initiating party's chosen router address and public keys.
+
+*cannot:*
+ - use the link after the intended recipient has completed the connection.
+
 [1]: https://en.wikipedia.org/wiki/End-to-end_encryption
 [2]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
 [3]: https://tools.ietf.org/html/rfc5234

protocol/overview-tjr.md

@@ -1,4 +1,4 @@
-Revision 2, 2024-06-22
+Revision 4, 2026-03-09
 
 Evgeny Poberezkin
 
@@ -8,16 +8,17 @@ Evgeny Poberezkin
 
 - [Introduction](#introduction)
   - [What is SimpleX](#what-is-simplex)
+  - [Network model](#network-model)
+  - [Applications](#applications)
   - [SimpleX objectives](#simplex-objectives)
   - [In Comparison](#in-comparison)
 - [Technical Details](#technical-details)
-  - [Trust in Servers](#trust-in-servers)
-  - [Client -> Server Communication](#client---server-communication)
+  - [Trust in Routers](#trust-in-routers)
+  - [Client -> Router Communication](#client---router-communication)
   - [2-hop Onion Message Routing](#2-hop-onion-message-routing)
   - [SimpleX Messaging Protocol](#simplex-messaging-protocol)
   - [SimpleX Agents](#simplex-agents)
-  - [Encryption Primitives Used](#encryption-primitives-used)
-- [Threat model](#threat-model)
+- [Security](#security)
 - [Acknowledgements](#acknowledgements)
 
 
@@ -27,27 +28,27 @@ Evgeny Poberezkin
 
 SimpleX as a whole is a platform upon which applications can be built. [SimpleX Chat](https://github.com/simplex-chat/simplex-chat) is one such application that also serves as an example and reference application.
 
- - [SimpleX Messaging Protocol](./simplex-messaging.md) (SMP) is a protocol to send messages in one direction to a recipient, relying on a server in-between. The messages are delivered via uni-directional queues created by recipients.
- 
- - SMP protocol allows to send message via a SMP server playing proxy role using 2-hop onion routing (referred to as "private routing" in messaging clients) to protect transport information of the sender (IP address and session) from the server chosen (and possibly controlled) by the recipient.
+ - [SimpleX Messaging Protocol](./simplex-messaging.md) (SMP) is a protocol to send messages in one direction to a recipient, relying on a router in-between. The messages are delivered via uni-directional queues created by recipients.
+
+ - SMP protocol allows to send message via a SMP router playing proxy role using 2-hop onion routing (referred to as "private routing" in messaging clients) to protect transport information of the sender (IP address and session) from the router chosen (and possibly controlled) by the recipient.
 
  - SMP runs over a transport protocol (shown below as TLS) that provides integrity, server authentication, confidentiality, and transport channel binding.
 
- - A SimpleX Server is one of those servers.
+ - A SimpleX router is one of those routers.
 
- - The SimpleX Network is the term used for the collective of SimpleX Servers that facilitate SMP.
+ - The SimpleX Network is the term used for the collective of SimpleX routers that facilitate SMP.
 
- - SimpleX Client libraries speak SMP to SimpleX Servers and provide a low-level API not generally intended to be used by applications.
+ - SimpleX Client libraries speak SMP to SimpleX routers and provide a low-level API not generally intended to be used by applications.
 
  - SimpleX Agents interface with SimpleX Clients to provide a more high-level API intended to be used by applications. Typically they are embedded as libraries, but can also be abstracted into local services.
 
  - SimpleX Agents communicate with other agents inside e2e encrypted envelopes provided by SMP protocol - the syntax and semantics of the messages exchanged by the agent are defined by [SMP agent protocol](./agent-protocol.md)
 
 
-*Diagram showing the SimpleX Chat app, with logical layers of the chat application interfacing with a SimpleX Agent library, which in turn interfaces with a SimpleX Client library. The Client library in turn speaks the Messaging Protocol to a SimpleX Server.*
+*Diagram showing the SimpleX Chat app, with logical layers of the chat application interfacing with a SimpleX Agent library, which in turn interfaces with a SimpleX Client library. The Client library in turn speaks the Messaging Protocol to a SimpleX router.*
 
 ```
-  User's Computer                 Internet                    Third-Party Server
+  User's Computer                 Internet                    Third-Party Router
 ------------------     |   ----------------------     |   -------------------------
                        |                              |
    SimpleX Chat        |                              |
@@ -57,11 +58,43 @@ SimpleX as a whole is a platform upon which applications can be built. [SimpleX
 +----------------+     |                              |
 |  SimpleX Agent |     |                              |
 +----------------+    -------------- TLS ----------------    +----------------+
-| SimpleX Client | ------ SimpleX Messaging Protocol ------> | SimpleX Server |
+| SimpleX Client | ------ SimpleX Messaging Protocol ------> | SimpleX router |
 +----------------+    -----------------------------------    +----------------+
                        |                              |
 ```
 
+#### Network model
+
+SimpleX is a general-purpose packet routing network built on top of the Internet. Network endpoints — end-user devices, automated services, AI-enabled applications, IoT devices — exchange data packets through SimpleX network nodes (SMP routers), which accept, buffer, and deliver packets. Each router operates independently and can be operated by any party on standard computing hardware.
+
+SimpleX routers use resource-based addressing: each address identifies a resource on a router, similar to how the World Wide Web addresses resources via URLs. Internet routers, by comparison, use endpoint-based addressing, where IP addresses identify destination devices. Because of this design, SimpleX network participants do not need globally unique addresses to communicate.
+
+SimpleX network has two resource-based addressing schemes:
+
+- *Messaging queues* ([SMP](./simplex-messaging.md)). A queue is a unidirectional, ordered sequence of fixed-size data packets (16,384 bytes each). Each queue has a resource address on a specific router, gated by cryptographic credentials that separately authorize sending and receiving.
+
+- *Data packets* ([XFTP](./xftp.md)). A data packet is an individually addressed block in one of the standard sizes. Each packet has a unique resource address on a specific router, gated by cryptographic credentials. Data packet addressing is more efficient for delivery of larger payloads than queues.
+
+Packet delivery follows a two-router path. The sending endpoint submits a packet to a first router, which forwards it to a second router, where the receiving endpoint retrieves it. The sending endpoint's IP address is known only to the first router; the receiving endpoint's IP address is known only to the second router. See [2-hop Onion Message Routing](#2-hop-onion-message-routing) for details.
+
+Routers buffer packets between submission and retrieval — from seconds to days, enabling asynchronous delivery when endpoints are online at different times. Packets are removed after delivery or after a configured expiration period.
+
+
+#### Applications
+
+Applications currently using SimpleX network:
+
+- **SimpleX Chat** — a peer-to-peer messenger using SimpleX network as a transport layer, in the same way that communication applications use WebRTC, Tor, i2p, or Nym. All communication logic — contacts, conversations, groups, message formats, end-to-end encryption — runs on endpoint devices.
+
+- **IoT devices** — using the SimpleX queue protocol directly for sensor data collection and device control.
+
+- **AI-based services** — automated services built on the SimpleX Chat application core.
+
+- **Secure monitoring and control systems** — applications for equipment monitoring and control, including robotics, using the network for command delivery and telemetry collection.
+
+[SimpleGo](https://simplego.dev), developed by an independent organization, is a microcontroller-based device running a SimpleX Chat-compatible messenger directly on a microcontroller without a general-purpose operating system. Running over 20 days on a single battery charge, it demonstrates the energy efficiency of resource-based addressing: the device receives packets without continuous polling. A microcontroller-based router implementation that functions simultaneously as a WiFi router is also in development.
+
+
 #### SimpleX objectives
 
 1. Provide messaging infrastructure for distributed applications. This infrastructure needs to have the following qualities:
@@ -70,7 +103,7 @@ SimpleX as a whole is a platform upon which applications can be built. [SimpleX
 
    - Privacy: protect against traffic correlation attacks to determine the contacts that the users communicate with.
 
-   - Reliability: the messages should be delivered even if some participating network servers or receiving clients fail, with “at least once” delivery guarantee.
+   - Reliability: the messages should be delivered even if some participating network routers or receiving clients fail, with "at least once" delivery guarantee.
 
    - Integrity: the messages sent in one direction are ordered in a way that sender and recipient agree on; the recipient can detect when a message was removed or changed.
 
@@ -78,63 +111,63 @@ SimpleX as a whole is a platform upon which applications can be built. [SimpleX
 
    - Low latency: the delay introduced by the network should not be higher than 100ms-1s in addition to the underlying TCP network latency.
 
-2. Provide better communication security and privacy than the alternative instant messaging solutions. In particular SimpleX provides better privacy of metadata (who talks to whom and when) and better security against active network attackers and malicious servers.
+2. Provide better communication security and privacy than the alternative instant messaging solutions. In particular SimpleX provides better privacy of metadata (who talks to whom and when) and better security against active network attackers and malicious routers.
 
 3. Balance user experience with privacy requirements, prioritizing experience of mobile device users.
 
 
 #### In Comparison
 
-SimpleX network has a design similar to P2P networks, but unlike most P2P networks it consists of clients and servers without depending on any centralized component.
+SimpleX network has a design similar to P2P networks, but unlike most P2P networks it consists of clients and routers without depending on any centralized component.
 In comparison to more traditional messaging applications (e.g. WhatsApp, Signal, Telegram) the key differences of SimpleX network are:
 
 - participants do not need to have globally unique addresses to communicate, instead they use redundant unidirectional (simplex) messaging queues, with a separate set of queues for each contact.
 
 - connection requests are passed out-of-band, non-optionally protecting key exchange against man-in-the-middle attack.
 
-- simple message queues provided by network servers are used by the clients to create more complex communication scenarios, such as duplex one-to-one communication, transmitting files, group communication without central servers, and content/communication channels.
+- simple message queues provided by network routers are used by the clients to create more complex communication scenarios, such as duplex one-to-one communication, transmitting files, group communication without central routers, and content/communication channels.
 
-- servers do not store any user information (no user profiles or contacts, or messages once they are delivered), and primarily use in-memory persistence.
+- routers do not store any user information (no user profiles or contacts, or messages once they are delivered), and primarily use in-memory persistence.
 
-- users can change servers with minimal disruption - even after an in-use server disappears, simply by changing the configuration on which servers the new queues are created.
+- users can change routers with minimal disruption - even after an in-use router disappears, simply by changing the configuration on which routers the new queues are created.
 
 
 ## Technical Details
 
-#### Trust in Servers
+#### Trust in Routers
 
-Clients communicate directly with servers (but not with other clients) using SimpleX Messaging Protocol (SMP) running over some transport protocol that provides integrity, server authentication, confidentiality, and transport channel binding. By default, we assume this transport protocol is TLS.
+Clients communicate directly with routers (but not with other clients) using SimpleX Messaging Protocol (SMP) running over some transport protocol that provides integrity, server authentication, confidentiality, and transport channel binding. By default, we assume this transport protocol is TLS.
 
-Users use multiple servers, and choose where to receive their messages. Accordingly, they send messages to their communication partners' chosen servers either directly, if this is a known/trusted server, or via another SMP server providing proxy functionality to protect IP address and session of the sender.
+Users use multiple routers, and choose where to receive their messages. Accordingly, they send messages to their communication partners' chosen routers either directly, if this is a known/trusted router, or via another SMP router providing proxy functionality to protect IP address and session of the sender.
 
-Although end-to-end encryption is always present, users place a degree of trust in servers they connect to. This trust decision is very similar to a user's choice of email provider; however the trust placed in a SimpleX server is significantly less. Notably, there is no re-used identifier or credential between queues on the same (or different) servers. While a user *may* re-use a transport connection to fetch messages from multiple queues, or connect to a server from the same IP address, both are choices a user may opt into to break the promise of un-correlatable queues.
+Although end-to-end encryption is always present, users place a degree of trust in routers they connect to. This trust decision is very similar to a user's choice of email provider; however the trust placed in a SimpleX router is significantly less. Notably, there is no re-used identifier or credential between queues on the same (or different) routers. While a user *may* re-use a transport connection to fetch messages from multiple queues, or connect to a router from the same IP address, both are choices a user may opt into to break the promise of un-correlatable queues.
 
-Users may trust a server because:
+Users may trust a router because:
 
-- They deploy and control the servers themselves from the available open-source code. This has the trade-offs of strong trust in the server but limited metadata obfuscation to a passive network observer. Techniques such as noise traffic, traffic mixing (incurring latency), and using an onion routing transport protocol can mitigate that.
+- They deploy and control the routers themselves from the available open-source code. This has the trade-offs of strong trust in the router but limited metadata obfuscation to a passive network observer. Techniques such as noise traffic, traffic mixing (incurring latency), and using an onion routing transport protocol can mitigate that.
 
-- They use servers from a trusted commercial provider. The more clients the provider has, the less metadata about the communication times is leaked to the network observers.
+- They use routers from a trusted commercial provider. The more clients the provider has, the less metadata about the communication times is leaked to the network observers.
 
-By default, servers do not retain access logs, and permanently delete messages and queues when requested. Messages persist only in memory until they cross a threshold of time, typically on the order of days.[0] There is still a risk that a server maliciously records all queues and messages (even though encrypted) sent via the same transport connection to gain a partial knowledge of the user’s communications graph and other meta-data.
+By default, routers do not retain access logs, and permanently delete messages and queues when requested. Messages persist in memory or in a database until they cross a threshold of time, typically on the order of days.[0] There is still a risk that a router maliciously records all queues and messages (even though encrypted) sent via the same transport connection to gain a partial knowledge of the user's communications graph and other meta-data.
 
-SimpleX supports measures (managed transparently to the user at the agent level) to mitigate the trust placed in servers.  These include rotating the queues in use between users, noise traffic, supporting overlay networks such as Tor, and isolating traffic to different queues to different transport connections (and Tor circuits, if Tor is used).
+SimpleX supports measures (managed transparently to the user at the agent level) to mitigate the trust placed in routers.  These include rotating the queues in use between users, noise traffic, supporting overlay networks such as Tor, and isolating traffic to different queues to different transport connections (and Tor circuits, if Tor is used).
 
-[0] While configurable by servers, a minimum value is enforced by the default software. SimpleX Agents can provide redundant routing over queues to mitigate against message loss.
+[0] While configurable by routers, a minimum value is enforced by the default software. SimpleX Agents can provide redundant routing over queues to mitigate against message loss.
 
 
-#### Client -> Server Communication
+#### Client -> Router Communication
 
 Utilizing TLS grants the SimpleX Messaging Protocol (SMP) server authentication and metadata protection to a passive network observer. But SMP does not rely on the transport protocol for message confidentiality or client authentication. The SMP protocol itself provides end-to-end confidentiality, authentication, and integrity of messages between communicating parties.
 
-Servers have long-lived, self-signed, offline certificates whose hash is pre-shared with clients over secure channels - either provided with the client library or provided in the secure introduction between clients, as part of the server address.  The offline certificate signs an online certificate used in the transport protocol handshake. [0]
+Routers have long-lived, self-signed, offline certificates whose hash is pre-shared with clients over secure channels - either provided with the client library or provided in the secure introduction between clients, as part of the router address.  The offline certificate signs an online certificate used in the transport protocol handshake. [0]
 
-If the transport protocol's confidentiality is broken, incoming and outgoing messages to the server cannot be correlated by message contents. Additionally, because of encryption at the SMP layer, impersonating the server is not sufficient to pass (and therefore correlate) a message from a sender to recipient - the only attack possible is to drop the messages. Only by additionally *compromising* the server can one pass and correlate messages.
+If the transport protocol's confidentiality is broken, incoming and outgoing messages to the router cannot be correlated by message contents. Additionally, because of encryption at the SMP layer, impersonating the router is not sufficient to pass (and therefore correlate) a message from a sender to recipient - the only attack possible is to drop the messages. Only by additionally *compromising* the router can one pass and correlate messages.
 
-It's important to note that the SMP protocol does not do server authentication. Instead we rely upon the fact that an attacker who tricks the transport protocol into authenticating the server incorrectly cannot do anything with the SMP messages except drop them.
+It's important to note that the SMP protocol does not do server authentication. Instead we rely upon the fact that an attacker who tricks the transport protocol into authenticating the router incorrectly cannot do anything with the SMP messages except drop them.
 
-After the connection is established, the client sends blocks of a fixed size 16KB, and the server replies with the blocks of the same size to reduce metadata observable to a network adversary. The protocol has been designed to make traffic correlation attacks difficult, adapting ideas from Tor, remailers, and more general onion and mix networks. It does not try to replace Tor though - SimpleX servers can be deployed as onion services and SimpleX clients can communicate with servers over Tor to further improve participants privacy.
+After the connection is established, the client sends blocks of a fixed size 16KB, and the router replies with the blocks of the same size to reduce metadata observable to a network adversary. The protocol has been designed to make traffic correlation attacks difficult, adapting ideas from Tor, remailers, and more general onion and mix networks. It does not try to replace Tor though - SimpleX routers can be deployed as onion services and SimpleX clients can communicate with routers over Tor to further improve participants privacy.
 
-By using fixed-size blocks, oversized for the expected content, the vast majority of traffic is uniform in nature. When enough traffic is transiting a server simultaneously, the server acts as a low-latency mix node. We can't rely on this behavior to make a security claim, but we have engineered to take advantage of it when we can. As mentioned, this holds true even if the transport connection is compromised.
+By using fixed-size blocks, oversized for the expected content, the vast majority of traffic is uniform in nature. When enough traffic is transiting a router simultaneously, the router acts as a low-latency mix node. We can't rely on this behavior to make a security claim, but we have engineered to take advantage of it when we can. As mentioned, this holds true even if the transport connection is compromised.
 
 The protocol does not protect against attacks targeted at particular users with known identities - e.g., if the attacker wants to prove that two known users are communicating, they can achieve it by observing their local traffic. At the same time, it substantially complicates large-scale traffic correlation, making determining the real user identities much less effective.
 
@@ -143,39 +176,39 @@ The protocol does not protect against attacks targeted at particular users with
 
 #### 2-hop Onion Message Routing
 
-As SimpleX Messaging Protocol servers providing messaging queues are chosen by the recipients, in case senders connect to these servers directly the server owners (who potentially can be the recipients themselves) can learn senders' IP addresses (if Tor is not used) and which other queues on the same server are accessed by the user in the same transport connection (even if Tor is used).
+As SimpleX Messaging Protocol routers providing messaging queues are chosen by the recipients, in case senders connect to these routers directly the router owners (who potentially can be the recipients themselves) can learn senders' IP addresses (if Tor is not used) and which other queues on the same router are accessed by the user in the same transport connection (even if Tor is used).
 
 While the clients support isolating the messages sent to different queues into different transport connections (and Tor circuits), this is not practical, as it consumes additional traffic and system resources.
 
-To mitigate this problem SimpleX Messaging Protocol servers support 2-hop onion message routing when the SMP server chosen by the sender forwards the messages to the servers chosen by the recipients, thus protecting both the senders IP addresses and sessions, even if connection isolation and Tor are not used.
+To mitigate this problem SimpleX Messaging Protocol routers support 2-hop onion message routing when the SMP router chosen by the sender forwards the messages to the routers chosen by the recipients, thus protecting both the senders IP addresses and sessions, even if connection isolation and Tor are not used.
 
 The design of 2-hop onion message routing prevents these potential attacks:
 
-- MITM by proxy (SMP server that forwards the messages).
+- MITM by proxy (SMP router that forwards the messages).
 
-- Identification by the proxy which and how many queues the sender sends messages to (as messages are additionally e2e encrypted between the sender and the destination SMP server).
+- Identification by the proxy which and how many queues the sender sends messages to (as messages are additionally e2e encrypted between the sender and the destination SMP router).
 
 - Correlation of messages sent to different queues via the same user session (as random correlation IDs and keys are used for each message).
 
 See more details about 2-hop onion message routing design in [SimpleX Messaging Protocol](./simplex-messaging.md#proxying-sender-commands)
 
-Also see [Threat model](#threat-model)
+Also see [Security](./security.md)
 
 
 #### SimpleX Messaging Protocol
 
-SMP is initialized with an in-person or out-of-band introduction message, where Alice provides Bob with details of a server (including IP address or host name, port, and hash of the long-lived offline certificate), a queue ID, and Alice's public keys to agree e2e encryption. These introductions are similar to the PANDA key-exchange, in that if observed, the adversary can race to establish the communication channel instead of the intended participant. [0]
+SMP is initialized with an in-person or out-of-band introduction message, where Alice provides Bob with details of a router (including IP address or host name, port, and hash of the long-lived offline certificate), a queue ID, and Alice's public keys to agree e2e encryption. These introductions are similar to the PANDA key-exchange, in that if observed, the adversary can race to establish the communication channel instead of the intended participant. [0]
 
 Because queues are uni-directional, Bob provides an identically-formatted introduction message to Alice over Alice's now-established receiving queue.
 
-When setting up a queue, the server will create separate sender and recipient queue IDs (provided to Alice during set-up and Bob during initial connection). Additionally, during set-up Alice will perform a DH exchange with the server to agree upon a shared secret. This secret will be used to re-encrypt Bob's incoming message before Alice receives it, creating the anti-correlation property earlier-described should the transport encryption be compromised.
+When setting up a queue, the router will create separate sender and recipient queue IDs (provided to Alice during set-up and Bob during initial connection). Additionally, during set-up Alice will perform a DH exchange with the router to agree upon a shared secret. This secret will be used to re-encrypt Bob's incoming message before Alice receives it, creating the anti-correlation property earlier-described should the transport encryption be compromised.
 
-[0] Users can additionally create public 'contact queues' that are only used to receive connection requests.  
+[0] Users can additionally create public 'contact queues' that are only used to receive connection requests.
 
 
 #### SimpleX Agents
 
-SimpleX agents provide higher-level operations compared to SimpleX Clients, who are primarily concerned with creating queues and communicating with servers using SMP.  Agent operations include:
+SimpleX agents provide higher-level operations compared to SimpleX Clients, who are primarily concerned with creating queues and communicating with routers using SMP.  Agent operations include:
 
 - Managing sets of bi-directional, redundant queues for communication partners
 
@@ -186,195 +219,21 @@ SimpleX agents provide higher-level operations compared to SimpleX Clients, who
 - Noise traffic
 
 
-#### Encryption Primitives Used
+## Security
 
-- Ed25519 or Curve25519 to authorize/verify commands to SMP servers (authorization algorithm is set via client/server configuration).
-- Curve25519 for DH exchange to agree:
-  - the shared secret between server and recipient (to encrypt message bodies - it avoids shared cipher-text in sender and recipient traffic)
-  - the shared secret between sender and recipient (to encrypt messages end-to-end in each queue - it avoids shared cipher-text in redundant queues).
-- [NaCl crypto_box](https://nacl.cr.yp.to/box.html) encryption scheme (curve25519xsalsa20poly1305) for message body encryption between server and recipient and for E2E per-queue encryption.
-- SHA256 to validate server offline certificates.
-- [double ratchet](https://signal.org/docs/specifications/doubleratchet/) protocol for end-to-end message encryption between the agents:
-  - Curve448 keys to agree shared secrets required for double ratchet initialization (using [X3DH](https://signal.org/docs/specifications/x3dh/) key agreement with 2 ephemeral keys for each side),
-  - AES-GCM AEAD cipher,
-  - SHA512-based HKDF for key derivation.
+For encryption primitives, threat model, and detailed security analysis, see [Security](./security.md).
 
+SimpleX provides these security properties:
 
-## Threat Model
+- **End-to-end encryption** using Double Ratchet algorithm with forward secrecy and post-quantum cryptography.
 
-#### Global Assumptions
+- **No shared identifiers** across connections — contacts cannot prove they communicate with the same user.
 
- - A user protects their local database and key material.
- - The user's application is authentic, and no local malware is running.
- - The cryptographic primitives in use are not broken.
- - A user's choice of servers is not directly tied to their identity or otherwise represents distinguishing information about the user.
- - The user's client uses 2-hop onion message routing.
+- **Sender deniability** — neither routers nor recipients can cryptographically prove message origin.
 
-#### A passive adversary able to monitor the traffic of one user
+- **Transport metadata protection** — fixed-size blocks, 2-hop onion routing, and optional connection isolation frustrate traffic correlation.
 
-*can:*
-
- - identify that and when a user is using SimpleX.
-
- - determine which servers the user receives the messages from.
-
- - observe how much traffic is being sent, and make guesses as to its purpose.
-
-*cannot:*
-
- - see who sends messages to the user and who the user sends the messages to.
-
- - determine the servers used by users' contacts.
-
-#### A passive adversary able to monitor a set of senders and recipients
-
- *can:*
-
- - identify who and when is using SimpleX.
-
- - learn which SimpleX Messaging Protocol servers are used as receive queues for which users.
-
- - learn when messages are sent and received.
-
- - perform traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the servers.
-
- - observe how much traffic is being sent, and make guesses as to its purpose
-
-*cannot, even in case of a compromised transport protocol:*
-
- - perform traffic correlation attacks with any increase in efficiency over a non-compromised transport protocol
-
-#### SimpleX Messaging Protocol server
-
-*can:*
-
-- learn when a queue recipient is online
-
-- know how many messages are sent via the queue (although some may be noise or not content messages).
-
-- learn which messages would trigger notifications even if a user does not use [push notifications](./push-notifications.md).
-
-- perform the correlation of the queue used to receive messages (matching multiple queues to a single user) via either a re-used transport connection, user's IP Address, or connection timing regularities.
-
-- learn a recipient's IP address, track them through other IP addresses they use to access the same queue, and infer information (e.g. employer) based on the IP addresses, as long as Tor is not used.
-
-- drop all future messages inserted into a queue, detectable only over other, redundant queues.
-
-- lie about the state of a queue to the recipient and/or to the sender  (e.g. suspended or deleted when it is not).
-
-- spam a user with invalid messages.
-
-*cannot:*
-
-- undetectably add, duplicate, or corrupt individual messages.
-
-- undetectably drop individual messages, so long as a subsequent message is delivered.
-
-- learn the contents or type of messages.
-
-- distinguish noise messages from regular messages except via timing regularities.
-
-- compromise the users' end-to-end encryption with an active attack.
-
-- learn a sender's IP address, track them through other IP addresses they use to access the same queue, and infer information (e.g. employer) based on the IP addresses, even if Tor is not used (provided messages are sent via proxy SMP server).
-
-- perform senders' queue correlation (matching multiple queues to a single sender) via either a re-used transport connection, user's IP Address, or connection timing regularities, unless it has additional information from the proxy SMP server (provided messages are sent via proxy SMP server).
-
-#### SimpleX Messaging Protocol server that proxies the messages to another SMP server
-
-*can:*
-
-- learn a sender's IP address, as long as Tor is not used.
-
-- learn when a sender with a given IP address is online.
-
-- know how many messages are sent from a given IP address and to a given destination SMP server.
-
-- drop all messages from a given IP address or to a given destination server.
-
-- unless destination SMP server detects repeated public DH keys of senders, replay messages to a destination server within a single session, causing either duplicate message delivery (which will be detected and ignored by the receiving clients), or, when receiving client is not connected to SMP server, exhausting capacity of destination queues used within the session.
-
-*cannot:*
-
-- perform queue correlation (matching multiple queues to a single user), unless it has additional information from the destination SMP server.
-
-- undetectably add, duplicate, or corrupt individual messages.
-
-- undetectably drop individual messages, so long as a subsequent message is delivered.
-
-- learn the contents or type of messages.
-
-- learn which messages would trigger notifications.
-
-- learn the destination queues of messages.
-
-- distinguish noise messages from regular messages except via timing regularities.
-
-- compromise the user's end-to-end encryption with another user via an active attack.
-
-- compromise the user's end-to-end encryption with the destination SMP servers via an active attack.
-
-#### An attacker who obtained Alice's (decrypted) chat database
-
-*can:*
-
-- see the history of all messages exchanged by Alice with her communication partners.
-
-- see shared profiles of contacts and groups.
-
-- surreptitiously receive new messages sent to Alice via existing queues; until communication queues are rotated or the Double-Ratchet advances forward.
-
-- prevent Alice from receiving all new messages sent to her - either surreptitiously by emptying the queues regularly or overtly by deleting them.
-
-- send messages from the user to their contacts; recipients will detect it as soon as the user sends the next message, because the previous message hash won’t match (and potentially won’t be able to decrypt them in case they don’t keep the previous ratchet keys).
-
-*cannot:*
-
-- impersonate a sender and send messages to the user whose database was stolen. Doing so requires also compromising the server (to place the message in the queue, that is possible until the Double-Ratchet advances forward) or the user's device at a subsequent time (to place the message in the database).
-
-- undetectably communicate at the same time as Alice with her contacts. Doing so would result in the contact getting different messages with repeated IDs.
-
-- undetectably monitor message queues in realtime without alerting the user they are doing so, as a second subscription request unsubscribes the first and notifies the second.
-
-#### A user’s contact
-
-*can:*
-
-- spam the user with messages.
-
-- forever retain messages from the user.
-
-*cannot:*
-
-- cryptographically prove to a third-party that a message came from a user (assuming the user’s device is not seized).
-
-- prove that two contacts they have is the same user.
-
-- cannot collaborate with another of the user's contacts to confirm they are communicating with the same user.
-
-#### An attacker who observes Alice showing an introduction message to Bob
-
-*can:*
-
- - Impersonate Bob to Alice.
-
-*cannot:*
-
- - Impersonate Alice to Bob.
-
-#### An attacker with Internet access
-
-*can:*
-
-- Denial of Service SimpleX messaging servers.
-
-- spam a user's public “contact queue” with connection requests.
-
-*cannot:*
-
-- send messages to a user who they are not connected with.
-
-- enumerate queues on a SimpleX server.
+- **Out-of-band key exchange** — connection requests passed outside the network protect against MITM attacks.
 
 
 ## Acknowledgements

protocol/pqdr.md

@@ -13,6 +13,11 @@ Version 1, 2024-06-22
   - [Initialization](#initialization)
   - [Encrypting messages](#encrypting-messages)
   - [Decrypting messages](#decrypting-messages)
+- [Ratchet message wire format](#ratchet-message-wire-format)
+  - [Encrypted ratchet message](#encrypted-ratchet-message)
+  - [Encrypted message header](#encrypted-message-header)
+  - [Plaintext message header](#plaintext-message-header)
+  - [KEM state machine](#kem-state-machine)
 - [Implementation considerations](#implementation-considerations)
 - [Chosen KEM algorithm](#chosen-kem-algorithm)
 - [Summary](#summary)
@@ -71,11 +76,10 @@ def RatchetInitAlicePQ2HE(state, SK, bob_dh_public_key, shared_hka, shared_nhkb,
     // below added for post-quantum KEM
     state.PQRs = GENERATE_PQKEM()
     state.PQRr = bob_pq_kem_encapsulation_key
-    state.PQRss = random // shared secret for KEM
-    state.PQRct = PQKEM-ENC(state.PQRr, state.PQRss) // encapsulated additional shared secret
+    state.PQRct, state.PQRss = PQKEM-ENC(state.PQRr) // encapsulate: generates shared secret and ciphertext
     // above added for KEM
     // the next line augments DH key agreement with PQ shared secret
-    state.RK, state.CKs, state.NHKs = KDF_RK_HE(SK, DH(state.DHRs, state.DHRr) || state.PQRss) 
+    state.RK, state.CKs, state.NHKs = KDF_RK_HE(SK, DH(state.DHRs, state.DHRr) || state.PQRss)
     state.CKr = None
     state.Ns = 0
     state.Nr = 0
@@ -176,8 +180,7 @@ def DHRatchetPQ2HE(state, header):
     state.DHRs = GENERATE_DH()
     // below is added for KEM
     state.PQRs = GENERATE_PQKEM() // generate new PQ key pair
-    state.PQRss = random // shared secret for KEM
-    state.PQRct = PQKEM-ENC(state.PQRr, state.PQRss) // encapsulated additional shared secret KEM #1
+    state.PQRct, state.PQRss = PQKEM-ENC(state.PQRr) // encapsulate: generates shared secret and ciphertext KEM #1
     // above is added for KEM
     // use new shared secret with sending ratchet
     state.RK, state.CKs, state.NHKs = KDF_RK_HE(state.RK, DH(state.DHRs, state.DHRr) || state.PQRss)
@@ -191,6 +194,80 @@ Other than augmenting DH key agreements with the shared secrets from KEM, the ab
 
 It is worth noting that while DH agreements work as ping-pong, when the new received DH key is used for both DH agreements (and only the sent DH key is updated for the second DH key agreement), PQ KEM agreements in the proposed scheme work as a "parallel ping-pong", with two balls in play all the time (two KEM agreements run in parallel).
 
+## Ratchet message wire format
+
+The pseudocode above describes the algorithm. This section specifies the actual binary encoding used in SimpleX implementation with Curve448 DH keys, sntrup761 KEM and AES-256-GCM AEAD.
+
+The ratchet-encrypted message has three encoding layers, from outermost to innermost:
+
+1. **Encrypted ratchet message** — the complete ratchet message envelope, referenced as an opaque encrypted body in [agent protocol](./agent-protocol.md).
+2. **Encrypted message header** — the encrypted header within the ratchet message, used as associated data for message body encryption.
+3. **Plaintext message header** — the DH and KEM ratchet keys and counters.
+
+### Encrypted ratchet message
+
+The outer envelope contains the encrypted header (used as associated data for body authentication), the body authentication tag, and the encrypted message body.
+
+The message body is encrypted with AES-256-GCM using the message key derived from the sending chain key (`KDF_CK`). The associated data for body encryption is the concatenation of the ratchet associated data and the encoded encrypted header.
+
+```abnf
+encRatchetMessage = versionedLength encMessageHeader msgAuthTag encMsgBody
+; encMessageHeader is used as associated data for body decryption: AD = rcAD || encMessageHeader
+msgAuthTag = 16*16 OCTET ; AES-256-GCM authentication tag for the message body
+encMsgBody = *OCTET ; AES-256-GCM encrypted padded message body (remaining bytes)
+```
+
+### Encrypted message header
+
+The encrypted header wraps the current ratchet e2e encryption version, an initialization vector, an authentication tag, and the encrypted padded header body.
+
+The header body is encrypted with AES-256-GCM using the header key (`HKs`). The associated data for header encryption is the ratchet associated data. The header is padded before encryption to a fixed size to prevent leaking information about the KEM state.
+
+```abnf
+encMessageHeader = currentVersion headerIV headerAuthTag versionedLength encHeaderBody
+currentVersion = 2*2 OCTET ; Word16, current ratchet e2e encryption version
+headerIV = 16*16 OCTET ; AES-256 initialization vector for header encryption
+headerAuthTag = 16*16 OCTET ; AES-256-GCM authentication tag for the header
+encHeaderBody = *OCTET ; AES-256-GCM encrypted padded header (see plaintext format below)
+```
+
+`versionedLength` uses a 2-byte length prefix (Word16) when the current e2e version supports PQ encryption, or a 1-byte length prefix otherwise. The parser distinguishes the two encodings by peeking at the first byte: values below 32 indicate a 2-byte prefix (as the header is always at least 69 bytes).
+
+```abnf
+versionedLength = largeLength / length ; 2-byte for PQ versions, 1-byte for pre-PQ versions
+```
+
+The padded header sizes before encryption are: 2310 bytes when PQ is supported, 88 bytes when PQ is not supported. Padding uses a 2-byte big-endian length prefix followed by the plaintext header and `#` fill bytes.
+
+### Plaintext message header
+
+```abnf
+msgHeader = maxVersion dhPublicKey [kemParams] prevMsgCount msgCount
+maxVersion = 2*2 OCTET ; Word16, max supported e2e encryption version
+dhPublicKey = length x509encoded ; Curve448 public DH ratchet key
+kemParams = noKEM / proposedKEM / acceptedKEM
+  ; present only when current ratchet version >= pqRatchetE2EEncryptVersion
+noKEM = %x30 ; "0" - no KEM parameters
+proposedKEM = %x31 %s"P" kemEncapsulationKey ; KEM proposed, not yet accepted
+acceptedKEM = %x31 %s"A" kemCiphertext kemEncapsulationKey ; KEM accepted
+kemEncapsulationKey = largeLength 1158*1158 OCTET ; sntrup761 encapsulation key
+kemCiphertext = largeLength 1039*1039 OCTET ; sntrup761 ciphertext
+prevMsgCount = 4*4 OCTET ; Word32, number of messages in previous sending chain
+msgCount = 4*4 OCTET ; Word32, message number in current sending chain
+length = 1*1 OCTET
+largeLength = 2*2 OCTET ; Word16
+```
+
+### KEM state machine
+
+PQ encryption can be enabled or disabled during a connection's lifetime. The KEM parameters in the header reflect three states:
+
+- **No KEM** (`noKEM`): PQ encryption is not active. The header contains only the DH key, as in the original double ratchet.
+- **Proposed** (`proposedKEM`): One party generated a KEM key pair and includes the encapsulation key in the header, proposing PQ encryption. No ciphertext is included because the other party has not yet sent its encapsulation key.
+- **Accepted** (`acceptedKEM`): The party received the other's encapsulation key, performed encapsulation (KEM #1), and includes both the ciphertext and its own new encapsulation key (for KEM #2). This is the steady state for active PQ encryption.
+
+The transition from Proposed to Accepted happens when a party receives a message containing KEM parameters (either Proposed or Accepted) and responds with its own Accepted parameters. Once both parties are in Accepted state, the double PQ KEM augmentation described in the algorithm above operates in each DH ratchet step.
+
 ## Implementation considerations for SimpleX Messaging Protocol
 
 As SimpleX Messaging Protocol pads messages to a fixed size, using 16kb transport blocks, the size increase introduced by this scheme can be compensated for by using ZSTD encryption of JSON bodies and image previews encoded as base64. While there may be some rare cases of random texts that would fail to compress, in all real scenarios it would not cause the message size reduction.

protocol/push-notifications.md

@@ -1,14 +1,19 @@
-Version 2, 2024-06-22
+Version 3, 2025-01-24
 
-# Overview of push notifications for SimpleX Messaging Servers
+# Overview of push notifications for SimpleX Messaging Routers
+
+This document describes Notification Router protocol version 3. Version history:
+- v1: initial version
+- v2: authenticated commands, command batching
+- v3: detailed invalid token reason
 
 ## Table of contents
 
 - [Introduction](#introduction)
-- [Participating servers](#participating-servers)
+- [Participating routers](#participating-routers)
 - [Register device token to receive push notifications](#register-device-token-to-receive-push-notifications)
 - [Subscribe to connection notifications](#subscribe-to-connection-notifications)
-- [SimpleX Notification Server protocol](#simplex-notification-server-protocol)
+- [SimpleX Notification Router protocol](#simplex-notification-router-protocol)
   - [Register new notification token](#register-new-notification-token)
   - [Verify notification token](#verify-notification-token)
   - [Check notification token status](#check-notification-token-status)
@@ -23,35 +28,35 @@ Version 2, 2024-06-22
 
 ## Introduction
 
-SimpleX Messaging servers already operate as push servers and deliver the messages to subscribed clients as soon as they are sent to the servers.
+SimpleX Messaging routers already operate as push routers and deliver the messages to subscribed clients as soon as they are sent to the routers.
 
 The reason for push notifications is to support instant message notifications on iOS that does not allow background services.
 
-## Participating servers
+## Participating routers
 
-The diagram below shows which servers participate in message notification delivery.
+The diagram below shows which routers participate in message notification delivery.
 
-While push provider (e.g., APN) can learn how many notifications are delivered to the user, it cannot access message content, even encrypted, or any message metadata - the notifications are e2e encrypted between SimpleX Notification Server and the user's device.
+While push provider (e.g., APN) can learn how many notifications are delivered to the user, it cannot access message content, even encrypted, or any message metadata - the notifications are e2e encrypted between SimpleX Notification Router and the user's device.
 
 ```
-  User's iOS device                Internet                           Servers
+  User's iOS device                Internet                           Routers
 ---------------------   .   ------------------------   .   -----------------------------
                         .                              .
                         .                              .       can be self-hosted now
 +--------------+        .                              .         +----------------+
 | SimpleX Chat |       -------------- TLS ---------------        | SimpleX        |
 |    client    |------> SimpleX Messaging Protocol (SMP) ------> | Messaging      |
-+--------------+       ----------------------------------        | Server         |
++--------------+       ----------------------------------        | Router         |
      ^    |             .                              .         +----------------+
      |    |             .                              .          . . .  |   . . .
      |    |             .                              .               | V |
      |    |             .                              .               |SMP| TLS
      |    |             .                              .               | | |               SimpleX
-     |    |             .                              .          . . .  V   . . .      NTF Server
+     |    |             .                              .          . . .  V   . . .      NTF Router
      |    |             .                              .       +----------------------------------+
      |    |             .                              .       | +---------------+                |
      |    |            -------------- TLS ---------------      | | SimpleX       | can be         | 
-     |    |----------->   Notification Server Protocol  -----> | | Notifications | self-hosted    |
+     |    |----------->   Notification Router Protocol  -----> | | Notifications | self-hosted    |
      |                 ----------------------------------      | | Subscriber    | in the future  |
      |                  .                              .       | +---------------+                |
      |                  .                              .       |         |                        |
@@ -59,7 +64,7 @@ While push provider (e.g., APN) can learn how many notifications are delivered t
      |                  .                              .       | +---------------+                |
      |                  .                              .       | | SimpleX       |                |
      |                  .                              .       | | Push          |                |
-     |                  .                              .       | | Server        |                |
+     |                  .                              .       | | Router        |                |
      |                  .                              .       | +---------------+                |
      |                  .                              .       +----------------------------------+
      |                  .                              .          . . .  |   . . .
@@ -85,25 +90,28 @@ This diagram shows the process of subscription to notifications, notification de
 
 ![Subscribe to notifications](./diagrams/notifications/subscription.svg)
 
-## SimpleX Notification Server protocol
+## SimpleX Notification Router protocol
 
-To manage notification subscriptions to SMP servers, SimpleX Notification Server provides an RPC protocol with a similar design to SimpleX Messaging Protocol server.
+To manage notification subscriptions to SMP routers, SimpleX Notification Router provides an RPC protocol with a similar design to SimpleX Messaging Protocol router.
 
-This protocol sends requests and responses in a fixed size blocks of 512 bytes over TLS, uses the same [syntax of protocol transmissions](./simplex-messaging.md#smp-transmission-and-transport-block-structure) as SMP protocol, and has the same transport [handshake syntax](./simplex-messaging.md#transport-handshake) (except the server certificate is not included in the handshake).
+This protocol sends requests and responses in a fixed size blocks of 512 bytes over TLS, uses the same [syntax of protocol transmissions](./simplex-messaging.md#smp-transmission-and-transport-block-structure) as SMP protocol, and has the same transport [handshake syntax](./simplex-messaging.md#transport-handshake) (except the router certificate is not included in the handshake).
+
+The client and router use ALPN extension with `ntf/1` protocol name to agree handshake version.
 
 Protocol commands have this syntax:
 
-```
-ntfServerTransmission = 
-ntfServerCmd = newTokenCmd / verifyTokenCmd / checkTokenCmd /
+```abnf
+ntfRouterTransmission = authorization corrId entityId ntfRouterCmd
+  ; same transmission structure as SMP, see simplex-messaging.md
+ntfRouterCmd = newTokenCmd / verifyTokenCmd / checkTokenCmd /
                replaceTokenCmd / deleteTokenCmd / cronCmd /
-               newSubCmd / checkSubCmd / deleteSubCmd
+               newSubCmd / checkSubCmd / deleteSubCmd / pingCmd
 ```
 ### Register new notification token
 
-This command should be used after the client app obtains a token from push notifications provider to register the token with the server.
+This command should be used after the client app obtains a token from push notifications provider to register the token with the router.
 
-Having received this command the server will deliver a test notification via the push provider to validate that the client has this token.
+Having received this command the router will deliver a test notification via the push provider to validate that the client has this token.
 
 The command syntax:
 
@@ -111,23 +119,24 @@ The command syntax:
 newTokenCmd = %s"TNEW" SP newToken
 newToken = %s"T" deviceToken authPubKey clientDhPubKey
 deviceToken = pushProvider tokenString
-pushProvider = apnsDev / apnsProd / apnsNull
+pushProvider = apnsDev / apnsProd / apnsTest / apnsNull
 apnsDev = "AD" ; APNS token for development environment
 apnsProd = "AP" ; APNS token for production environment
-apnsNull = "AN" ; token that does not trigger any notification delivery - used for server testing
+apnsTest = "AT" ; APNS token for test environment (mock server)
+apnsNull = "AN" ; token that does not trigger any notification delivery - used for router testing
 tokenString = shortString
 authPubKey = length x509encoded ; Ed25519 key used to verify clients commands
-clientDhPubKey = length x509encoded ; X25519 key to agree e2e encryption between the server and client
+clientDhPubKey = length x509encoded ; X25519 key to agree e2e encryption between the router and client
 shortString = length *OCTET
 length = 1*1 OCTET
 ```
 
-The server response syntax:
+The router response syntax:
 
 ```abnf
-tokenIdResp = %s"IDTKN" SP entityId serverDhPubKey
+tokenIdResp = %s"IDTKN" SP entityId routerDhPubKey
 entityId = shortString
-serverDhPubKey = length x509encoded ; X25519 key to agree e2e encryption between the server and client
+routerDhPubKey = length x509encoded ; X25519 key to agree e2e encryption between the router and client
 ```
 
 ### Verify notification token
@@ -159,7 +168,9 @@ The response to this command:
 
 ```abnf
 tokenStatusResp = %s"TKN" SP tokenStatus
-tokenStatus = %s"NEW" / %s"REGISTERED" / %s"INVALID" / %s"CONFIRMED" / %s"ACTIVE" / %s"EXPIRED"
+tokenStatus = %s"NEW" / %s"REGISTERED" / tokenInvalid / %s"CONFIRMED" / %s"ACTIVE" / %s"EXPIRED"
+tokenInvalid = %s"INVALID" ["," invalidReason] ; optional reason added in v3
+invalidReason = %s"BAD" / %s"TOPIC" / %s"EXPIRED" / %s"UNREGISTERED"
 ```
 
 ### Replace notification token
@@ -200,8 +211,8 @@ After this command all message notification subscriptions will be removed and no
 This command enables or disables periodic notifications sent to the client device irrespective of message notifications.
 
 This is useful for two reasons:
-- it provides better privacy from notification server, as while the server learns the device token, it doesn't learn anything else about user communications.
-- it allows to receive messages when notifications were dropped by push provider, e.g. while the device was offline, or lost by notification server, e.g. while it was restarting.
+- it provides better privacy from notification router, as while the router learns the device token, it doesn't learn anything else about user communications.
+- it allows to receive messages when notifications were dropped by push provider, e.g. while the device was offline, or lost by notification router, e.g. while it was restarting.
 
 The command syntax:
 
@@ -214,18 +225,18 @@ The interval for periodic notifications is set in minutes, with the minimum of 2
 
 ### Create SMP message notification subscription
 
-This command makes notification server subscribe to message notifications from SMP server and to deliver them to push provider:
+This command makes notification router subscribe to message notifications from SMP router and to deliver them to push provider:
 
 ```abnf
-newSubCmd = %s"SNEW" newSub
-newSub = %s "S" tokenId smpServer notifierId notifierKey
+newSubCmd = %s"SNEW" SP newSub
+newSub = %s"S" tokenId smpRouter notifierId notifierKey
 tokenId = shortString ; returned in response to `TNEW` command
-smpServer = smpServer = hosts port fingerprint
+smpRouter = hosts port fingerprint
 hosts = length 1*host
 host = shortString
 port = shortString
 fingerprint = shortString
-notifierId = shortString ; returned by SMP server in response to `NKEY` SMP command
+notifierId = shortString ; returned by SMP router in response to `NKEY` SMP command
 notifierKey = length x509encoded ; private key used to authorize requests to subscribe to message notifications
 ```
 
@@ -247,10 +258,10 @@ The response:
 
 ```abnf
 subStatusResp = %s"SUB" SP subStatus
-subStatus = %s"NEW" / %s"PENDING" / ; e.g., after SMP server disconnect/timeout while ntf server is retrying to connect
-            %s"ACTIVE" / %s"INACTIVE" / %s"END" / ; if another server subscribed to notifications
-            %s"AUTH" / subErrStatus
-subErrStatus = %s"ERR" SP shortString
+subStatus = %s"NEW" / %s"PENDING" / ; e.g., after SMP router disconnect/timeout while ntf router is retrying to connect
+            %s"ACTIVE" / %s"INACTIVE" / %s"END" / ; if another router subscribed to notifications
+            %s"AUTH" / %s"DELETED" / %s"SERVICE" / subErrStatus
+subErrStatus = %s"ERR" SP *OCTET
 ```
 
 ### Delete notification subscription
@@ -265,6 +276,17 @@ The response to this command is `okResp` or `errorResp`.
 
 After this command no more message notifications will be sent from this queue.
 
+### Keep-alive command
+
+To keep the transport connection alive the clients should use `PING` command:
+
+```abnf
+pingCmd = %s"PING"
+pongResp = %s"PONG"
+```
+
+This command is sent unsigned and without entity ID.
+
 ### Error responses
 
 All commands can return error response:
@@ -277,7 +299,7 @@ Where `errorType` has the same syntax as in [SimpleX Messaging Protocol](./simpl
 
 ## Threat Model
 
-This threat model compliments SimpleX Messaging Protocol [threat model](./overview-tjr.md#threat-model)
+This threat model compliments SimpleX Messaging Protocol [threat model](./security.md#threat-model)
 
 #### A passive adversary able to monitor the traffic of one user
 
@@ -287,21 +309,21 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 *cannot:*
 
- - determine which servers a user subscribed to the notifications from.
+ - determine which routers a user subscribed to the notifications from.
 
 #### A passive adversary able to monitor a set of senders and recipients
 
  *can:*
 
- - perform more efficient traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the servers.
+ - perform more efficient traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the routers.
 
-#### SimpleX Messaging Protocol server
+#### SimpleX Messaging Protocol router
 
 *can:*
 
 - learn which messages trigger push notifications.
 
-- learn IP address of SimpleX notification servers used by the user.
+- learn IP address of SimpleX notification routers used by the user.
 
 - drop message notifications.
 
@@ -313,13 +335,13 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 - learn which queues belong to the same users with any additional efficiency compared with not using push notifications.
 
-#### SimpleX Notification Server subscribed to message notifications
+#### SimpleX Notification Router subscribed to message notifications
 
 *can:*
 
 - learn a user device token.
 
-- learn how many messaging queues and servers a user receives messages from.
+- learn how many messaging queues and routers a user receives messages from.
 
 - learn how many message notifications are delivered to the user from each queue.
 
@@ -339,7 +361,7 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 - add, duplicate, or corrupt individual messages that will be shown to the user.
 
-#### SimpleX Notification Server subscribed ONLY to periodic notifications
+#### SimpleX Notification Router subscribed ONLY to periodic notifications
 
 *can:*
 
@@ -351,7 +373,7 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 *cannot:*
 
-- learn how many messaging queues and servers a user receives messages from.
+- learn how many messaging queues and routers a user receives messages from.
 
 - learn how many message notifications are delivered to the user from each queue.
 
@@ -383,7 +405,7 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 *cannot:*
 
-- learn which SimpleX Messaging Protocol servers are used by a user (notifications are e2e encrypted).
+- learn which SimpleX Messaging Protocol routers are used by a user (notifications are e2e encrypted).
 
 - learn which or how many messaging queues a user receives notifications from.
 
@@ -395,4 +417,4 @@ This threat model compliments SimpleX Messaging Protocol [threat model](./overvi
 
 - register notification token not present on attacker's device.
 
-- enumerate tokens or subscriptions on a SimpleX Notification Server.
+- enumerate tokens or subscriptions on a SimpleX Notification Router.

protocol/security.md

@@ -0,0 +1,215 @@
+Revision 1, 2026-03-09
+
+# SimpleX Network: Security
+
+This document describes the cryptographic primitives and threat model for the SimpleX network. For a general introduction, see [SimpleX: messaging and application platform](./overview-tjr.md).
+
+## Table of contents
+
+- [Encryption primitives](#encryption-primitives)
+- [Threat model](#threat-model)
+  - [Global Assumptions](#global-assumptions)
+  - [A passive adversary able to monitor the traffic of one user](#a-passive-adversary-able-to-monitor-the-traffic-of-one-user)
+  - [A passive adversary able to monitor a set of senders and recipients](#a-passive-adversary-able-to-monitor-a-set-of-senders-and-recipients)
+  - [SimpleX Messaging Protocol router](#simplex-messaging-protocol-router)
+  - [SimpleX Messaging Protocol router that proxies the messages to another SMP router](#simplex-messaging-protocol-router-that-proxies-the-messages-to-another-smp-router)
+  - [An attacker who obtained Alice's (decrypted) chat database](#an-attacker-who-obtained-alices-decrypted-chat-database)
+  - [A user's contact](#a-users-contact)
+  - [An attacker who observes Alice showing an introduction message to Bob](#an-attacker-who-observes-alice-showing-an-introduction-message-to-bob)
+  - [An attacker with Internet access](#an-attacker-with-internet-access)
+
+
+## Encryption primitives
+
+- **Router command authorization**: X25519 DH-based authenticated encryption (SMP v7+), providing sender deniability. Ed25519 signatures used for recipient commands and notifier commands.
+
+- **Per-queue key agreement**: Curve25519 DH exchange to agree:
+  - the shared secret between router and recipient (to encrypt message bodies — avoids shared ciphertext in sender and recipient traffic),
+  - the shared secret between sender and recipient (to encrypt messages end-to-end in each queue — avoids shared ciphertext in redundant queues).
+
+- **SMP-layer encryption**: [NaCl crypto_box](https://nacl.cr.yp.to/box.html) (curve25519xsalsa20poly1305) for message body encryption between router and recipient, and for e2e per-queue encryption.
+
+- **Certificate validation**: SHA256 to validate router offline certificates.
+
+- **End-to-end encryption**: [Double ratchet](https://signal.org/docs/specifications/doubleratchet/) protocol:
+  - Curve448 keys for shared secret agreement via [X3DH](https://signal.org/docs/specifications/x3dh/) with 2 ephemeral keys per side,
+  - optional [SNTRUP761](https://ntruprime.cr.yp.to/) post-quantum KEM running in parallel with the DH ratchet (see [PQDR](./pqdr.md)), providing post-quantum forward secrecy,
+  - AES-GCM AEAD cipher,
+  - SHA512-based HKDF for key derivation.
+
+
+## Threat Model
+
+### Global Assumptions
+
+- A user protects their local database and key material.
+- The user's application is authentic, and no local malware is running.
+- The cryptographic primitives in use are not broken.
+- A user's choice of routers is not directly tied to their identity or otherwise represents distinguishing information about the user.
+- The user's client uses 2-hop onion message routing.
+
+### A passive adversary able to monitor the traffic of one user
+
+*can:*
+
+- identify that and when a user is using SimpleX.
+
+- determine which routers the user receives messages from.
+
+- observe how much traffic is being sent, and make guesses as to its purpose.
+
+*cannot:*
+
+- see who sends messages to the user and who the user sends messages to.
+
+- determine the routers used by users' contacts.
+
+### A passive adversary able to monitor a set of senders and recipients
+
+*can:*
+
+- identify who and when is using SimpleX.
+
+- learn which SimpleX Messaging Protocol routers are used as receive queues for which users.
+
+- learn when messages are sent and received.
+
+- perform traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the routers.
+
+- observe how much traffic is being sent, and make guesses as to its purpose.
+
+*cannot, even in case of a compromised transport protocol:*
+
+- perform traffic correlation attacks with any increase in efficiency over a non-compromised transport protocol.
+
+### SimpleX Messaging Protocol router
+
+*can:*
+
+- learn when a queue recipient is online.
+
+- know how many messages are sent via the queue (although some may be noise or not content messages).
+
+- learn which messages would trigger notifications even if a user does not use [push notifications](./push-notifications.md).
+
+- perform the correlation of the queue used to receive messages (matching multiple queues to a single user) via either a re-used transport connection, user's IP Address, or connection timing regularities.
+
+- learn a recipient's IP address, track them through other IP addresses they use to access the same queue, and infer information (e.g. employer) based on the IP addresses, as long as Tor is not used.
+
+- drop all future messages inserted into a queue, detectable only over other, redundant queues.
+
+- lie about the state of a queue to the recipient and/or to the sender  (e.g. suspended or deleted when it is not).
+
+- spam a user with invalid messages.
+
+*cannot:*
+
+- undetectably add, duplicate, or corrupt individual messages.
+
+- undetectably drop individual messages, so long as a subsequent message is delivered.
+
+- learn the contents or type of messages.
+
+- distinguish noise messages from regular messages except via timing regularities.
+
+- compromise the users' end-to-end encryption with an active attack.
+
+- learn a sender's IP address, track them through other IP addresses they use to access the same queue, and infer information (e.g. employer) based on the IP addresses, even if Tor is not used (provided messages are sent via proxy SMP router).
+
+- perform senders' queue correlation (matching multiple queues to a single sender) via either a re-used transport connection, user's IP Address, or connection timing regularities, unless it has additional information from the proxy SMP router (provided messages are sent via proxy SMP router).
+
+### SimpleX Messaging Protocol router that proxies the messages to another SMP router
+
+*can:*
+
+- learn a sender's IP address, as long as Tor is not used.
+
+- learn when a sender with a given IP address is online.
+
+- know how many messages are sent from a given IP address and to a given destination SMP router.
+
+- drop all messages from a given IP address or to a given destination router.
+
+- unless destination SMP router detects repeated public DH keys of senders, replay messages to a destination router within a single session, causing either duplicate message delivery (which will be detected and ignored by the receiving clients), or, when receiving client is not connected to SMP router, exhausting capacity of destination queues used within the session.
+
+*cannot:*
+
+- perform queue correlation (matching multiple queues to a single user), unless it has additional information from the destination SMP router.
+
+- undetectably add, duplicate, or corrupt individual messages.
+
+- undetectably drop individual messages, so long as a subsequent message is delivered.
+
+- learn the contents or type of messages.
+
+- learn which messages would trigger notifications.
+
+- learn the destination queues of messages.
+
+- distinguish noise messages from regular messages except via timing regularities.
+
+- compromise the user's end-to-end encryption with another user via an active attack.
+
+- compromise the user's end-to-end encryption with the destination SMP routers via an active attack.
+
+### An attacker who obtained Alice's (decrypted) chat database
+
+*can:*
+
+- see the history of all messages exchanged by Alice with her communication partners.
+
+- see shared profiles of contacts and groups.
+
+- surreptitiously receive new messages sent to Alice via existing queues; until communication queues are rotated or the Double-Ratchet advances forward.
+
+- prevent Alice from receiving all new messages sent to her - either surreptitiously by emptying the queues regularly or overtly by deleting them.
+
+- send messages from the user to their contacts; recipients will detect it as soon as the user sends the next message, because the previous message hash won't match (and potentially won't be able to decrypt them in case they don't keep the previous ratchet keys).
+
+*cannot:*
+
+- impersonate a sender and send messages to the user whose database was stolen. Doing so requires also compromising the router (to place the message in the queue, that is possible until the Double-Ratchet advances forward) or the user's device at a subsequent time (to place the message in the database).
+
+- undetectably communicate at the same time as Alice with her contacts. Doing so would result in the contact getting different messages with repeated IDs.
+
+- undetectably monitor message queues in realtime without alerting the user they are doing so, as a second subscription request unsubscribes the first and notifies the first.
+
+### A user's contact
+
+*can:*
+
+- spam the user with messages.
+
+- forever retain messages from the user.
+
+*cannot:*
+
+- cryptographically prove to a third-party that a message came from a user (assuming the user's device is not seized).
+
+- prove that two contacts they have is the same user.
+
+- cannot collaborate with another of the user's contacts to confirm they are communicating with the same user.
+
+### An attacker who observes Alice showing an introduction message to Bob
+
+*can:*
+
+- Impersonate Bob to Alice.
+
+*cannot:*
+
+- Impersonate Alice to Bob.
+
+### An attacker with Internet access
+
+*can:*
+
+- Denial of Service SimpleX messaging routers.
+
+- spam a user's public "contact queue" with connection requests.
+
+*cannot:*
+
+- send messages to a user who they are not connected with.
+
+- enumerate queues on a SimpleX router.

protocol/xftp.md

@@ -1,4 +1,4 @@
-Version 2, 2024-06-22
+Version 3, 2025-01-24
 
 # SimpleX File Transfer Protocol
 
@@ -11,12 +11,12 @@ Version 2, 2024-06-22
 - [XFTP procedure](#xftp-procedure)
 - [File description](#file-description)
 - [URIs syntax](#uris-syntax)
-  - [XFTP server URI](#xftp-server-uri)
+  - [XFTP router URI](#xftp-router-uri)
   - [File description URI](#file-description-URI)
 - [XFTP qualities and features](#xftp-qualities-and-features)
 - [Cryptographic algorithms](#cryptographic-algorithms)
-- [File chunk IDs](#file-chunk-ids)
-- [Server security requirements](#server-security-requirements)
+- [Data packet IDs](#data-packet-ids)
+- [Router security requirements](#router-security-requirements)
 - [Transport protocol](#transport-protocol)
   - [TLS ALPN](#tls-alpn)
   - [Connection handshake](#connection-handshake)
@@ -26,13 +26,14 @@ Version 2, 2024-06-22
   - [Command authentication](#command-authentication)
   - [Keep-alive command](#keep-alive-command)
   - [File sender commands](#file-sender-commands)
-    - [Register new file chunk](#register-new-file-chunk)
-    - [Add file chunk recipients](#add-file-chunk-recipients)
-    - [Upload file chunk](#upload-file-chunk)
-    - [Delete file chunk](#delete-file-chunk)
+    - [Register new data packet](#register-new-data-packet)
+    - [Add data packet recipients](#add-data-packet-recipients)
+    - [Upload data packet](#upload-data-packet)
+    - [Delete data packet](#delete-data-packet)
   - [File recipient commands](#file-recipient-commands)
-    - [Download file chunk](#download-file-chunk)
-    - [Acknowledge file chunk download](#acknowledge-file-chunk-download)
+    - [Download data packet](#download-data-packet)
+    - [Acknowledge data packet download](#acknowledge-data-packet-download)
+  - [Error responses](#error-responses)
 - [Threat model](#threat-model)
 
 ## Abstract
@@ -45,23 +46,31 @@ It is designed as a application level protocol to solve the problem of secure an
 
 ## Introduction
 
-The objective of SimpleX File Transfer Protocol (XFTP) is to facilitate the secure and private unidirectional transfer of files from senders to recipients via persistent file chunks stored by the xftp server.
+The objective of SimpleX File Transfer Protocol (XFTP) is to facilitate the secure and private unidirectional transfer of files from senders to recipients via persistent data packets stored by the xftp router.
 
 XFTP is implemented as an application level protocol on top of HTTP2 and TLS.
 
-The protocol describes the set of commands that senders and recipients can send to XFTP servers to create, upload, download and delete file chunks of several pre-defined sizes. XFTP servers SHOULD support chunks of 4 sizes: 64KB, 256KB, 1MB and 4MB (1KB = 1024 bytes, 1MB = 1024KB).
+This document describes XFTP protocol version 3. The version history:
 
-The protocol is designed with the focus on meta-data privacy and security. While using TLS, the protocol does not rely on TLS security by using additional encryption to achieve that there are no identifiers or ciphertext in common in received and sent server traffic, frustrating traffic correlation even if TLS is compromised.
+- v1: initial version
+- v2: authenticated commands - added basic auth support for commands
+- v3: blocked files - added BLOCKED error type for policy violations
 
-XFTP does not use any form of participants' identities. It relies on out-of-band passing of "file description" - a human-readable YAML document with the list of file chunk locations, hashes and necessary cryptographic keys.
+The protocol describes the set of commands that senders and recipients can send to XFTP routers to create, upload, download and delete data packets of several pre-defined sizes. XFTP routers SHOULD support packets of 4 sizes: 64KB, 256KB, 1MB and 4MB (1KB = 1024 bytes, 1MB = 1024KB).
+
+The protocol is designed with the focus on meta-data privacy and security. While using TLS, the protocol does not rely on TLS security by using additional encryption to achieve that there are no identifiers or ciphertext in common in received and sent router traffic, frustrating traffic correlation even if TLS is compromised.
+
+XFTP does not use any form of participants' identities. It relies on out-of-band passing of "file description" - a human-readable YAML document with the list of data packet locations, hashes and necessary cryptographic keys.
+
+> **Note:** While this protocol was originally designed for file transfer, it handles generic addressed data packets. File-specific semantics (splitting files into packets, assembly, naming) are application-level concerns defined in the [agent protocol](./agent-protocol.md).
 
 ## XFTP Model
 
-The XFTP model has three communication participants: the recipient, the file server (XFTP server) that is chosen and, possibly, controlled by the sender, and the sender.
+The XFTP model has three communication participants: the recipient, the XFTP router that is chosen and, possibly, controlled by the sender, and the sender.
 
-XFTP server allows uploading fixed size file chunks, with or without basic authentication. The same party that can be the sender of one file chunk can be the recipient of another, without exposing it to the server.
+XFTP router allows uploading fixed size data packets, with or without basic authentication. The same party that can be the sender of one data packet can be the recipient of another, without exposing it to the router.
 
-Each file chunk allows multiple recipients, each recipient can download the same chunk multiple times. It allows depending on the threat model use the same recipient credentials for multiple parties, thus reducing server ability to understand the number of intended recipients (but server can still track IP addresses to determine it), or use one unique set of credentials for each recipient, frustrating traffic correlation on the assumption of compromised TLS. In the latter case, senders can create a larger number of recipient credentials to hide the actual number of intended recipients from the servers (which is what SimpleX clients do).
+Each data packet allows multiple recipients, each recipient can download the same packet multiple times. It allows depending on the threat model use the same recipient credentials for multiple parties, thus reducing router ability to understand the number of intended recipients (but router can still track IP addresses to determine it), or use one unique set of credentials for each recipient, frustrating traffic correlation on the assumption of compromised TLS. In the latter case, senders can create a larger number of recipient credentials to hide the actual number of intended recipients from the routers (which is what SimpleX clients do).
 
 ```
            Sender                      Internet                XFTP relays             Internet         Recipient
@@ -69,7 +78,7 @@ Each file chunk allows multiple recipients, each recipient can download the same
                                |                       |                         |                  |
                                |                       |   (can be self-hosted)  |                  |
                                |                       |        +---------+      |                  |
-                  chunk 1     ----- HTTP2 over TLS ------       |  XFTP   |     ---- HTTP2 / TLS -----   chunk 1
+                  packet 1     ----- HTTP2 over TLS ------       |  XFTP   |     ---- HTTP2 / TLS -----   packet 1
                 |---> SimpleX File Transfer Protocol (XFTP) --> |  Relay  | --->        XFTP         ------------->|
                 |             ---------------------------       +---------+     ----------------------             |
                 |              |                       |                         |                  |              | 
@@ -83,21 +92,21 @@ file ---> |   XFTP   | ------>           XFTP            ---->  |  Relay  | --->
                 |              |                       |        +---------+      |                  |              |
                 |             ------- HTTP2 / TLS -------       |  XFTP   |     ---- HTTP2 / TLS ----              |
                 |------------->           XFTP           ---->  |  Relay  | --->        XFTP         ------------->|
-                   chunk N    ---------------------------       +---------+     ---------------------    chunk N
-                               |                       |   (store file chunks)   |                  |
+                   packet N    ---------------------------       +---------+     ---------------------    packet N
+                               |                       |   (store data packets)   |                  |
                                |                       |                         |                  |
                                |                       |                         |                  |
 ```
 
-When sender client uploads a file chunk, it has to register it first with one sender ID and multiple recipient IDs, and one random unique key per ID to authenticate sender and recipients, and also provide its size and hash that will be validated when chunk is uploaded.
+When sender client uploads a data packet, it has to register it first with one sender ID and multiple recipient IDs, and one random unique key per ID to authenticate sender and recipients, and also provide its size and hash that will be validated when packet is uploaded.
 
-To send the actual file, the sender client MUST pad it and encrypt it with a random symmetric key and distribute chunks of fixed sized across multiple XFTP servers. Information about chunk locations, keys, hashes and required keys is passed to the recipients as "[file description](#file-description)" out-of-band.
+To send the actual file, the sender client MUST pad it and encrypt it with a random symmetric key and distribute packets of fixed sized across multiple XFTP routers. Information about packet locations, keys, hashes and required keys is passed to the recipients as "[file description](#file-description)" out-of-band.
 
-Creating, uploading, downloading and deleting file chunks requires sending commands to the XFTP server - they are described in detail in [XFTP commands](#xftp-commands) section.
+Creating, uploading, downloading and deleting data packets requires sending commands to the XFTP router - they are described in detail in [XFTP commands](#xftp-commands) section.
 
 ## Persistence model
 
-Server stores file chunk records in memory, with optional adding to append-only log, to allow restoring them on server restart. File chunk bodies can be stored as files or as objects in any object store (e.g. S3).
+Router stores data packet records in memory, with optional adding to append-only log, to allow restoring them on router restart. Data packet bodies can be stored as files or as objects in any object store (e.g. S3).
 
 ## XFTP procedure
 
@@ -107,28 +116,28 @@ To send the file, the sender will:
 
 1) Prepare file
   - compute its SHA512 digest.
-  - prepend header with the name and pad the file to match the whole number of chunks in size. It is RECOMMENDED to use 2 of 4 allowed chunk sizes, to balance upload size and metadata privacy.
+  - prepend header with the name and pad the file to match the whole number of packets in size. It is RECOMMENDED to use 2 of 4 allowed packet sizes, to balance upload size and metadata privacy.
   - encrypt it with a randomly chosen symmetric key and IV (e.g., using NaCL secret_box).
-  - split into allowed size chunks.
+  - split into allowed size packets.
   - generate per-recipient keys. It is recommended that the sending client generates more per-recipient keys than the actual number of recipients, rounding up to a power of 2, to conceal the actual number of intended recipients.
 
-2) Upload file chunks
-  - register each chunk record with randomly chosen one or more (for redundancy) XFTP server(s).
+2) Upload data packets
+  - register each packet record with randomly chosen one or more (for redundancy) XFTP router(s).
   - optionally request additional recipient IDs, if required number of recipient keys didn't fit into register request.
-  - upload each chunk to chosen server(s).
+  - upload each packet to chosen router(s).
 
 3) Prepare file descriptions, one per recipient.
 
-The sending client combines addresses of all chunks and other information into "file description", different for each file recipient, that will include:
+The sending client combines addresses of all packets and other information into "file description", different for each file recipient, that will include:
 
 - an encryption key used to encrypt/decrypt the full file (the same for all recipients).
 - file SHA512 digest to validate download.
-- list of chunk descriptions; information for each chunk:
-  - private Ed25519 key to sign commands for file transfer server.
-  - chunk address (server host and chunk ID).
-  - chunk sha512 digest.
+- list of packet descriptions; information for each packet:
+  - private Ed25519 key to sign commands for file transfer router.
+  - packet address (router host and packet ID).
+  - packet sha256 digest.
 
-To reduce the size of file description, chunks are grouped by the server host.
+To reduce the size of file description, packets are grouped by the router host.
 
 4) Send file description(s) to the recipient(s) out-of-band, via pre-existing secure and authenticated channel. E.g., SimpleX clients send it as messages via SMP protocol, but it can be done via any other channel.
 
@@ -138,16 +147,16 @@ To reduce the size of file description, chunks are grouped by the server host.
 
 Having received the description, the recipient will:
 
-1) Download all chunks.
+1) Download all packets.
 
-The receiving client can fall back to secondary servers, if necessary:
-- if the server is not available.
-- if the chunk is not present on the server (ERR AUTH response).
-- if the hash of the downloaded file chunk does not match the description.
+The receiving client can fall back to secondary routers, if necessary:
+- if the router is not available.
+- if the packet is not present on the router (ERR AUTH response).
+- if the hash of the downloaded data packet does not match the description.
 
-Optionally recipient can acknowledge file chunk reception to delete file ID from server for this recipient.
+Optionally recipient can acknowledge data packet reception to delete file ID from router for this recipient.
 
-2) Combine the chunks into a file.
+2) Combine the packets into a file.
 
 3) Decrypt the file using the key in file description.
 
@@ -163,35 +172,35 @@ Optionally recipient can acknowledge file chunk reception to delete file ID from
 
 It includes these fields:
 - `party` - "sender" or "recipient". Sender's file description is required to delete the file.
-- `size` - padded file size equal to total size of all chunks, see `fileSize` syntax below.
+- `size` - padded file size equal to total size of all packets, see `fileSize` syntax below.
 - `digest` - SHA512 hash of encrypted file, base64url encoded string.
 - `key` - symmetric encryption key to decrypt the file, base64url encoded string.
 - `nonce` - nonce to decrypt the file, base64url encoded string.
-- `chunkSize` - default chunk size, see `fileSize` syntax below.
-- `replicas` - the array of file chunk replicas descriptions.
+- `chunkSize` - default packet size, see `fileSize` syntax below.
+- `replicas` - the array of data packet replicas descriptions.
 - `redirect` - optional property for redirect information indicating that the file is itself a description to another file, allowing to use file description as a short URI.
 
 Each replica description is an object with 2 fields:
 
-- `chunks` - and array of chunk replica descriptions stored on one server.
-- `server` - [server address](#xftp-server-uri) where the chunks can be downloaded from.
+- `chunks` - an array of packet replica descriptions stored on one server.
+- `server` - [router address](#xftp-router-uri) where the packets can be downloaded from.
 
-Each server replica description is a string with this syntax:
+Each router replica description is a string with this syntax:
 
 ```abnf
-chunkReplica = chunkNo ":" replicaId ":" replicaKey [":" chunkDigest [":" chunkSize]]
-chunkNo = 1*DIGIT
-  ; a sequential 1-based chunk number in the original file.
+packetReplica = packetNo ":" replicaId ":" replicaKey [":" packetDigest [":" packetSize]]
+packetNo = 1*DIGIT
+  ; a sequential 1-based packet number in the original file.
 replicaId = base64url
-  ; server-assigned random chunk replica ID.
+  ; router-assigned random packet replica ID.
 replicaKey = base64url
-  ; sender-generated random key to receive (or to delete, in case of sender's file description) the chunk replica.
-chunkDigest = base64url
-  ; chunk digest that MUST be specified for the first replica of each chunk,
+  ; sender-generated random key to receive (or to delete, in case of sender's file description) the packet replica.
+packetDigest = base64url
+  ; packet digest that MUST be specified for the first replica of each packet,
   ; and SHOULD be omitted (or be the same) on the subsequent replicas
-chunkSize = fileSize
+packetSize = fileSize
 fileSize = sizeInBytes / sizeInUnits
-  ; chunk size SHOULD only be specified on the first replica and only if it is different from default chunk size
+  ; packet size SHOULD only be specified on the first replica and only if it is different from default packet size
 sizeInBytes = 1*DIGIT
 sizeInUnits = 1*DIGIT sizeUnit
 sizeUnit = %s"kb" / %s"mb" / %s"gb"
@@ -204,28 +213,28 @@ Optional redirect information has two fields:
 
 ## URIs syntax
 
-### XFTP server URI
+### XFTP router URI
 
-The XFTP server address is a URI with the following syntax:
+The XFTP router address is a URI with the following syntax:
 
 ```abnf
-xftpServerURI = %s"xftp://" xftpServer
-xftpServer = serverIdentity [":" basicAuth] "@" srvHost [":" port]
+xftpRouterURI = %s"xftp://" xftpRouter
+xftpRouter = routerIdentity [":" basicAuth] "@" srvHost [":" port]
 srvHost = <hostname> ; RFC1123, RFC5891
 port = 1*DIGIT
-serverIdentity = base64url
+routerIdentity = base64url
 basicAuth = base64url
 ```
 
 ### File description URI
 
-This file description URI can be generated by the client application to share a small file description as a QR code or as a link. Practically, to be able to scan a QR code it should be under 1000 characters, so only file descriptions with 1-2 chunks can be used in this case. This is supported with `redirect` property when file description leads to a file which in itself is a larger file description to another file - akin to URL shortener.
+This file description URI can be generated by the client application to share a small file description as a QR code or as a link. Practically, to be able to scan a QR code it should be under 1000 characters, so only file descriptions with 1-2 packets can be used in this case. This is supported with `redirect` property when file description leads to a file which in itself is a larger file description to another file - akin to URL shortener.
 
 File description URI syntax:
 
 ```abnf
 fileDescriptionURI = serviceScheme "/file"  "#/?desc=" description [ "&data=" userData ]
-serviceScheme = (%s"https://" clientAppServer) | %s"simplex:"
+serviceScheme = (%s"https://" clientAppServer) / %s"simplex:"
 clientAppServer = hostname [ ":" port ]
 ; client app server, e.g. simplex.chat
 description = <URI-escaped YAML file description>
@@ -240,50 +249,50 @@ clientAppServer is not a server the client connects to - it is a server that sho
 
 XFTP stands for SimpleX File Transfer Protocol. Its design is based on the same ideas and has some of the qualities of SimpleX Messaging Protocol:
 
-- recipient cannot see sender's IP address, as the file fragments (chunks) are temporarily stored on multiple XFTP relays.
+- recipient cannot see sender's IP address, as the file fragments (packets) are temporarily stored on multiple XFTP relays.
 - file can be sent asynchronously, without requiring the sender to be online for file to be received.
 - there is no network of peers that can observe this transfer - sender chooses which XFTP relays to use, and can self-host their own.
-- XFTP relays do not have any file metadata - they only see individual chunks, with access to each chunk authorized with anonymous credentials (using Edwards curve cryptographic signature) that are random per chunk.
-- chunks have one of the sizes allowed by the servers - 64KB, 256KB, 1MB and 4MB chunks, so sending a large file looks indistinguishable from sending many small files to XFTP server. If the same transport connection is reused, server would only know that chunks are sent by the same user.
-- each chunk can be downloaded by multiple recipients, but each recipient uses their own key and chunk ID to authorize access, and the chunk is encrypted by a different key agreed via ephemeral DH keys (NaCl crypto_box (SalsaX20Poly1305 authenticated encryption scheme ) with shared secret derived from Curve25519 key exchange) on the way from the server to each recipient. XFTP protocol as a result has the same quality as SMP protocol - there are no identifiers and ciphertext in common between sent and received traffic inside TLS connection, so even if TLS is compromised, it complicates traffic correlation attacks.
-- XFTP protocol supports redundancy - each file chunk can be sent via multiple relays, and the recipient can choose the one that is available. Current implementation of XFTP protocol in SimpleX Chat does not support redundancy though.
+- XFTP relays do not have any file metadata - they only see individual packets, with access to each packet authorized with anonymous credentials (using Edwards curve cryptographic signature) that are random per packet.
+- packets have one of the sizes allowed by the routers - 64KB, 256KB, 1MB and 4MB packets, so sending a large file looks indistinguishable from sending many small files to XFTP router. If the same transport connection is reused, router would only know that packets are sent by the same user.
+- each packet can be downloaded by multiple recipients, but each recipient uses their own key and packet ID to authorize access, and the packet is encrypted by a different key agreed via ephemeral DH keys (NaCl crypto_box (SalsaX20Poly1305 authenticated encryption scheme ) with shared secret derived from Curve25519 key exchange) on the way from the router to each recipient. XFTP protocol as a result has the same quality as SMP protocol - there are no identifiers and ciphertext in common between sent and received traffic inside TLS connection, so even if TLS is compromised, it complicates traffic correlation attacks.
+- XFTP protocol supports redundancy - each data packet can be sent via multiple relays, and the recipient can choose the one that is available. Current implementation of XFTP protocol in SimpleX Chat does not support redundancy though.
 - the file as a whole is encrypted with a random symmetric key using NaCl secret_box.
 
 ## Cryptographic algorithms
 
 Clients must cryptographically authorize XFTP commands, see [Command authentication](#command-authentication).
 
-To authorize/verify transmissions clients and servers MUST use either signature algorithm Ed25519 algorithm defined in RFC8709 or using deniable authentication scheme based on NaCL crypto_box (see Simplex Messaging Protocol).
+To authorize/verify transmissions clients and routers MUST use either signature algorithm Ed25519 algorithm defined in RFC8709 or using deniable authentication scheme based on NaCL crypto_box (see Simplex Messaging Protocol).
 
-To encrypt/decrypt file chunk bodies delivered to the recipients, servers/clients MUST use NaCL crypto_box.
+To encrypt/decrypt data packet bodies delivered to the recipients, routers/clients MUST use NaCL crypto_box.
 
-Clients MUST encrypt file chunk bodies sent via XFTP servers using use NaCL crypto_box.
+Clients MUST encrypt data packet bodies sent via XFTP routers using use NaCL crypto_box.
 
-## File chunk IDs
+## Data packet IDs
 
-XFTP servers MUST generate a separate new set of IDs for each new chunk - for the sender (that uploads the chunk) and for each intended recipient. It is REQUIRED that:
+XFTP routers MUST generate a separate new set of IDs for each new packet - for the sender (that uploads the packet) and for each intended recipient. It is REQUIRED that:
 
-- These IDs are different and unique within the server.
+- These IDs are different and unique within the router.
 - Based on random bytes generated with cryptographically strong pseudo-random number generator.
 
-## Server security requirements
+## Router security requirements
 
-XFTP server implementations MUST NOT create, store or send to any other servers:
+XFTP router implementations MUST NOT create, store or send to any other routers:
 
 - Logs of the client commands and transport connections in the production environment.
 
 - History of retrieved files.
 
-- Snapshots of the database they use to store file chunks (instead clients can manage redundancy by creating chunk replicas using more than one XFTP server). In-memory persistence is recommended for file chunks records.
+- Snapshots of the database they use to store data packets (instead clients can manage redundancy by creating packet replicas using more than one XFTP router). In-memory persistence is recommended for data packets records.
 
-- Any other information that may compromise privacy or [forward secrecy][4] of communication between clients using XFTP servers.
+- Any other information that may compromise privacy or [forward secrecy][4] of communication between clients using XFTP routers.
 
 ## Transport protocol
 
-- binary-encoded commands sent as fixed-size padded block in the body of HTTP2 POST request, similar to SMP and notifications server protocol transmission encodings.
+- binary-encoded commands sent as fixed-size padded block in the body of HTTP2 POST request, similar to SMP and notifications router protocol transmission encodings.
 - HTTP2 POST with a fixed size padded block body for file upload and download.
 
-Block size - 4096 bytes (it would fit ~120 Ed25519 recipient keys).
+Block size - 16384 bytes (it would fit ~350 Ed25519 recipient keys).
 
 The reasons to use HTTP2:
 
@@ -299,40 +308,41 @@ The reason not to use URI segments / HTTP verbs / REST semantics is to have cons
 
 ### ALPN to agree handshake version
 
-Client and server use [ALPN extension][18] of TLS to agree handshake version.
+Client and router use [ALPN extension][18] of TLS to agree handshake version.
 
-Server SHOULD send `xftp/1` protocol name and the client should confirm this name in order to use the current protocol version. This is added to allow support of older clients without breaking backward compatibility and to extend or modify handshake syntax.
+Router SHOULD send `xftp/1` protocol name and the client should confirm this name in order to use the current protocol version. This is added to allow support of older clients without breaking backward compatibility and to extend or modify handshake syntax.
 
-If the client does not confirm this protocol name, the server would fall back to v1 of XFTP protocol.
+If the client does not confirm this protocol name, the router would fall back to v1 of XFTP protocol.
 
 ### Transport handshake
 
-When a client and a server agree on handshake version using ALPN extension, they should proceed with XFTP handshake.
+When a client and a router agree on handshake version using ALPN extension, they should proceed with XFTP handshake.
 
-As with SMP, a client doesn't reveal its version range to avoid version fingerprinting. Unlike SMP, XFTP runs a HTTP2 protocol over TLS and the server can't just send its handshake right away. So a session handshake is driven by client-sent requests:
+As with SMP, a client doesn't reveal its version range to avoid version fingerprinting. Unlike SMP, XFTP runs a HTTP2 protocol over TLS and the router can't just send its handshake right away. So a session handshake is driven by client-sent requests:
 
-1. To pass initiative to the server, the client sends a request with empty body.
-2. Server responds with its `paddedServerHello` block.
+1. To pass initiative to the router, the client sends a request with empty body.
+2. Router responds with its `paddedRouterHello` block.
 3. Clients sends a request containing `paddedClientHello` block,
-4. Server sends an empty response, finalizing the handshake.
+4. Router sends an empty response, finalizing the handshake.
 
-Once TLS handshake is complete, client and server will exchange blocks of fixed size (16384 bytes).
+Once TLS handshake is complete, client and router will exchange blocks of fixed size (16384 bytes).
 
 ```abnf
-paddedServerHello = <padded(serverHello, 16384)>
-serverHello = xftpVersionRange sessionIdentifier serverCert signedServerKey ignoredPart
+paddedRouterHello = <padded(routerHello, 16384)>
+routerHello = xftpVersionRange sessionIdentifier routerCerts signedRouterKey ignoredPart
 xftpVersionRange = minXftpVersion maxXftpVersion
 minXftpVersion = xftpVersion
 maxXftpVersion = xftpVersion
 sessionIdentifier = shortString
 ; unique session identifier derived from transport connection handshake
-serverCert = originalLength <x509encoded>
-signedServerKey = originalLength <x509encoded> ; signed by server certificate
+routerCerts = length 1*routerCert ; NonEmpty list of certificates in chain
+routerCert = originalLength <x509encoded>
+signedRouterKey = originalLength <x509encoded> ; signed by router certificate
 
 paddedClientHello = <padded(clientHello, 16384)>
 clientHello = xftpVersion keyHash ignoredPart
 ; chosen XFTP protocol version - must be the maximum supported version
-; within the range offered by the server
+; within the range offered by the router
 
 xftpVersion = 2*2OCTET ; Word16 version number
 keyHash = shortString
@@ -342,47 +352,47 @@ originalLength = 2*2OCTET
 ignoredPart = *OCTET
 ```
 
-In XFTP v2 the handshake is only used for version negotiation, but `serverCert` and `signedServerKey` must be validated by the client.
+In XFTP v2 the handshake is only used for version negotiation, but `routerCert` and `signedRouterKey` must be validated by the client.
 
-`keyHash` is the CA fingerprint used by client to validate TLS certificate chain and is checked by a server against its own key.
+`keyHash` is the CA fingerprint used by client to validate TLS certificate chain and is checked by a router against its own key.
 
-`ignoredPart` in handshake allows to add additional parameters in handshake without changing protocol version - the client and servers must ignore any extra bytes within the original block length.
+`ignoredPart` in handshake allows to add additional parameters in handshake without changing protocol version - the client and routers must ignore any extra bytes within the original block length.
 
-For TLS transport client should assert that `sessionIdentifier` is equal to `tls-unique` channel binding defined in [RFC 5929][14] (TLS Finished message struct); we pass it in `serverHello` block to allow communication over some other transport protocol (possibly, with another channel binding).
+For TLS transport client should assert that `sessionIdentifier` is equal to `tls-unique` channel binding defined in [RFC 5929][14] (TLS Finished message struct); we pass it in `routerHello` block to allow communication over some other transport protocol (possibly, with another channel binding).
 
 ### Requests and responses
 
 - File sender:
-  - create file chunk record.
+  - create data packet record.
     - Parameters:
       - Ed25519 key for subsequent sender commands and Ed25519 keys for commands of each recipient.
-      - chunk size.
+      - packet size.
     - Response:
-      - chunk ID for the sender and different IDs for all recipients.
-  - add recipients to file chunk
+      - packet ID for the sender and different IDs for all recipients.
+  - add recipients to data packet
     - Parameters:
-      - sender's chunk ID
+      - sender's packet ID
       - Ed25519 keys for commands of each recipient.
     - Response:
-      - chunk IDs for new recipients.
-  - upload file chunk.
-  - delete file chunk (invalidates all recipient IDs).
+      - packet IDs for new recipients.
+  - upload data packet.
+  - delete data packet (invalidates all recipient IDs).
 - File recipient:
-  - download file chunk:
-    - chunk ID
-    - DH key for additional encryption of the chunk.
-    - command should be signed with the key passed by the sender when creating chunk record.
-  - delete file chunk ID (only for one recipient): signed with the same key.
+  - download data packet:
+    - packet ID
+    - DH key for additional encryption of the packet.
+    - command should be signed with the key passed by the sender when creating packet record.
+  - delete data packet ID (only for one recipient): signed with the same key.
 
 ## XFTP commands
 
 Commands syntax below is provided using ABNF with case-sensitive strings extension.
 
 ```abnf
-xftpCommand = ping / senderCommand / recipientCmd / serverMsg
+xftpCommand = ping / senderCommand / recipientCmd / routerMsg
 senderCommand = register / add / put / delete
 recipientCmd = get / ack
-serverMsg = pong / sndIds / rcvIds / ok / file
+routerMsg = pong / sndIds / rcvIds / ok / file / error
 ```
 
 The syntax of specific commands and responses is defined below.
@@ -393,11 +403,11 @@ Commands are made via HTTP2 requests, responses to commands are correlated as HT
 
 ### Command authentication
 
-XFTP servers must authenticate all transmissions (excluding `ping`) by verifying the client signatures. Command signature should be generated by applying the algorithm specified for the file to the `signed` block of the transmission, using the key associated with the file chunk ID (recipient's or sender's depending on which file chunk ID is used).
+XFTP routers must authenticate all transmissions (excluding `ping`) by verifying the client signatures. Command signature should be generated by applying the algorithm specified for the file to the `signed` block of the transmission, using the key associated with the data packet ID (recipient's or sender's depending on which data packet ID is used).
 
 ### Keep-alive command
 
-To keep the transport connection alive and to generate noise traffic the clients should use `ping` command to which the server responds with `pong` response. This command should be sent unsigned and without file chunk ID.
+To keep the transport connection alive and to generate noise traffic the clients should use `ping` command to which the router responds with `pong` response. This command should be sent unsigned and without data packet ID.
 
 ```abnf
 ping = %s"PING"
@@ -405,21 +415,19 @@ ping = %s"PING"
 
 This command is always sent unsigned.
 
-  data FileResponse = ... | FRPong | ...
-
 ```abnf
 pong = %s"PONG"
 ```
 
 ### File sender commands
 
-Sending any of the commands in this section (other than `register`, that is sent without file chunk ID) is only allowed with sender's ID.
+Sending any of the commands in this section (other than `register`, that is sent without data packet ID) is only allowed with sender's ID. The `register` command must be signed (using `sndKey` included in `fileInfo` for verification) but must NOT include a data packet ID.
 
-#### Register new file chunk
+#### Register new data packet
 
-This command is sent by the sender to the XFTP server to register a new file chunk.
+This command is sent by the sender to the XFTP router to register a new data packet.
 
-Servers SHOULD support basic auth with this command, to allow only server owners and trusted users to create file chunks on the servers.
+Routers SHOULD support basic auth with this command, to allow only router owners and trusted users to create data packets on the routers.
 
 The syntax is:
 
@@ -427,7 +435,7 @@ The syntax is:
 register = %s"FNEW " fileInfo rcvPublicAuthKeys basicAuth
 fileInfo = sndKey size digest
 sndKey = length x509encoded
-size = 1*DIGIT
+size = 4*4 OCTET ; Word32 big-endian
 digest = length *OCTET
 rcvPublicAuthKeys = length 1*rcvPublicAuthKey
 rcvPublicAuthKey = length x509encoded
@@ -438,7 +446,7 @@ x509encoded = <binary X509 key encoding>
 length = 1*1 OCTET
 ```
 
-If the file chunk is registered successfully, the server must send `sndIds` response with the sender's and recipients' file chunk IDs:
+If the data packet is registered successfully, the router must send `sndIds` response with the sender's and recipients' data packet IDs:
 
 ```abnf
 sndIds = %s"SIDS " senderId recipientIds
@@ -447,9 +455,9 @@ recipientIds = length 1*recipientId
 recipientId = length *OCTET
 ```
 
-#### Add file chunk recipients
+#### Add data packet recipients
 
-This command is sent by the sender to the XFTP server to add additional recipient keys to the file chunk record, in case number of keys requested by client didn't fit into `register` command. The syntax is:
+This command is sent by the sender to the XFTP router to add additional recipient keys to the data packet record, in case number of keys requested by client didn't fit into `register` command. The syntax is:
 
 ```abnf
 add = %s"FADD " rcvPublicAuthKeys
@@ -457,7 +465,7 @@ rcvPublicAuthKeys = length 1*rcvPublicAuthKey
 rcvPublicAuthKey = length x509encoded
 ```
 
-If additional keys were added successfully, the server must send `rcvIds` response with the added recipients' file chunk IDs:
+If additional keys were added successfully, the router must send `rcvIds` response with the added recipients' data packet IDs:
 
 ```abnf
 rcvIds = %s"RIDS " recipientIds
@@ -465,66 +473,100 @@ recipientIds = length 1*recipientId
 recipientId = length *OCTET
 ```
 
-#### Upload file chunk
+#### Upload data packet
 
-This command is sent by the sender to the XFTP server to upload file chunk body to server. The syntax is:
+This command is sent by the sender to the XFTP router to upload data packet body to router. The syntax is:
 
 ```abnf
 put = %s"FPUT"
 ```
 
-Chunk body is streamed via HTTP2 request.
+Packet body is streamed via HTTP2 request.
 
-If file chunk body was successfully received, the server must send `ok` response.
+If data packet body was successfully received, the router must send `ok` response.
 
 ```abnf
 ok = %s"OK"
 ```
 
-#### Delete file chunk
+#### Delete data packet
 
-This command is sent by the sender to the XFTP server to delete file chunk from the server. The syntax is:
+This command is sent by the sender to the XFTP router to delete data packet from the router. The syntax is:
 
 ```abnf
 delete = %s"FDEL"
 ```
 
-Server should delete file chunk record, invalidating all recipient IDs, and delete file body from file storage. If file chunk was successfully deleted, the server must send `ok` response.
+Router should delete data packet record, invalidating all recipient IDs, and delete file body from file storage. If data packet was successfully deleted, the router must send `ok` response.
 
 ### File recipient commands
 
 Sending any of the commands in this section is only allowed with recipient's ID.
 
-#### Download file chunk
+#### Download data packet
 
-This command is sent by the recipient to the XFTP server to download file chunk body from the server. The syntax is:
+This command is sent by the recipient to the XFTP router to download data packet body from the router. The syntax is:
 
 ```abnf
 get = %s"FGET " rDhKey
 rDhKey = length x509encoded
 ```
 
-If requested file is successfully located, the server must send `file` response. File chunk body is sent as HTTP2 response body.
+If requested file is successfully located, the router must send `file` response. Data packet body is sent as HTTP2 response body.
 
 ```abnf
 file = %s"FILE " sDhKey cbNonce
 sDhKey = length x509encoded
-cbNonce = <nonce used in NaCl crypto_box encryption scheme>
+cbNonce = 24*24 OCTET ; NaCl crypto_box nonce
 ```
 
-Chunk is additionally encrypted on the way from the server to the recipient using a key agreed via ephemeral DH keys `rDhKey` and `sDhKey`, so there is no ciphertext in common between sent and received traffic inside TLS connection, in order to complicate traffic correlation attacks, if TLS is compromised.
+Packet is additionally encrypted on the way from the router to the recipient using a key agreed via ephemeral DH keys `rDhKey` and `sDhKey`, so there is no ciphertext in common between sent and received traffic inside TLS connection, in order to complicate traffic correlation attacks, if TLS is compromised.
 
-#### Acknowledge file chunk download
+#### Acknowledge data packet download
 
-This command is sent by the recipient to the XFTP server to acknowledge file reception, deleting file ID from server for this recipient. The syntax is:
+This command is sent by the recipient to the XFTP router to acknowledge file reception, deleting file ID from router for this recipient. The syntax is:
 
 ```abnf
 ack = %s"FACK"
 ```
 
-If file recipient ID is successfully deleted, the server must send `ok` response.
+If file recipient ID is successfully deleted, the router must send `ok` response.
 
-In current implementation of XFTP protocol in SimpleX Chat clients don't use FACK command. Files are automatically expired on servers after configured time interval.
+In current implementation of XFTP protocol in SimpleX Chat clients don't use FACK command. Files are automatically expired on routers after configured time interval.
+
+### Error responses
+
+The router responds with `ERR` followed by the error type:
+
+```abnf
+error = %s"ERR " errorType
+errorType = %s"BLOCK" / %s"SESSION" / %s"HANDSHAKE" /
+            %s"CMD" SP cmdError / %s"AUTH" / %s"BLOCKED" SP blockingInfo /
+            %s"SIZE" / %s"QUOTA" / %s"DIGEST" / %s"CRYPTO" /
+            %s"NO_FILE" / %s"HAS_FILE" / %s"FILE_IO" /
+            %s"TIMEOUT" / %s"INTERNAL"
+cmdError = %s"UNKNOWN" / %s"SYNTAX" / %s"PROHIBITED" / %s"NO_AUTH" / %s"HAS_AUTH" / %s"NO_ENTITY"
+blockingInfo = %s"reason=" blockingReason ["," %s"notice=" jsonNotice]
+blockingReason = %s"spam" / %s"content"
+jsonNotice = *OCTET ; JSON-encoded notice object
+```
+
+Error types:
+- `BLOCK` - incorrect block format, encoding or signature size.
+- `SESSION` - incorrect session ID (TLS Finished message / tls-unique binding).
+- `HANDSHAKE` - incorrect handshake command.
+- `CMD` - command syntax errors (UNKNOWN, SYNTAX, PROHIBITED, NO_AUTH, HAS_AUTH, NO_ENTITY).
+- `AUTH` - command authorization error - bad signature or non-existing data packet.
+- `BLOCKED` - data packet was blocked due to policy violation (added in v3). Contains blocking reason and optional notice.
+- `SIZE` - incorrect file size.
+- `QUOTA` - storage quota exceeded.
+- `DIGEST` - incorrect file digest.
+- `CRYPTO` - file encryption/decryption failed.
+- `NO_FILE` - no expected file body in request/response or no file on the router.
+- `HAS_FILE` - unexpected file body.
+- `FILE_IO` - file IO error.
+- `TIMEOUT` - file sending or receiving timeout.
+- `INTERNAL` - internal router error.
 
 ## Threat model
 
@@ -533,7 +575,7 @@ In current implementation of XFTP protocol in SimpleX Chat clients don't use FAC
  - A user protects their local database and key material.
  - The user's application is authentic, and no local malware is running.
  - The cryptographic primitives in use are not broken.
- - A user's choice of servers is not directly tied to their identity or otherwise represents distinguishing information about the user.
+ - A user's choice of routers is not directly tied to their identity or otherwise represents distinguishing information about the user.
 
 #### A passive adversary able to monitor the traffic of one user
 
@@ -541,7 +583,7 @@ In current implementation of XFTP protocol in SimpleX Chat clients don't use FAC
 
  - identify that and when a user is sending files over XFTP protocol.
 
- - determine which servers the user sends/receives files to/from.
+ - determine which routers the user sends/receives files to/from.
 
  - observe how much traffic is being sent, and make guesses as to its purpose.
 
@@ -553,43 +595,45 @@ In current implementation of XFTP protocol in SimpleX Chat clients don't use FAC
 
  *can:*
 
- - learn which XFTP servers are used to send and receive files for which users.
+ - learn which XFTP routers are used to send and receive files for which users.
 
  - learn when files are sent and received.
 
- - perform traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the servers.
+ - perform traffic correlation attacks against senders and recipients and correlate senders and recipients within the monitored set, frustrated by the number of users on the routers.
 
- - observe how much traffic is being sent, and make guesses as to its purpose
+ - observe how much traffic is being sent, and make guesses as to its purpose.
 
-*cannot, even in case of a compromised transport protocol:*
+ - in case of a compromised transport protocol, correlate file senders and receivers.
 
- - perform traffic correlation attacks with any increase in efficiency over a non-compromised transport protocol
+*cannot, in case of a non-compromised transport protocol:*
 
-#### XFTP server
+ - perform traffic correlation attacks.
+
+#### XFTP router
 
 *can:*
 
 - learn when file senders and recipients are online.
 
-- know how many file chunks and chunk sizes are sent via the server.
+- know how many data packets and packet sizes are sent via the router.
 
-- perform the correlation of the file chunks as belonging to one file via either a re-used transport connection, user's IP address, or connection timing regularities.
+- perform the correlation of the data packets as belonging to one file via either a re-used transport connection, user's IP address, or connection timing regularities.
 
 - learn file senders' and recipients' IP addresses, and infer information (e.g. employer) based on the IP addresses, as long as Tor is not used.
 
-- delete file chunks, preventing file delivery, as long as redundant delivery is not used.
+- delete data packets, preventing file delivery, as long as redundant delivery is not used.
 
-- lie about the state of a file chunk to the recipient and/or to the sender  (e.g. deleted when it is not).
+- lie about the state of a data packet to the recipient and/or to the sender  (e.g. deleted when it is not).
 
 - refuse deleting the file when instructed by the sender.
 
 *cannot:*
 
-- undetectably corrupt file chunks.
+- undetectably corrupt data packets.
 
 - learn the contents, name or the exact size of sent files.
 
-- learn approximate size of sent files, as long as more than one server is used to send file chunks.
+- learn approximate size of sent files, as long as more than one router is used to send data packets.
 
 - compromise the users' end-to-end encryption of files with an active attack.
 
@@ -601,7 +645,7 @@ In current implementation of XFTP protocol in SimpleX Chat clients don't use FAC
 
 - receive all files sent and received by Alice that did not expire yet, as long as information about these files was not removed from the database.
 
-- prevent Alice's contacts from receiving the files she sent by deleting all or some of the file chunks from XFTP servers.
+- prevent Alice's contacts from receiving the files she sent by deleting all or some of the data packets from XFTP routers.
 
 #### A user's contact
 
@@ -623,10 +667,10 @@ In current implementation of XFTP protocol in SimpleX Chat clients don't use FAC
 
 *can:*
 
-- Denial of Service XFTP servers.
+- Denial of Service XFTP routers.
 
 *cannot:*
 
 - send files to a user who they are not connected with.
 
-- enumerate file chunks on an XFTP server.
+- enumerate data packets on an XFTP router.

protocol/xrcp.md

@@ -10,7 +10,7 @@ Version 1, 2024-06-22
   - [Session invitation](#session-invitation)
   - [Establishing TLS connection](#establishing-tls-connection)
   - [Session verification and protocol negotiation](#session-verification-and-protocol-negotiation)
-  - [Controller/host session operation](#сontrollerhost-session-operation)
+  - [Controller/host session operation](#controllerhost-session-operation)
 - [Key agreement for announcement packet and for session](#key-agreement-for-announcement-packet-and-for-session)
 - [Threat model](#threat-model)
 
@@ -67,7 +67,7 @@ The session invitation contains this data:
 - CA TLS certificate fingerprint of the controller - this is part of long term identity of the controller established during the first session, and repeated in the subsequent session announcements.
 - Session Ed25519 public key used to verify the announcement and commands - this mitigates the compromise of the long term signature key, as the controller will have to sign each command with this key first.
 - Long-term Ed25519 public key used to verify the announcement and commands - this is part of the long term controller identity.
-- Session X25519 DH key and SNTRUP761 KEM encapsulation key to agree session encryption (both for multicast announcement and for commands and responses in TLS), as described in https://datatracker.ietf.org/doc/draft-josefsson-ntruprime-hybrid/. The new keys are used for each session, and if client key is already available (from the previous session), the computed shared secret will be used to encrypt the announcement multicast packet. The out-of-band invitation is unencrypted. DH public key and KEM encapsulation key are sent unencrypted. NaCL crypto_box is used for encryption.
+- Session X25519 DH key to agree session encryption (both for multicast announcement and for commands and responses in TLS), as described in https://datatracker.ietf.org/doc/draft-josefsson-ntruprime-hybrid/. The new keys are used for each session, and if client key is already available (from the previous session), the computed shared secret will be used to encrypt the announcement multicast packet. The out-of-band invitation is unencrypted. DH public key and KEM encapsulation key are sent unencrypted. NaCL crypto_box is used for encryption.
 
 Host application decrypts (except the first session) and validates the invitation:
 - Session signature is valid.
@@ -104,12 +104,11 @@ Multicast session announcement is a binary encoded packet with this syntax:
 ```abnf
 sessionAddressPacket = dhPubKey nonce encrypted(unpaddedSize sessionAddress packetPad)
 dhPubKey = length x509encoded ; same as announced
-nonce = length *OCTET
-sessionAddress = largeLength sessionAddressUri ; as above
+nonce = 24*24 OCTET ; NaCl 192-bit nonce, no length prefix
+sessionAddress = sessionAddressUri ; length given by unpaddedSize
 length = 1*1 OCTET ; for binary data up to 255 bytes
 largeLength = 2*2 OCTET ; for binary data up to 65535 bytes
-packetPad = <pad packet size to 1450 bytes> ; possibly, we may need to move KEM agreement one step later,
-; with encapsulation key in HELLO block and KEM ciphertext in reply to HELLO.
+packetPad = <pad invitation content to 900 bytes before encryption>
 ```
 
 ### Establishing TLS connection
@@ -143,7 +142,7 @@ hostHello = %s"HELLO " dhPubKey nonce encrypted(unpaddedSize hostHelloJSON hello
 unpaddedSize = largeLength
 dhPubKey = length x509encoded
 pad = <pad block size to 16384 bytes>
-helloPad = <pad hello size to 12888 bytes>
+helloPad = <pad hello size to 12288 bytes>
 largeLength = 2*2 OCTET
 ```
 
@@ -157,10 +156,7 @@ The controller decrypts (including the first session) and validates the received
 {
   "definitions": {
     "version": {
-      "type": "string",
-      "metadata": {
-        "format": "[0-9]+"
-      }
+      "type": "uint16"
     },
     "base64url": {
       "type": "string",
@@ -172,9 +168,7 @@ The controller decrypts (including the first session) and validates the received
   "properties": {
     "v": {"ref": "version"},
     "ca": {"ref": "base64url"},
-    "kem": {"ref": "base64url"}
-  },
-  "optionalProperties": {
+    "kem": {"ref": "base64url"},
     "app": {"properties": {}, "additionalProperties": true}
   },
   "additionalProperties": true
@@ -184,13 +178,13 @@ The controller decrypts (including the first session) and validates the received
 The controller should reply with with `ctrlHello` or `ctrlError` response:
 
 ```abnf
-ctrlHello = %s"HELLO " kemCiphertext nonce encrypted(unpaddedSize ctrlHelloJSON helloPad) pad
+ctrlHello = %s"HELLO " kemCiphertext encrypted(unpaddedSize ctrlHelloJSON helloPad) pad
 ; ctrlHelloJSON is encrypted with the hybrid secret,
 ; including both previously agreed DH secret and KEM secret from kemCiphertext
 unpaddedSize = largeLength
 kemCiphertext = largeLength *OCTET
 pad = <pad block size to 16384 bytes>
-helloPad = <pad hello size to 12888 bytes>
+helloPad = <pad hello size to 12288 bytes>
 largeLength = 2*2 OCTET
 
 ctrlError = %s"ERROR " nonce encrypted(unpaddedSize ctrlErrorMessage helloPad) pad
@@ -206,6 +200,8 @@ JTD schema for the encrypted part of controller HELLO block `ctrlHelloJSON`:
 }
 ```
 
+Controller `hello` block and all subsequent protocol messages are encrypted with the chain keys derived from the hybrid key (see key exchange below) - that is why controller hello block does not include nonce. That provides forward secrecy within the XRCP session. Receiving this `hello` block allows host to compute the same hybrid keys and to derive the same chain keys.
+
 Once the controller replies HELLO to the valid host HELLO block, it should stop accepting new TCP connections.
 
 ### Controller/host session operation
@@ -223,10 +219,12 @@ tlsunique channel binding from TLS session MUST be included in commands (include
 The syntax for encrypted command and response body encoding:
 
 ```abnf
-commandBody = encBody sessSignature idSignature [attachment]
-responseBody = encBody [attachment] ; counter must match command
-encBody = nonce encLength32 encrypted(tlsunique counter body)
-attachment = %x01 nonce encLength32 encrypted(attachment)
+commandBody = counter encBody sessSignature idSignature [attachment]
+responseBody = counter encBody [attachment] ; counter must match command
+; counter is placed outside of encrypted body to allow correlating encryption keys
+; with the chain keys (each command and response are encrypted by different keys)
+encBody = encLength32 encrypted(tlsunique body)
+attachment = %x01 encLength32 encrypted(attachment)
 noAttachment = %x00
 tlsunique = length 1*OCTET
 counter = 8*8 OCTET ; int64
@@ -239,7 +237,7 @@ If the command or response includes attachment, its hash must be included in com
 
 Initial announcement is shared out-of-band (URI with xrcp scheme), and it is not encrypted.
 
-This announcement contains only DH keys, as KEM key is too large to include in QR code, which are used to agree encryption key for host HELLO block. The host HELLO block will contain DH key in plaintext part and KEM encapsulation (public) key in encrypted part, that will be used to determine the shared secret (using SHA256 over concatenated DH shared secret and KEM encapsulated secret) both for controller HELLO response (that contains KEM ciphertext in plaintext part) and subsequent session commands and responses.
+This announcement contains only DH keys, as KEM key is too large to include in QR code, which are used to agree encryption key for host HELLO block. The host HELLO block will contain DH key in plaintext part and KEM encapsulation (public) key in encrypted part, that will be used to determine the shared secret (using SHA3-256 over concatenated DH shared secret and KEM encapsulated secret) to derive keys for controller HELLO response (that contains KEM ciphertext in plaintext part) and subsequent session commands and responses.
 
 During the next session the announcement is sent via encrypted multicast block. The shared key for this announcement and for host HELLO block is determined using the KEM shared secret from the previous session and DH shared secret computed using the host DH key from the previous session and the new controller DH key from the announcement.
 
@@ -250,19 +248,19 @@ In pseudo-code:
 ```
 // session 1
 hostHelloSecret(1) = dhSecret(1)
-sessionSecret(1) = sha256(dhSecret(1) || kemSecret(1)) // to encrypt session 1 data, incl. controller hello
+sessionSecret(1) = sha3-256(dhSecret(1) || kemSecret(1)) // to encrypt session 1 data, incl. controller hello
 dhSecret(1) = dh(hostHelloDhKey(1), controllerInvitationDhKey(1))
 kemCiphertext(1) = enc(kemSecret(1), kemEncKey(1))
 // kemEncKey is included in host HELLO, kemCiphertext - in controller HELLO
 kemSecret(1) = dec(kemCiphertext(1), kemDecKey(1))
 
 // multicast announcement for session n
-announcementSecret(n) = sha256(dhSecret(n'))
+announcementSecret(n) = dhSecret(n')
 dhSecret(n') = dh(hostHelloDhKey(n - 1), controllerDhKey(n))
 
 // session n
 hostHelloSecret(n) = dhSecret(n)
-sessionSecret(n) = sha256(dhSecret(n) || kemSecret(n)) // to encrypt session n data, incl. controller hello
+sessionSecret(n) = sha3-256(dhSecret(n) || kemSecret(n)) // to encrypt session n data, incl. controller hello
 dhSecret(n) = dh(hostHelloDhKey(n), controllerDhKey(n))
 // controllerDhKey(n) is either from invitation or from multicast announcement
 kemCiphertext(n) = enc(kemSecret(n), kemEncKey(n))
@@ -273,6 +271,22 @@ If controller fails to store the new host DH key after receiving HELLO block, th
 
 To decrypt a multicast announcement, the host should try to decrypt it using the keys of all known (paired) remote controllers.
 
+Once sessionSecret is agreed for the session, it is used to derive two chain keys, to receive and to send messages:
+
+```
+controller: sndKey, rcvKey = HKDF(sessionSecret, "SimpleXSbChainInit", 64)
+host: rcvKey, sndKey = HKDF(sessionSecret, "SimpleXSbChainInit", 64)
+```
+
+where HKDF is based on SHA512, with empty salt.
+
+Actual keys and nonces to encrypt and decrypt messages are derived from these chain keys:
+
+```
+to send: (sndKey', sk, nonce) = HKDF(sndKey, "SimpleXSbChain", 88)
+to receive: (rcvKey', sk, nonce) = HKDF(rcvKey, "SimpleXSbChain", 88)
+```
+
 ## Threat model
 
 #### A passive network adversary able to monitor the site-local traffic:

rfcs/2022-04-20-smp-conf-timeout-recovery.md

@@ -3,9 +3,9 @@
 ## Problem
 
 When sending an SMP confirmation a network timeout can lead to the following race condition:
-- server receives the confirmation while the joining party fails to receive the server's response;
+- router receives the confirmation while the joining party fails to receive the router's response;
 - joining party deletes the connection together with credentials sent in the confirmation for securing the queue;
-- initiating party will receive the confirmation from the server and secure the queue;
+- initiating party will receive the confirmation from the router and secure the queue;
 - on subsequent attempt to join via the same invitation link initiating party will generate new credentials and fail authorization.
 
 This renders the joining party permanently unable to join via that invitation link and complete the connection.

rfcs/2024-07-06-ios-notifications.md

@@ -0,0 +1,18 @@
+# iOS notifications stability
+
+## Problem
+
+iOS notifications may fail to deliver for several reasons, but there are two important reasons that we could address:
+- when notification router is not subscribed to SMP router(s), the notifications can be dropped - it can happen because either notification router restarts or becuase SMP router restarted and some messages are received before notification router resubscribed. We lose approximately 3% of notifications because of this reason.
+- when user device is offline or has low power condition, Apple does not deliver notification, but puts them to storage. If while the notification is in storage a new one arrives it would overwrite the previous notification. If it was the message to the same message queue, the client will download messages anyway, up to a limit, but if the message was to another queue, it will not be delivered until the app is opened. Apple delivers about 88% of notifications that should be delivered (not accounting for uninstalled apps), the rest is replaced with the newer notifications.
+
+## Solution
+
+The first problem can be solved by preserving notifications for a limited time (say 1 hour) in case there is no subscription to notification from notification router. At the very least, they can be preserved in SMP router memory but can also be stored to a file on restart, similar to messages, and be delivered when notification router resubscribes. It is sufficient to store one notification per messaging queue.
+
+The second problem is both more damaging and more complex to solve. The solution could be to always deliver several last notifications to different queues in one packet (Apple allows up to ~4-5kb notification size, and we are sending packets of fixed size 512 bytes, so we could fit up to 8-10 of them in each notification).
+
+Every time a client receives such batch of notifications if can:
+- check if that notification was already received in the previous batch.
+- if it was received, it would be ignored, otherwise it would be processed.
+- process them one by one, started from the most recent one while the time allows.

rfcs/2024-09-05-queue-storage.md

@@ -0,0 +1,81 @@
+# Storage considerations for SMP queues
+
+See [Short invitation links](./2024-06-21-short-links.md).
+
+## Problem
+
+1) queue records are created permanently, until the clients delete them.
+
+2) clients only delete queue records based on some user action, pending connections do not expire.
+
+While part 2 should be improved in the client, indefinite storage of queue records becomes a much bigger issue if each of them would result in a permanent storage of 4-16kb blob in router memory, without router-side expiration for short invitation links.
+
+## Possible solutions
+
+1) Add some queue timestamp, e.g. queue creation date, to expire unsecured queues after say 3 weeks.
+
+The problem with this approach is that contact addresses are also unsecured queues, and they should not be expired.
+
+We could set really large expiration time, and require that clients "update" the unsecured queues they need at least every 1-2 years, but it would not solve the problem of storing a large number of blobs in the router memory for unused/abandoned 1-time invitations.
+
+2) Do not store blobs in memory / append-only log, and instead use something like RocksDB. While it may be a correct long term solution, it may be not expedient enough at the current POC stage for this feature. Also, the lack of expiration is wrong in any case and would indefinitely grow router storage.
+
+3) Add flag allowing the router to differentiate permanent queues used as contact addresses, also using different blob sizes for them. In this case, messaging queues will be expired if not secured after 3 weeks, and contact address queues would be expired if not "updated" by the owner within 2 years.
+
+Probably all three solutions need to be used, to avoid creating a non-expiring blob storage in memory, as in case too many of such blobs are created it would not be possible to differentiate between real users and resource exhaustion attacks, and unlike with messages, they won't be expiring too.
+
+Routers already can differentiate messaging queues and contact address queues, if they want to:
+- with the old 4-message handshake, the confirmation message on a normal queue was different, and also KEY command was eventually used.
+- with the fast 2-message handshake, while the confirmation message has the same syntax, and the differences are inside encrypted envelope, the client still uses SKEY command.
+- in both cases, the usual messaging queues are secured, and contact addresses are not, so this difference is visible in the storage as well (although it is not easy to differentiate between abandoned 1-time invitations and contact addresses).
+
+Differentiating these queues can also allow different message retention times - e.g., the queues for contact addresses could have bigger size, but have lower message retention time.
+
+## Proposed solution
+
+1. Add queue updated_at date into queue records. While it adds some metadata, it seems necessary to manage retention and quality of service. It will not include exact time, only date, and the time of creation will be replaced by the time of any update - queue secured, a message is sent, or queue owner subscribes to the queue. To avoid the need to update store log on every message this information can be appended to store log on router termination. Or given that only one update per day is needed it may be ok to make these updates as they happen (temporarily making the sequence and time of these events available in storage).
+
+2. Add flag to indicate the queue usage - messaging queue or queue for contact address connection requests. This would result in different queue size and different retention policy for queue and its messages. We already have "sender can secure flag" which is, effectively, this flag - contact address queues are never secured. So this does not increase stored metadata in any way.
+
+## Possible changes to short links
+
+This is a design considerations and a concept, not a design yet.
+
+Instead of implementing a generic blob storage that can be used as an attack vector, and adds additional failure point (another router storing blob that is necessary to connect to the queue on the current router), but instead adds an extended queue information blobs, most of which could be dropped without the loss of connectivity, so that the attack can be mitigated by deleting these blobs without users losing the ability to connect, as long as the queue and minimal extended information is retained.
+
+So, to make the connection there need to be these elements:
+
+- queue router and queue ID - mandatory part, that can be included in short link
+- SMP key - mandatory part for all queues. We are considering initializing ratchets earlier for contact addresses, and include ratchet keys and pre-keys into queue data as well, but it is out of scope here.
+- Ratchet keys - mandatory part for 1-time invitation that won't fit in short link.
+- PQ key - optional part that can be stored with addresses if ratchet keys are added and with 1-time invitations.
+- App blobs - chat preferences for 1-time invitation links and profile information for contact addresses.
+
+So rather that storing one blob with a large address inside it, not associated with the queue, increasing probability of failure and reducing our ability to mitigate resource exhaustion, we could store extended blobs associated with the queues.
+
+Also, we need the address shared with the sender (party accepting the connection) to be short. We could use a similar approach that was proposed for data blobs, using a single random seed per queues to derive multiple keys and IDs from it. For example:
+
+1. The queue owner:
+  - generates Ed25529 key pair `(sk, spk)` and X25519 key pair `(dhk, dhpk)` to use with the router, same as now sent in NEW command.
+  - generates queue recipient ID (this ID can still be router-generated).
+  - generates X25519 key pair `(k, pk)` to use with the accepting party.
+  - derives from `k`:
+    - sender ID.
+    - symmetric key for authenticated encryption of blobs.
+  - `k` will be used as short link.
+2. All other data from the invitation can be included in queue creation request and be associated with the queue as 1-3 blobs with different priority:
+  - ratchet keys - it will have a small size, so only this blob cannot be removed, while other blobs can be removed in case of resource exhaustion.
+  - PQ keys - optional blob.
+  - conversation preferences and profile - can be removed depending on creation time, e.g. all new blobs can be removed.
+
+The algorithm used to derive key and ID from `k` needs to be cryptographically secure, e.g. it could be some KDF or ChaCha DRG initialized with `k` as seed, TBC.
+
+So, coupling blob storage with messaging queues has these pros/cons:
+
+Cons:
+- no additional layer of privacy - the router used for connection is visible in the link, even after the blobs are removed from the router.
+
+Pros:
+- no additional point of failure in the connection process - the same router will be used to retrieve necessary blobs as for connection.
+- queue blobs of messaging blobs will be automatically removed once the queue is secured or expired, without additional request from the recipient - reducing the storage and the time these blobs are available.
+- queue blobs for contact addresses will be structured and some of the large blobs can be removed in case of resource exhaustion attack (and recreated by the client if needed), with the only downside that PQ handshake will be postponed (which is the case now) and profile will not be available at a point of connection.

rfcs/2024-09-10-private-rendezvous.md

@@ -0,0 +1,26 @@
+# Private rendezvous protocol
+
+## Problem
+
+Our current handshake protocol is open to this attack: whoever observes the link exchange, knows on which router connection is being made, and if the traffic on this router is observed, then it can confirm communication between parties. Further, even with the [last proposal](./2024-09-09-smp-blobs.md#possible-privacy-improvement), having real-time access to the router data allows to establish the exact messaging queue that is used to send messages.
+
+## Solution
+
+We could make the initial link exchange more private by making it harder for any observer to discover which router will be used for messaging by hiding this information from the router that hosts the initial link.
+
+Preliminary, the protocol could be the following:
+
+1. Connection initiator stores 224-256 bytes of encrypted connection link on a rendezvous router (link contains router host and linkId on another messaging router, not a rendezvous one).
+
+2. Rendezvous router adds these links to buckets, up to 64 links per bucket. Bucket ID is the timestamp when the bucket was created + a sequential bucket number, in case more than one bucket is created per second.
+
+3. The router responds to the link creator with a bucket ID where this link was added. That bucket ID is its timestamp + a number prevents router "fingerprinting" clients and using say one bucket for each client. If timestamp is different or a bucket number within this timestamp is too large, the client can refuse to use it, depending on the client settings.
+
+4. The initiating party will pass to the accepting party the rendezvous router host, the hash of this bucket ID (bucket link) and the passphrase to derive the key from. The initiating party has an option to pass a link and passphrase via two channels - in which case the link will only contain the bucket ID.
+
+5. The accepting party would then request the bucket via its ID hash (the router would store hashes to be able to look up - hash is used to prevent showing time in the link) and attempt to decrypt all contained links using the provided key.
+The accepting party then will continue the connection via the decrypted link.
+
+This obviously does not protect accepting party from the initiating party, if it can choose rendezvous router it controls. It also does not protect from the malicious rendezvous router that would collaborate with link observers. I think reunion doesn’t protect from it too.
+
+But it does protect connection from whoever observes the link, particularly if this link only contains the bucket and the key is passed separately, via some other channel.

rfcs/2024-09-25-ios-notifications-2.md

@@ -0,0 +1,49 @@
+# iOS notifications delivery
+
+## Problem
+
+For iOS notifications to be delivered the client has to create credentials for notification subscription on SMP router using NKEY command and after that create a subscription on notification router using SNEW command. These two commands are sent in sequence, after the connections are created, and for it to happen the client needs to be online and in foreground.
+
+iOS users tend to close the app when it is not used, and iOS has very limited permissions for background activities, so these notification subscriptions are created with a substantial delay, and notifications do not work.
+
+This problem is distinct from and probably more common than other problems affecting notifications delivery described [here](./2024-07-06-ios-notifications.md).
+
+## Solution
+
+1. When the new connection is created, the client already knows if it needs to create notification subscription or not, based on the conversation setting (e.g., if the group is muted, the client will not create notification subscription as well.). We should extend NEW command to avoid the need to send additional NKEY command with an option to create notification subscription at the point where connection is created. NDEL would still be used to disable this notification, and NKEY will be used to re-enable it.
+
+2. In the same way we stopped using SDEL command (NDEL sends notification DELD to subscribed notification router) to delete notificaiton subscriptions from notification router, we should delegate creating notification subscription on notification router to SMP routers. Clients could use keys agreed with ntf router for e2e encryption and for command authorization to encrypt and sign instruction to create notification subscription that will be forwarded to notification router using protocol similar to SMP proxies. This will avoid the need for clients to separately contact notification routers that won't happen until they are online.
+
+3. Instead of making Ntf router trust DELD notifications, we could send deletion instructions signed by the client, which will only fail to send in case notification router is down (and they won't be sent later after router restart).
+
+Cons:
+- If SMP routers were to retain in the storage the information about which notification router is used for which queue, it would reduce metadata privacy. While currently it is not an issue, as all notification routers are known and operated by us, once there are other client apps, this can be used for app users fingerprinting, which would act as a deterrence from using new apps – but only if app users use routers of operators who are different from the app provider. To mitigate it, we could only store it in router memory and include notification instruction in subscription commands (SUB) and include notification subscription status in SUB responses. We don't need to mitigate the problem of router being able to store this information, as messaging routers can observe which notification routers connect to them anyway.
+- If SMP router is restarted before the subscription request is forwared to the notification router, then it will have to be forwarded again, once the client subscribes. The problem here is that if the client is offline, it will neither subscribe to the queue to send notification subscription request, nor receive notifications from this queue. Storing notification router and subscription request would mitigate that, as in this case we could send all pending requests on router start, without depending on client subscriptions.
+- "Small" agent will need to support connections to ntf routers and manage workers that retry sending pending subscription requests.
+- Until the client learns the public keys of notification router, it will not be able to decrypt notifications. It potentially can be mitigated by using the public key of the router returned when token is created, in this way different client keys (per-queue) will be combined with the same ntf router key (per-token).
+
+## Implementation details
+
+1. NEW and NKEY commands will need to be extended to include notification subscription request. As the notifier ID needs to be sent to notification router, this notifier ID will have to be client-generated and supplied as part of NEW command.
+
+now:
+
+```haskell
+NEW :: RcvPublicAuthKey -> RcvPublicDhKey -> Maybe BasicAuth -> SubscriptionMode -> SenderCanSecure -> Command Recipient
+NKEY :: NtfPublicAuthKey -> RcvNtfPublicDhKey -> Command Recipient
+```
+
+extended:
+
+```haskell
+NEW :: RcvPublicAuthKey -> RcvPublicDhKey -> Maybe BasicAuth -> SubscriptionMode -> SenderCanSecure -> Maybe NtfRequest -> Command Recipient
+
+data NtfRequest = NtfRequest NotifierId NtfPublicAuthKey RcvNtfPublicDhKey NtfServerRequest
+
+data NtfServerRequest = NtfServerRequest NtfServer EncSingedNtfCmd
+
+NKEY :: NtfPublicAuthKey -> RcvNtfPublicDhKey -> Maybe NtfServerRequest -> Command Recipient
+-- NotifierID is passed in entity ID field of the transmission
+```
+
+2. Notification router will need to support an additional command to receive "proxied" subscription commands, `SFWD`, that would include `NtfServerRequest`. This command can include both `SNEW` and `SDEL` commands.

rfcs/2024-11-25-queue-blobs-2.md

@@ -0,0 +1,58 @@
+# Blob extensions for SMP queues 2 and queue storage
+
+This document evolves the design proposed [here](./2024-09-09-smp-blobs.md).
+
+## Problems
+
+In addition to problems in the first doc, we have these issues with in-memory queue record storage:
+- many queues are idle or rarely used, but they are loaded to memory, and currently just loading all queues uses 20gb RAM on each router, and takes 10 min to process, increasing downtimes during restarts.
+- adding blobs to memory would make this problem much worse.
+
+## Proposed solution
+
+Move queues to the same journalling approach as [used for messages](./2024-09-01-smp-message-storage.md) now, with independent file names in the same folders.
+
+Each queue change would be logged to its own file, and every time the queue is opened the whole file will be read and compacted to a single line - replacing one store log for all queues, with individual log files for each queue.
+
+Queue deletion would not be making a record in the file, instead it would be deleting the entire folder - it would reduce retention period for any metadata of deleted queues.
+
+We could additionally record deletions to the central log, for debugging, and reset it on every start. But in this case we should not remove folders at the point of deletion, but rather mark them as deleted and delete on restart. TBC
+
+It would also allow simplifying blob storage by having only one blob per queue - for example, limied to 16kb (a bit smaller to fit in block) for contact address queues and 4-8kb for invitations (to fit PQ keys and conversation preferences).
+
+We would also need to be able to lookup recipient ID via sender/notifier/link IDs.
+
+One possible solution is to use and load to memory a central index file. But it is likely to also consume a lot of memory and result in slow starts.
+
+Another solution that is probably better is to use the same folder structure and put notifier/sender/link files with the ID of the recipient queue inside the files. So to locate recipient queue the sender would have to locate folder containing the reference file pointing to the recipient queue and then to locate the actual queue data.
+
+## Implementation details
+
+Each queue folder would these files:
+
+- queue_state.log (and timestamped backups) - to store pointers to message journals (already implemented)
+- messages.randomBase64.log - message journals (already implemented)
+- queue_rec.log (and timestamped backups) - to log complete queue record every time it is changed (so only the last line needs to be read following the same logic as with queue_state.log, to prevent file corruption).
+- blob.data, blob.data.bak, blob.timestamp.data - files for data blobs (to make sure some copy of this file is readable/correct in case of write corruption) - the same two step overwrite process will be used as currently with store log compacting:
+  - on write: 1. if file exists, move it to .bak, 2. store new blob to .data, 3. move .bak to .timestamp.data
+  - on read: 1. if .bak exists, move it to .data 2. use .data
+
+Additional suggestion to reduce probability of queue_state.log and queue_rec.log file corruption is to do one of the following:
+- log end of lines in the beginning of the output, not in the end, to prevent the last line from being corrupted in case the previous line was not fully stored. The downside is that the file will not be EOL terminated, and there will be no confirmation that the output was fully made.
+- log EOL both in the beginning and at the end of output, and ignore empty lines in between - this would both confirm that the last line is fully logged and prevent corruption of the next line in case it was not.
+- check the last byte of the file and log EOL if it is not EOL. Probably cleanest approach, but with a small performance cost.
+
+If queue folder is a reference to the queue, it may have one of these files:
+- notifier.id
+- sender.id
+- link.id
+
+These files would contain a one line with the recipient ID of the queue. These files would never change, they can only be deleted when queue is deleted or when notifier/link is deleted.
+
+There is logic in code preventing using the same ID in different contexts, and the ID size is large enough to make any collisions unlikely (192 bits), so with correctly working code the queue folder would either have one of reference files, and nothing else, or the queue and message files from the beginning of this section. But even if the same ID is re-used in different context, it should not cause any problems as file names don't overlap.
+
+While we could store different types of references in different types of folders, it would have additional costs of maintaining 4 folder hierarchies. Instead we could use the fact that it is one hierarchy to prevent using the same ID in different contexts.
+
+## Protocol
+
+The only change in protocol is that there will be only one blob per queue, without markers (see the previous doc). Otherwise the protocol and proposed privacy improvement seem reasonable.

rfcs/2025-03-30-ios-notifications-3.md

@@ -0,0 +1,93 @@
+# New notifications protocol
+
+## Problem
+
+iOS notifications have these problems:
+- iOS notification service crashes exceeding memory limit. This is being addressed by changes in GHC RTS.
+- there is a large number of connections, because each member in a group requires individual connection. This will improve with chat relays when each group would require 2-3 connections.
+- some notification may be not shown if notification with reply/mention is skipped, and instead some other message is delivered, which may be muted. This would not improve without some changes, as notifications may be skipped anyway.
+- client devices delay communication with ntf router because it is done in background, and by that time the app may be suspended.
+- notification router represents a bottleneck, as it has to be owned by the app vendor, and the current design when ntf router subscribes to notifications scales very badly.
+
+This RFC is based on the previous [RFC related to notifications](./2024-09-25-ios-notifications-2.md).
+
+## Solution
+
+As notification router has to know client token and currently it associates subscriptions with this token anyway, we are not gaining any privacy and security by using per-subscription keys - both authorization and encryption keys of notification subscription can be dropped.
+
+We still need to store the list of queue IDs associated with the token on the notification router, but we do not need any per-queue keys on the notification router, and we don't need subscriptions - it's effectively a simple set of IDs, with no other information.
+
+In this case, when queue is created the client would supply notifier ID - it has to be derived from correlation ID, to prevent existense check (see previous RFC). As we also supply sender ID, instead of deriving it as sha3-192 of correlation ID, they both can be derived as sha3-384 and split to two IDs - 24 bytes each.
+
+The notification router will maintain a rotating list of router keys with the latest key communicated to the client every time the token is registered and checked. The keys would expire after, say, 1 week or 1 month, and removed from notification router on expiration.
+
+The packet containing association between notifier queue ID and token will be crypto_box encrypted using key agreement between identified notification router master key and an ephemeral per packet (effectively, per-queue) client-key.
+
+Deleting the queue may also include encrypted packet that would verify that the client deleted the queue.
+
+Instead of notification router subscribing to the notifications creating a lot of traffic for the queues without messages, the SMP router would push notifications via NTF router connection (whether via NTF or via SMP protocol). This could be used as a mechanism to migrate existing queues when with the next subscription the notification router would communicate it's address to SMP router and this association would be stored together with the queue.
+
+## Protocol design
+
+Additional/changed SMP commands:
+
+```haskell
+-- register notification router
+-- should be signed with router key
+NSRV :: NtfServerCreds -> Command NtfServer
+
+-- response
+NSID :: NtfServerId -> BrokerMsg
+
+-- to communicate which router is responsible for the queue
+-- should be signed with queue key
+NSUB :: Maybe NtfServerId -> Command Notifier
+
+-- subscribe to notificaions from all queues associated with the router
+-- should be signed with router key
+-- entity ID - NtfServerId
+NSSUB :: Command NtfServer
+
+data NtfServerCreds = NtfServerCreds
+  { server :: NtfServer,
+    -- NTF router certificate chain that should match fingerpring in address
+    cert :: X.CertificateChain,
+    -- router autorizatio key to sign router subscription requests
+    authKey :: X.SignedExact X.PubKey
+  }
+
+-- entity ID is recipient ID
+NSKEY :: NtfSubscription -> Command Recipient
+
+data NtfSubscription = NtfSubscription
+  -- key to encrypt notifications e2e with the client
+  { ntfPubDbKey :: RcvNtfPublicDhKey,
+    ntfServer :: NtfServer,
+    -- should be linked to correlation ID to prevent existense check
+    -- the ID sent to notification router could be its hash?
+    ntfId :: NotifierId,
+    encNtfTokenAssoc :: EncDataBytes
+  }
+
+-- before the encryption - equivalent to NSUB command, but without key to authorize requests to specific queue
+data NtfTokenAssoc = NtfTokenAssoc
+  { signature :: SignatureEd25519,
+    tknId :: NtfTokenId,
+    ntfQueue :: SMPQueueNtf
+  }
+```
+
+SMP router will need to maintain the list of Ntf routers and their credentials, and when NSSUB arrives to make only one subscription. When message arrives it would deliver notification to the correct connection via queue / ntf router association.
+
+Ntf router needs to maintain three indices to the same data:
+- `(smpServer, queueId) -> tokenId` - to deliver notification to the correct token
+- `tokenId -> [smpServer -> [queueId]]` - to remove all queues when token is removed, and to store/update these associations effficiently - store log may have one compact line per token (after compacting), or per token/router combination.
+- `[smpServer]` - array of SMP routers to subscribe to.
+
+## Mention notifications
+
+Currently we are marking messages with T (true) for messages that require notifications and F (false) for messages that don't require. Sender does not know whether the recipient has notifications disabled, enabled or in mentions-only mode.
+
+The proposal is to:
+- add additional values to this metadata, e.g. 2 (priority) and 3 (high priority) (and T/F could be sent as 0/1 respectively) - that is, to deliver notifications even if notifications are generally disabled (they can still be further filtered by the client).
+- instead of deleting notification credentials when notifications are disabled - which is costly - communicate to SMP router the change of notificaion priority level, e.g. the client could set minimal notification priority to deliver notifications, where 0 would mean disabling it completely, 1 enable for all, 2 for priority 2+, 3 for priority 3. The downside here is that it could be used for timing correlation of queues in the group, but it already can be used on bulk deletions of ntf credentials for these queues and when sending messages.

rfcs/2025-04-04-short-links-for-groups.md

@@ -0,0 +1,159 @@
+# Using short links as group links
+
+## Problem
+
+To use the short links for groups these problems has to be / can be solved:
+1. recognizing link as a group link.
+2. permanent link with the ability to change chat relays.
+3. binding owners signatures to the link.
+4. allowing to add/remove owners, both to share ownership and for reliability in case of one owner losing keys/access.
+
+While current short links solve problems 1-3 (via contact type, and via extension of user data in the link), the problem 4 is solved only partially.
+
+We could include the current list of root owners in the user data, and we could send any history of ownership changes from this baseline as a short blockchain on joining the group, we still requrie one master owner to retain access to the queue associated with the group.
+
+## Possible solution approaches
+
+1. "Kick this can down the road" - ignore this problem until there is a namespace, and a group name can be associated with multiple queues.
+
+Pros: simple and reasonable, and it suggests postponing multisig for owners too. The users can still see the list of owners and their keys in user data of the link, and receive admin roster signed by owners on joining.
+
+Cons: if this "master owner" loses the access to the device, no further changes to group profile will be possible.
+
+2. The queue access can be shared by sharing the key and recipient IDs with all owners.
+
+The problems:
+- preventing MITM attack between owners (this protect exists for other solutions too).
+- protecting these credentials from chat relays. So somehow there should be direct key agreement between members allowing to send e2e encrypted message inaccessible to chat relays.
+
+Pros: simpler than alternatives, and still provides protection against losing the key.
+Cons:
+- quite clunky, and requires the new primitive anyway (e2e encryption).
+- no multisig
+
+This could possibly be evolved into the requirement to have a direct connection with other owners, and verifying the security code before they have access to group.
+
+3. Allow "joint management" of SMP queues.
+
+SMP routers can support multiple recipients for contact queues:\
+- subscription would be possible to the "subscriber recipient".
+- all other changes (update data, change subscriber recipient, add or remove recipients) would require multiple recipient signatures on SMP command in line with n-of-m multisig rules, that the command sender would have to collect out-of-band (from SMP protocol point of view).
+
+Pros: allows joint ownership, and protects from losing access to master owner device.
+Cons:
+- complicates queue abstraction with approach that is not needed for most queues.
+- still retains the router as a single point of failure.
+
+4. Introduce "group" as a new type of entity managed by SMP routers.
+
+SMP routers would provide a separate set of commands for managing group records that would include in an encrypted container:
+- the group profile
+- the list of chat relay links
+- the list of owner member IDs with their public keys
+- multisig rules
+- alternative group entity locations
+- possibly, a globally unique group identity (as the hash of the initial/seed group data).
+
+While the router domain would be used as the hostname in group link, it may contain alternative hosts (not just hostnames of the same router), both in the link and in the group record data.
+
+Pros: separates additional complexity to where it is needed, allowing reliability and redundancy for group ownership.
+Cons: complexity, coupling between SMP and chat protocol.
+
+## Design for channel/group as a separate queue mode
+
+Option 1.
+
+A queue mode "channel" when owners are represented by their individual queues (either a separate mode, or a submode of "channel", or just normal contact address queues). In this case sending message to channel queue would broadcast message to queue owners, without exposing even the number of owners.
+
+Pros:
+- allows chat relays to send messages to all owners (e.g., channel can be secured with the list of snd keys, one per relay).
+- quite easy to evolve from the current design.
+- extensible.
+Cons:
+- close to "solution in search of a problem".
+- does not require data model changes - channel queue would simply have a list of owner "recipient IDs", and each owner queue would also point to channel.
+
+Option 2.
+
+Also a separate queue mode "channel", but instead of having a linked owner queues, it would simply maintain a list of owner keys to maintain the data. In this case, messages cannot be sent to this "queue" at all.
+
+Pros:
+- simpler design.
+- we could allow sending messages to it too, with the "main" owner receiving them. This could be negotiated in the protocol.
+- it may be easier to migrate the current groups, as the admin link would be this queue (although for public groups in directory it would have to be recreated anyway).
+- Possibly, when queue is created there should be a flag whether it should accept unsigned messages - then contact addresses would be created with unsigned messages ON, messages queues, once SKEY is universally supported, with unsigned messages OFF, and channel queues with unsigned messages OFF too for new public queues.
+Cons:
+- if no messages are accepted, this is not even a queue.
+- no way to directly contact owners (maybe it is not a downside, as for relays there would be a communication channel anyway as part of the group).
+
+Option 2 looks more simple and attractive, implementing router broadcast for SMP seems unnecessary, as while it could have been used for simple groups, it does not solve such problems as spam and pre-moderation anyway - it requires a higher level protocol.
+
+The command to update owner keys would be `RKEY` with the list of keys, and we can make `NEW` accept multiple keys too, although the use case here is less clear.
+
+## Multiple owners managing queue data.
+
+Option 1: Use the same keys in SMP as when signing queue data.
+
+Option 2: Use different keys.
+
+The value here could be that the router could validate these signatures too, and also maintain the chain of key changes. While tempting, it is probably unnecessary, and this chain of ownership is better to be maintained on chat relay level, as there are no size constraints on the size of this chain. Also, it is better for metadata privacy to not couple transport and chat protocol keys.
+
+We still need to bind the mutable data updates to the "genesis" signature key (the one included in the immutable data).
+
+The proposed design:
+
+- when mutable data is signed by genesis key, then it is bound, and no changes is needed.
+- mutable data may be signed by the key of the new owner, in which case mutable part itself must contain the binding. We could also use ring signature to sign the mutable data, concealing which owner signed the data - that would increase the signature size from 64 bytes to `32 * (n + 1)` bytes.
+
+Current mutable data:
+
+```haskell
+data UserLinkData = UserLinkData
+  { agentVRange :: VersionRangeSMPA,
+    userData :: ConnInfo
+  }
+```
+
+Proposed mutable data:
+
+```haskell
+data UserLinkData = UserLinkData
+  { agentVRange :: VersionRangeSMPA,
+    owners :: [OwnerInfo]
+    userData :: ConnInfo
+  }
+
+type OwnerId = ByteString
+
+data OwnerInfo = OwnerInfo
+  { ownerId :: OwnerId, -- unique in the list, application specific - e.g., MemberId
+    ownerKey :: PublicKeyEd25519,
+    -- owner signature of sender ID,
+    -- confirms that the owner agreed with being the owner,
+    -- prevents a member being added as an owner without consent.
+    ownerSig :: SignatureEd25519,
+    -- owner authorization, sig(ownerId || ownerKey, prevKey), where prevKey is either a "genesis key" or some other key previously signed by the genesis key.
+    authOwnerId :: OwnerId, -- null for "genesis"
+    authOwnerSig :: SignatureEd25519
+  }
+```
+
+The size of the OwnerInfo record encoding is:
+- ownerId: 1 + 12
+- ownerKey: 1 + 32
+- ownerSig: 1 + 64
+- ownerAuthId: 1 + 12
+- ownerAuthSig: 1 + 64
+
+~189 bytes, so we should practically limit the number of owners to say 8 - 1 original + 7 addiitonal. Original creator could use a different key as a "genesis" key, to conceal creator identity from other members, and it needs to include the record with memberId anyway.
+
+The structure is simplified, and it does not allow arbitrary ownership changes. Its purpose is not to comprehensively manage ownership changes - while it is possible with a generic blockchain, it seems not appropriate at this stage, - but rather to ensure access continuity and that the router cannot modify the data (although nothing prevents the router from removing the data completely or from serving the previous version of the data).
+
+For example it would only allow any given owner to remove subsequenty added owners, preserving the group link and identity, but it won't allow removing owners that signed this owner authorization. So owners are not equal, with the creator having the highest rank and being able to remove all additional owners, and owners authorise by creator can remove all other owners but themselves and creator, and so on - they have to maintain the chain that authorized themselves, at least. We could explicitely include owner rank into OwnerInfo, or we could require that they are sorted by rank, or the rank can be simply derived from signatures.
+
+When additional owners want to be added to the group, they would have to provide any of the current owners:
+- the key for SMP commands authorization - this will be passed to SMP router together with other keys. There could be either RKEY to pass all keys (some risk to miss some, or of race conditions), or RADD/RGET/RDEL to add and remove recipient keys, which has no risk of race conditions.
+- the signature of the immutable data by their member key included in their profile.
+- the current owner would then include their member key into the queue data, and update it with LSET command. In any case there should be some simple consensus protocol between owners for owner changes, and it has to be maintained as a blockchain by owners and by chat relays, as otherwise it may lead to race conditions with LSET command.
+
+Potentially, there could be one command to update keys and link data, so that they are consistent.

rfcs/2025-07-15-multi-device.md

@@ -0,0 +1,104 @@
+# Using the same profile from multiple devices
+
+## Problem
+
+Double Ratchet algorithm makes it hard to send/receive messages sent to the user from different devices, as each message changes the state of Double Ratchet keys, and these state changes must be strictly sequential and they cannot be reversed (although skipping is possible).
+
+Traditional approach for multi-device converts each direct conversation into a group, where each device participates as a member. Likewise, for group conversations each device also participates as a member. While these members *look* as if they are the same user to others, a very simple client app modification may show device ID for each message, and the communication peers, both in direct chats and in groups would know how many devices a user has and which device the user sent the message from. In addition to that, with this approach communication peers can send different messages to different devices (it can be prevented by provider who would request that only message key is encrypted with DR, while the encrypted message is the same) or withheld from some devices (it cannot be prevented by provider, as it cannot add key to the communication in case it is missing, and cannot withhold the message completely too). These opens various vectors for targeted attacks, e.g.:
+- tracking movements of the user: once each devices is identified as "desk" and "phone" it would allow to know where the user is at a given time.
+- manipulating information by sending messages to one device (to have proof it was sent) and withholding from others, or sending different messages if the protocol allows it.
+
+In addition to that, the specific implementation of this approach in Signal compromises break-in recovery property (aka post-compromise security) of Double-Ratchet algorithm, making its design ineffective - the only reason to have the second ratchet in DR algorithm is to provide break-in recovery, without it a much simpler design with a single ratchet is sufficient. See [this paper](https://eprint.iacr.org/2021/626.pdf) for details.
+
+While this limitation can be addressed with notifications when a new device is added and per-device keys, we still find the remaining attack vectors on user security and privacy to be unacceptable, and opening unsuspecting users to various criminal actions - and it is wrong to say that would only affect security conscious users, and most people would not be affected by these risks. Allowing potential criminals in groups to know which device you are currently using is a real risk for all users.
+
+Another approach was offered by Threema that is ["mediator" router](https://threema.com/en/blog/md-architectural-overview) where the state of encryption ratchets is stored router-side. While it protects the user from their communication peers, it increases required level of trust to the routers, and in case of SimpleX network it would expose the knowledge of who communicates to whom. So while the idea of router-side storage of encryption state is promising, it has to be per-connection, to retain "no-accounts" property of SimpleX messaging network.
+
+Also see [FAQ](https://simplex.chat/faq/#why-cant-i-use-the-same-profile-on-different-devices) and [this issue](https://github.com/simplex-chat/simplex-chat/issues/444#issuecomment-3066968358).
+
+## Proposed solution
+
+One of the ideas presented in FAQ - to store the state of Double Ratchet algorithm in the encrypted container on the router seems promising. The RFC develops this idea.
+
+### Considerations for the design
+
+1. The largest ratchet state size with the current implementation is less than 8kb (which is achieved when both sides shared PQ keys and ciphertexts), so while it cannot fit in the same transport blocks together with sent and received messages, it would fit in one transport block.
+
+2. Protocol commands and events may be changed (even if at the cost of slightly reducing message size) can fit the hash of the ratchet state (32 bytes sha256 would be sufficient), so that the client can determine whether it has the most recent ratchet state or if it needs to retrieve the latest copy. Message size reduction won't affect the users because we use compression, and there is a substantial reserve.
+
+3. Client commands that modify ratchet state would include the hash of the previous ratchet state so that the router can reject or ignore the command in case the previous ratchet state is different or in case command is repeated in case of lost response).
+
+4. The client does not need to retrieve message state for each encryption and decryption operation - it can "speculatively" use the ratchet state it has, and receive correct ratchet state in the "error" response after attempting encryption based on incorrect ratchet state.
+
+## Proposed protocol design
+
+Ratchet state will be stored on the same router that stores message queue, as part of message queue record. 8kb is a sufficient size for this blob (the actual max size is 7800 bytes). The router would also store the hashes of the current and, possibly, the previous ratchet states (TBC).
+
+While ratchet is used for duplex connection, the connection still has primary queue, and with redundancy the same ratchet state can be stored on all secondary queues.
+
+Ratchet state will be encrypted using secret_box - a symmetric encryption scheme, so PQ-resistant. If ratchet state is stored on more than one router, it has to be encrypted with a different key for each router.
+
+Questions: how to rotate the key used to store ratchet? Should key used to encrypt ratchet rotate at the same time when queue is rotated? The latter is a logical option, as it prevents additional complexity and solves the problem anyway. A possible option is to have "ratchet version" that will be used to advance the key used to encrypt ratchet via HKDF.
+
+Security considerations: the scheme may reduce break-in recovery to the points queues are rotated, unless there is some randomness mixed-in into the key derivation (the key used to encrypt ratchet state). But including randomness would defeat the purpose, as other devices wouldn't be able to access the ratchets. Another approach would be to have each device use its own key for encryption, and encrypt to all keys of all devices (or to encrypt key, to avoid size increase). Having multiple encryptions would show how many devices use the queue, but routers already can observe it, so it is a better tradeoff. Another idea would be to rotate the key used to authorize queue commands - we already support multiple recipient keys, and it can be used for multi-device scenario. That would partially mitigate break-in attacks as the attacker who obtained the key from ratchet state would be able to decrypt it, but won't be able to decrypt it (the attacker collusion with the router is not mitigated). Yet another idea would be for each party (device) to share its private (or encapsulation) key and to have a symmetric key (used to encrypt the ratchet state) encrypted (encapsulated) separately for each device. This would reduce the size of the stored data to `ratchet size` + `encrypted key size` * N, so even in case of PQ encryption (e.g. sntrup) the size required to store the ratchet would be under transport block size, while limiting it to say 4-8 devices, which is sufficient.
+
+To participate in multi-device scheme the devices would join the usual group that will be used to share public (encapsulation) device keys and to communicate updates to conversations that were received by the currently "active" device. "Active" means the device that received or sent and processed the message, and while only one device can receive messages from a given queue, device "active" state may be determined per queue, allowing concurrent usage.
+
+The scheme must be resilient to state updates being lost, and in case of direct messages it would result in some messages not being shown (or shown as skipped), while conversation preference and profile updates can be re-requested from peers, while the current profile of the user would become the latest. Likewise, for groups state updates ca be requested from super-peers or for decentralized groups - from owners. Maintaining chat state consistency is an important consideration, but is not a focus of this RFC - the focus is managing message delivery and DR encryption for multiple devices. Other multi-device schemes have the same issues with state consistency. Partially, the profile state consistency can be improved by using a single shared queue (or set of queues) to store user's profile and chat preferences to synchronize profile updates asynchronously between the devices.
+
+## The protocol to send the message
+
+`rsi` - ratchet state on device `i`.
+
+`enc(rs)` - current authoritative ratchet state on the router.
+
+`pt` and `ct` - plaintext and ciphertext messages.
+
+Encryption is a state transition function ratchetEnc: `(ct, rs') = ratchetEnc(pt, rs)`.
+
+1. Device encrypts the message using the stored ratchet state: `(ct, rsi') = ratchetEnc(pt, rsi)`
+
+2. Device sends modified encrypted ratchet state and the hash of the previous encrypted state to the router that stores the queue: `RSET (hash(enc(rsi)), enc(rsi'))`.
+
+3. If the hash of the previous state matches state stored on the router (`hash(enc(rsi)) == hash(enc(rs))`), the router updates the state and responds with `ratchet_ok` (that may include the current state or it's hash, for validation). If the hash is different, the router responds with `bad_ratchet(enc(rs))` message that includes the correct ratchet state. These updates must be atomic. In this case device has to update the local ratchet state (provided it can decrypt it), and repeat encryption attempt. If device cannot decrypt the provided ratchet state, it means that the connection is disrupted (possibly, device is removed from device group, but missed the notifications).
+
+4. After successful state update in primary receiving queue, the device would update it in secondary receiving queues.
+
+5. Device sends encrypted message as usual, via proxy that must be different both from the router that stores the ratchet and from the destination router.
+
+6. Device broadcasts sent message and new ratchet state to other devices in the device group.
+
+This protocol is simple, and it minimizes requests when sending the message to one additional request to update ratchet state in most cases, only requiring two requests when device state was not updated via device group prior to message sending attempt.
+
+## The protocol to receive the message
+
+Decryption is also a state transition function: `(pt, rs') = ratchetDec(ct, rs)`
+
+1. Router sends the message to the device (can be in response to SUB or ACK commands, or with active subscription). Pushed message would include the hash of the currently stored ratchet state: `hash(enc(rs))`.
+
+2. If device has the ratchet state with the same hash (`hash(enc(rs)) == hash(enc(rsi))`), it decrypts the message: `(pt, rsi') = ratchetDec(ct, rsi)`.
+
+3. If device has ratchet state with a different hash, it requests ratchet from the router with additional protocol command `RGET` with response `RCHT (enc(rs))` and updates the local state.
+
+4. Device decrypts the message `(pt, rsi') = ratchetDec(ct, rsi)` and processes it as usual.
+
+5. Device sends acknowledgement to the router as usual, but now it includes the new ratchet state and the hash of the previous state: `ACK msgId (hash(enc(rsi)), enc(rsi'))`
+
+6. The router compares ratchet state with stored state hash, and in case it matches it processes `ACK` and responds with `OK` as usual (or `NO_MSG` in case msgId is incorrect, also as usual - it would happen in repeated ACK requests). If ratchet state hash does not match, the router would respond with `bad_ratchet(enc(rs))` - which means that the message was already processed by another device and ratchet was advanced. This is a complex scenario, as the client has to either revert the change from message processing or somehow combine the change with the updates communicated via device group (as a side note, device group can simply re-broadcast messages, not state updates, but it will result in state divergence between devices when different messages are lost).
+
+Unlike sending messages, this flow does not require any additional requests in most cases, only requiring requesting message state reconciliation when the same message was received and processed by more than one client, but it does not require re-acknowledgement.
+
+## Challenges
+
+This is an idea of the design rather than the actual design, as it requires more thinking about:
+- how to handle concurrent ratchet state updates,
+- "active" status transitions per queue,
+- avoiding concurrent subscriptions to queues from multiple devices,
+- state updates and synchronization between devices,
+- handling skipped messages,
+- costs to update ratchets in bulk send scenario - this scheme would substantially increase costs of preparing large broadcasts, and it makes this scheme not acceptable for chat relays. Which means that "profile" on desktop used as chat relay won't be synched to other devices.
+- etc.
+
+## Advantages
+
+The communication peers won't know how many devices the user has, and which device was used to send the message. Also, the communication peers won't be able to send different messages to different user's devices, or to withhold messages from some devices.

rfcs/2025-08-20-service-subs-drift.md

@@ -0,0 +1,101 @@
+# Detecting and fixing state with service subscriptions
+
+## Problem
+
+While service certificates and subscriptions hugely decrease startup time and delivery delays on router restarts, they introduce the risk of losing subscriptions in case of state drifts. They also do not provide efficient mechanism for validating that the list of subscribed queues is in sync.
+
+How can the state drift happen?
+
+There are several possibilities:
+- lost broker response would make the broker consider that the queue is associated, but the client won't know it, and will have to re-associate. While in itself it is not a problem, as it'll be resolved, it would make drift detected more frequently (regardless of the detection logic used). That service certificates are used on clients with good connection would make it less likely though.
+- router state restored from the backup, in case of some failure. Nothing can be done to recover lost queues, but we may restore lost service associations.
+- queue blocking or removal by router operator because of policy violation.
+- router downgrade (when it loses all service associations) with subsequent upgrade - the client would think queues are associated, while they are not, and won't receive any messages at all in this scenario.
+- any other router-side error or logic error.
+
+In addition to the possibility of the drift, we simply need to have confidence that service subscriptions work as intended, without skipping queues. We ignored this consideration for notifications, as the tolerance to lost notifications is higher, but we can't ignore it for messages.
+
+## Solution
+
+Previously considered approach of sending NIL to all queues without messages is very expensive for traffic (most queues don't have messages), and it is also very expensive to detect and validate drift in the client because of asynchronous / concurrent events.
+
+We cannot read all queues into memory, and we cannot aggregate all responses in memory, and we cannot create database writes on every single service subscription to say 1m queues (a realistic number), as it simply won't work well even at the current scale.
+
+An approach of having an efficient way to detect drift, but load the full list of IDs when drift is detected, also won't work well, as drifts may be common, so we need both efficient way to detect there is diff and also to reconcile it.
+
+### Drift detection
+
+Both client and router would maintain the number of associated queues and the "symmetric" hash over the set of queue IDs. The requirements for this hash algorithm are:
+- not cryptographically strong, to be fast.
+- 128 bits to minimize collisions over the large set of millions of queues.
+- symmetric - the result should not depend on ID order.
+- allows fast additions and removals.
+
+In this way, every time association is added or removed (including queue marked as deleted), both peers would recompute this hash in the same transaction.
+
+The client would suspend sending and processing any other commands on the router and the queues of this router until SOKS response is received from this router, to prevent drift. It can be achieved with per-router semaphores/locks in memory. UI clients need to become responsive sooner than these responses are received, but we do not service certificates on UI clients, and chat relays may prevent operations on router queues until SOKS response is received.
+
+SOKS response would include both the count of associated queues (as now) and the hash over all associated queue IDs (to be added). If both count and hash match, the client will not do anything. If either does not match the client would perform full sync (see below).
+
+There is a value from doing the same in notification router as well to detect and "fix" drifts.
+
+The algorithm to compute hashes can be the following.
+
+1. Compute hash of each queue ID using xxHash3_128 ([xxhash-ffi](https://hackage.haskell.org/package/xxhash-ffi) library). They don't need to be stored or loaded at once, initially, it can be done with streaming if it is detected on start that there is no pre-computed hash.
+2. Combine hashes using XOR. XOR is both commutative and associative, so it would produce the same aggregate hash irrespective of the ID order.
+3. Adding queue ID to pre-computed hash requires a single XOR with ID hash: `new_aggregate = aggregate XOR hash(queue_id)`.
+4. Removing queue ID from pre-computed hash also requires the same XOR (XOR is involutory, it undoes itself): `new_aggregate = aggregate XOR hash(queue_id)`.
+
+These hashes need to be computed per user/router in the client and per service certificate in the router - on startup both have to validate and compute them once if necessary.
+
+There can be also a start-up option to recompute hashe(s) to detect and fix any errors.
+
+This is all rather simple and would help detecting drifts.
+
+### Synchronization when drift is detected
+
+The assumption here is that in most cases drifts are rare, and isolated to few IDs (e.g., this is the case with notification router).
+
+But the algorithm should be resilient to losing all associations, and it should not be substantially worse than simply restoring all associations or loading all IDs.
+
+We have `c_n` and `c_hash` for client-side count and hash of queue IDs and `s_n` and `s_hash` for router-side, which are returned in SOKS response to SUBS command.
+
+1. If `c_n /= s_n || c_hash /= s_hash`, the client must perform sync.
+
+2. If `abs(c_n - s_n) / max(c_n, s_n) > 0.5`, the client will request the full list of queues (more than half of the queues are different), and will perform diff with the queues it has. While performing the diff the client will continue block operations with this user/router.
+
+3. Otherwise would perform some algorithm for determining the difference between queue IDs between client and router. This algorithm can be made efficient (`O(log N)`) by relying on efficient sorting of IDs and database loading of ranges, via computing and communicating hashes of ranges, and performing a binary search on ranges, with batching to optimize network traffic.
+
+This algorithm is similar to Merkle tree reconcilliation, but it is optimized for database reading of ordered ranges, and for our 16kb block size to minimize network requests.
+
+The algorithm:
+1. The client would request all ranges from the router.
+2. The router would compute hashes for N ranges of IDs and send them to the client. Each range would include start_id, optional end_id (for single ID ranges) and XOR-hash of the range. N is determined based on the block size and the range size.
+3. The client would perform the same computation for the same ranges, and compare them with the returned ranges from the router, while detecting any gaps between ranges and missing range boundaries.
+4. If more than half of the ranges don't match, the client would request the full list. Otherwise it would repeat the same algorithm for each mismatched range and for gaps.
+
+It can be further optimized by merging adjacent ranges and by batching all range requests, it is quite simple.
+
+Once the client determines the list of missing and extra queues it can:
+- create associations (via SUB) for missing queues,
+- request removal of association (a new command, e.g. BUS) for extra queues on the router.
+
+The pseudocode for the algorightm:
+
+For the router to return all ranges or subranges of requested range:
+
+```haskell
+getSubRanges :: Maybe (RecipientId, RecipientId) -> [(RecipientId, Maybe RecipientId, Hash)]
+getSubRanges range_ = do
+  ((min_id, max_id), s_n) <- case range_ of
+    Nothing -> getAssociatedQueueRange -- with the certificate in the client session.
+    Just range -> (range,) <$> getAssociatedQueueCount range
+    if
+      | s_n <= max_N -> reply_with_single_queue_ranges
+      | otherwise -> do
+          let range_size = s_n `div` max_N
+          read_all_ranges -- in a recursive loop, with max_id, range_hash and next_min_id in each step
+          reply_ranges
+```
+
+We don't need to implement this synchronization logic right now, so not including client logic here, it's sufficient to implement drift detection, and the action to fix the drift would be to disable and to re-enable certificates via some command-line parameter of CLI.

rfcs/2026-03-28-subscription-performance.md

@@ -0,0 +1,90 @@
+# Subscription performance
+
+No protocol changes. This is an implementation RFC addressing subscription performance bottlenecks in both the SMP router and the agent.
+
+## Problem
+
+Subscribing large numbers of queues is slow. A messaging client with ~300K queues per router across 3 routers takes over 1 hour to subscribe. For comparison, the NTF server with ~1M queues per router across 12 routers took 20-30 minutes (prior to NTF client services, now in master).
+
+Even on fast networks (cloud VMs), a client with 1.1M active subscriptions needed ~1.5M attempts (commands sent) to fully subscribe - ~36% retry rate caused by the timeout cascade described below.
+
+### Root causes
+
+#### 1. Router: per-command processing in batches
+
+Batch verification and queue lookups are already done efficiently for the whole batch in `Server.hs`. But `processCommand` is called per-command in a loop - each SUB does its own individual DB query for message peek/delivery. With ~135 SUBs per batch (current SMP version), that's 135 individual DB queries per batch instead of 1 batched query.
+
+For 300K queues, that's ~2200 batches x 135 queries = ~300K individual DB queries on the router, which is the dominant bottleneck when using PostgreSQL storage.
+
+NSUB is cheaper because it just registers for notifications without message delivery - no per-queue DB query.
+
+#### 2. Agent: all queues read and sent at once
+
+`getUserServerRcvQueueSubs` reads all queues for a `(userId, server)` pair in one query with no LIMIT. For 300K queues, the entire result set is loaded into memory, then all ~2200 batches are queued to send without waiting for responses.
+
+The NTF server agent uses cursor-style reading with configurable batch sizes (900 subs per chunk, 90K per DB fetch) and waits for each chunk to be processed before fetching the next.
+
+#### 3. No backpressure on sends
+
+`nonBlockingWriteTBQueue` bypasses the `sndQ` bound by forking a thread when the queue is full. All batches are queued immediately, and all their response timers start simultaneously. A 30-second per-response timeout means later batches time out not because the router is slow to respond to them specifically, but because they're waiting in the router's receive queue behind thousands of earlier commands.
+
+This causes cascading timeouts: timed-out responses trigger `resubscribeSMPSession`, which retries all pending subs. Three consecutive timeouts can trigger connection drop via the monitor thread, causing a full reconnection and retry of everything.
+
+## Solution
+
+### Part 1: Router - batched command processing
+
+Move the per-command processing loop inside command handlers so that commands of the same type within a batch can be processed together.
+
+Current flow:
+```
+receive batch -> verify all -> lookup queues all -> for each command: processCommand (individual DB query)
+```
+
+Proposed flow:
+```
+receive batch -> verify all -> lookup queues all -> group by command type -> process group:
+  SUB group: one batched message peek query for all queues
+  NSUB group: batch registration (already cheap, but can batch DB writes)
+  other commands: process individually as before
+```
+
+For SUB, the batched processing would:
+1. Collect all queue IDs from the SUB group
+2. Perform a single DB query to peek messages for all queues
+3. Distribute results back to individual responses
+
+This reduces ~135 DB queries per batch to 1, cutting router-side DB load by ~100x for subscriptions.
+
+Commands where batching doesn't matter (SEND, ACK, KEY, etc.) continue to be processed individually.
+
+### Part 2: Agent - cursor-based subscription with backpressure
+
+Replace the all-at-once fetch-and-send pattern with cursor-style batching, similar to what the NTF server agent does.
+
+Changes to `subscribeUserServer`:
+1. Fetch queues in fixed-size batches (e.g., configurable, default ~1000) using LIMIT/OFFSET or cursor-based pagination.
+2. Send each batch and wait for responses before sending the next.
+3. Remove the use of `nonBlockingWriteTBQueue` for subscription batches - use blocking writes or structured backpressure so response timers don't start until the batch is actually sent.
+
+This ensures:
+- Memory usage is bounded (not 300K queue records in memory at once)
+- Response timeouts are meaningful (timer starts when the router receives the batch, not when it's queued locally)
+- Retries are scoped to the failed batch, not all pending subs
+- Works on slow/lossy networks by naturally pacing sends
+
+### Part 3: Response timeout for batches
+
+The current per-response 30-second timeout doesn't account for batch processing time. Options:
+
+1. **Stagger deadlines**: later responses in a batch get proportionally more time. The `rcvConcurrency` field was designed for this but is never used.
+2. **Per-batch timeout**: instead of timing individual responses, timeout the entire batch with a budget proportional to batch size.
+3. **No timeout for subscription responses**: since subscriptions are sent as batches with backpressure (Part 2), and the connection is monitored by pings, individual response timeouts may not be needed. A subscription that doesn't get a response will be retried on reconnect.
+
+## Priority and ordering
+
+Part 1 (router batching) gives the biggest improvement and is independent of Parts 2/3.
+
+Part 2 (agent cursor + backpressure) eliminates the retry cascade and is critical for slow networks.
+
+Part 3 (timeout handling) is a refinement that can be addressed after Parts 1 and 2.

rfcs/README.md

@@ -0,0 +1,150 @@
+# SimpleX Network Protocol Specifications — Governance and Evolution (draft)
+
+## Why this document exists
+
+SimpleX Network protocol specifications must evolve as the network grows. This document defines how specifications change, who governs those changes, and how the history of changes is preserved.
+
+### Lessons from the web: why ratcheted governance matters
+
+The web's governance history demonstrates both the necessity of consortium governance and the dangers of getting the transition wrong.
+
+[Tim Berners-Lee invented the web in 1991](https://home.cern/science/computing/birth-web/short-history-web). [Netscape took over in 1994](https://en.wikipedia.org/wiki/Netscape_Navigator), driving rapid innovation as a single company — SSL, cookies, JavaScript, and the features that made the web commercially viable. In 1994, [W3C was founded](https://www.w3.org/about/history/) as a consortium hosted across multiple independent institutions (MIT in the US, INRIA/ERCIM in Europe, Keio University in Japan, later Beihang University in China) to govern web standards.
+
+The transition from company-led innovation to consortium governance was abrupt rather than gradual. Netscape's decline (accelerated by the [browser wars](https://en.wikipedia.org/wiki/Browser_wars) and [AOL acquisition](https://cybercultural.com/p/1999-the-fall-of-netscape-and-the-rise-of-mozilla/)) transferred control to a standards body that prioritized process over progress. The result was [a lost decade of web stagnation](https://eev.ee/blog/2020/02/01/old-css-new-css/): CSS 2.0 shipped in 1998; CSS 2.1 didn't reach Candidate Recommendation until 2004 and wasn't finalized until 2011. W3C pursued XHTML and rejected proposed enhancements to HTML, until frustrated engineers from Apple, Mozilla, and Opera formed [WHATWG in 2004](https://en.wikipedia.org/wiki/WHATWG) to build HTML5 outside W3C's process. The abrupt governance transition, without a mechanism to balance community guarantees against the imperative to continue evolving the product at pace, dramatically slowed web evolution at the time it was needed most.
+
+Then in 2023, [W3C restructured from a multi-host consortium into a single 501(c)(3) nonprofit entity](https://www.w3.org/press-releases/2023/w3c-le-launched/) — W3C Inc, incorporated in the US. The previous structure distributed governance across four independent university hosts in different countries, making capture by any single entity structurally difficult. The new structure concentrates governance in a single legal entity with a board of directors. While presented as modernization, this effectively ended the decentralized consortium model that had protected web standards for nearly three decades.
+
+### The governance double ratchet
+
+SimpleX follows the same Netscape-to-consortium evolution path, but with two ratchets designed to prevent both failure modes — stagnation from premature governance transfer, and capture from governance centralization:
+
+- **Licensing ratchet**: all contributed IP is licensed under AGPLv3 (software) and Creative Commons (documentation), perpetually and irrevocably. What is licensed cannot be unlicensed. If a Party transfers Licensed IP, the licensing obligations transfer with it.
+
+- **Governance ratchet**: power can be given to the SimpleX Network Consortium, but never taken back. The Consortium Agreement requires majority decision of all Governing Parties for changes to the agreement itself, IP policy, and admission or removal of parties.
+
+The ratcheted transition is historically proven to be necessary. It allows the company to continue driving rapid product innovation (as Netscape did for the web) while incrementally and irreversibly transferring governance to the consortium, without the abrupt handover that stalled web evolution or the centralization that later undermined it.
+
+### Specification governance via the Consortium Agreement
+
+The SimpleX Network Consortium Agreement (being deployed in 2026) establishes two levels of intellectual property governance: **Licensed IP** (all contributed protocol specifications, software, and documentation, licensed perpetually and irrevocably) and **Core IP** (the subset essential to the network, requiring consortium governance to change). The distinction between these levels and how they map to the RFC process is described in [Standard vs Core specifications](#standard-vs-core-specifications) below.
+
+## Specification change process: protocol specifications and RFCs
+
+Protocol knowledge lives in two places:
+
+### `protocol/` — Consolidated specifications
+
+Each file is a complete, self-contained description of a protocol as it exists today. Like consolidated legislation in the UK legal system: the full current law in one document, not a patchwork of amendments.
+
+Consolidated specifications are maintained on every code change that affects protocol behavior. With LLMs, the cost of maintaining consolidated documents collapses — reworking prose to incorporate a new RFC is now inexpensive relative to the value of a single authoritative document per protocol.
+
+Implementers read `protocol/`. They should never need to reconstruct current behavior from a base spec plus a chain of RFCs.
+
+### `rfcs/` — Protocol evolution commits
+
+Each RFC describes a single change to a protocol specification. RFCs are the atomic unit of protocol evolution — analogous to commits in version control, or amending acts in legislation.
+
+An RFC is not part of the protocol specification. It becomes part of the specification only when embedded into the consolidated `protocol/` document. The RFC itself remains as a permanent historical record of what changed, when, and why.
+
+## RFC lifecycle
+
+```
+                  ┌——> done/ ——> standard/
+draft (root) ——>──┤
+                  └——> rejected/
+```
+
+### Draft — `rfcs/*.md`
+
+A proposal for a protocol change. Not yet implemented. Active proposals live in the `rfcs/` root directory.
+
+Named by proposal date: `YYYY-MM-DD-topic.md`.
+
+A draft may be rejected if the proposal is considered but not accepted for implementation.
+
+### Done — `rfcs/done/`
+
+Implemented in code. The protocol change described by this RFC exists in the codebase, but the RFC has not yet been verified against the actual implementation (code may have diverged from the proposal during implementation).
+
+### Standard — `rfcs/standard/`
+
+Verified against the actual implementation and synchronized with code. The RFC accurately describes what was implemented. This is a permanent historical record — standard RFCs are never modified or removed.
+
+On promotion to standard, the RFC is:
+1. Renamed from proposal date to standardization date: `YYYY-MM-DD-topic.md` (new date, same topic slug)
+2. Updated with a document history header capturing the full lifecycle
+3. Embedded into the corresponding `protocol/` consolidated specification
+
+The `protocol/` document references embedded RFCs by name (e.g., "Private message routing added by RFC 2023-09-12-second-relays, standardized 2026-XX-XX"), similar to UK legislation citing the amending act for each clause.
+
+Protocol version numbers make it clear which RFCs are included in which protocol revision — no separate tracking is needed.
+
+### Rejected — `rfcs/rejected/`
+
+Draft proposals that were considered but not accepted for implementation. Only drafts move to rejected — once an RFC is implemented (done/), it proceeds to standard/ after verification. Preserved for historical record of design decisions.
+
+### Document history header
+
+Every RFC in `standard/` carries a history header:
+
+```
+---
+Proposed: YYYY-MM-DD
+Implemented: YYYY-MM-DD
+Standardized: YYYY-MM-DD
+Protocol: simplex-messaging v9 (or whichever protocol this amends)
+---
+```
+
+## Governance
+
+SimpleX Network follows the Netscape-to-W3C evolution path, with ratcheted rather than abrupt transitions:
+
+| Phase | Period | Governance | Development process |
+|-------|--------|-----------|-------------------|
+| Protocol invented | 2020 | Two people | Prototype developed |
+| SimpleX Chat Ltd | 2022 | One company | Product-first: code leads, specs follow |
+| SimpleX Network Consortium | 2026 | Agreement of SimpleX Chat Ltd and non-profit entities | Product-first for standard; standards-first for core |
+| Decentralized governance | Future | TBD (DAO research ongoing) | Standards-first |
+
+### Current: product-first development
+
+SimpleX protocols currently follow a product-first development process: requirements drive code, code drives specification. RFCs are written as design proposals before implementation, but implementation details are figured out in code. Consolidated protocol specifications in `protocol/` are then amended to match the implementation.
+
+This process is governed by SimpleX Chat Ltd as the IP Holding Party under the Consortium Agreement.
+
+Any Specification Author (as defined in the Consortium Agreement) may propose RFCs. Acceptance and standardization decisions are made by SimpleX Chat Ltd during the current product-first phase.
+
+### Standard vs Core specifications
+
+The distinction between standard and core maps directly to the two levels of IP governance in the Consortium Agreement, and reflects the difference between product-first and standards-first development:
+
+**Standard** — Licensed IP, not yet under consortium governance. Governed by the company.
+
+All contributed protocol specifications are Licensed IP under the Consortium Agreement. Standard specifications follow product-first development: the company can evolve them with product needs, and they must be maintained on every code change that affects protocol behavior.
+
+Standard specifications live in `rfcs/standard/` and `protocol/`.
+
+**Core** — Governed IP, governed by the consortium.
+
+A subset of standard specifications will be designated as Core IP under the Consortium Agreement. Core specifications will follow standards-first development: specification changes must be agreed via Governing Decision before code changes.
+
+This is a legally binding commitment. Once Licensed IP is included in Core IP, the company that owns the code cannot unilaterally change it — even though they own the code, the Consortium Agreement requires a Governing Decision for any change to Core IP. This protects the fundamental properties of the network (privacy, security, decentralization) from unilateral modification by any single party.
+
+The designation of specific specifications as Core IP is itself a Governing Decision that requires Consortium vote. The transition will happen incrementally as protocols stabilize — the governance ratchet ensures that each designation is irreversible.
+
+The exact mechanism for distinguishing core from standard within the RFC and protocol folder structure is TBD — it will be decided as the first protocols are designated as Core IP.
+
+### Future: standards-first development
+
+As more protocols are designated as Core IP, development naturally transitions to a standards-first process for a growing portion of the protocol suite. The governance ratchet ensures this transition is gradual and irreversible — each protocol that becomes core gains the protection of consortium governance permanently, while remaining standard protocols continue to evolve at product pace.
+
+## Current state
+
+| Location | Contents | Count |
+|----------|----------|-------|
+| `protocol/` | Consolidated specs (SMP v19, Agent v7, XFTP v3, XRCP v1, NTF v3, PQDR v1) | 6 specs + overview |
+| `rfcs/` root | Active draft proposals | 10 |
+| `rfcs/done/` | Implemented, not yet verified | 1 (+10 sub-RFCs) |
+| `rfcs/standard/` | Verified against implementation | 31 |
+| `rfcs/rejected/` | Draft proposals not accepted | 7 |

rfcs/done/2026-01-30-send-file-page/2026-01-31-xftp-web-server-changes.md

@@ -0,0 +1,154 @@
+# XFTP Router: SNI, CORS, and Web Support
+
+Implementation details for Phase 3 of `rfcs/2026-01-30-send-file-page.md` (sections 6.1-6.4).
+
+## 1. Overview
+
+The XFTP router is extended to support web browser clients by:
+
+1. **SNI-based TLS certificate switching** — Present a CA-issued web certificate (e.g., Let's Encrypt) to browsers, while continuing to present the self-signed XFTP identity certificate to native XFTP clients.
+2. **CORS headers** — Add CORS response headers on SNI connections so browsers allow cross-origin XFTP requests.
+3. **Configuration** — `[WEB]` INI section for HTTPS cert/key paths; opt-in (commented out by default).
+
+Web handshake (challenge-response identity proof, §6.3 of parent RFC) is not yet implemented and will be added separately.
+
+## 2. SNI Certificate Switching
+
+### 2.1 Reusing the SMP Pattern
+
+The SMP router already implements SNI-based certificate switching via `TLSServerCredential` and `runTransportServerState_` (see `rfcs/2024-09-15-shared-port.md`). The XFTP router applies the same pattern with one key difference: both native and web XFTP clients use HTTP/2 transport, whereas SMP switches between raw SMP protocol and HTTP entirely.
+
+### 2.2 Approach
+
+When `httpServerCreds` is configured, the XFTP router bypasses `runHTTP2Server` and uses `runTransportServerState_` directly to obtain the per-connection `sniUsed` flag. It then sets up HTTP/2 manually on each TLS connection using `withHTTP2` (same internals as `runHTTP2ServerWith_`). The `sniUsed` flag is captured in the closure and shared by all HTTP/2 requests on that connection.
+
+When `httpServerCreds` is absent, the existing `runHTTP2Server` path is unchanged.
+
+```
+Native client (no SNI)  ──TLS──> XFTP identity cert ──HTTP/2──> processRequest (no CORS)
+Browser client (SNI)    ──TLS──> Web CA cert        ──HTTP/2──> processRequest (+ CORS)
+```
+
+### 2.3 Certificate Chain
+
+The web certificate file (e.g., `web.crt`) must contain the full chain: leaf certificate followed by the signing CA certificate. `loadServerCredential` uses `T.credentialLoadX509Chain` which reads all PEM blocks from the file.
+
+The client validates the chain by comparing `idCert` fingerprint (the CA cert, second in the 2-cert chain) against the known `keyHash`. This is the same validation as for XFTP identity certificates — the CA that signed the web cert must match the XFTP router's identity.
+
+## 3. CORS Support
+
+### 3.1 Design
+
+CORS headers are only added when both conditions are true:
+- `addCORSHeaders` is `True` in `TransportServerConfig` (set in XFTP `Main.hs`)
+- `sniUsed` is `True` for the current TLS connection
+
+This ensures native clients never see CORS headers.
+
+### 3.2 Response Headers
+
+All POST responses on SNI connections include:
+```
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: *
+```
+
+### 3.3 OPTIONS Preflight
+
+OPTIONS requests are intercepted at the HTTP/2 dispatch level, before `processRequest`. This is necessary because `processRequest` rejects bodies that don't match `xftpBlockSize`.
+
+Preflight response:
+```
+HTTP/2 200
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: POST, OPTIONS
+Access-Control-Allow-Headers: *
+Access-Control-Max-Age: 86400
+```
+
+### 3.4 Security
+
+`Access-Control-Allow-Origin: *` is safe because:
+- All XFTP commands require Ed25519 authentication (per-packet keys from file description).
+- No cookies or browser credentials are involved.
+- File content is end-to-end encrypted.
+
+## 4. Configuration
+
+### 4.1 INI Template
+
+```ini
+[WEB]
+# cert: /etc/opt/simplex-xftp/web.crt
+# key: /etc/opt/simplex-xftp/web.key
+```
+
+Commented out by default — web support is opt-in.
+
+### 4.2 Behavior
+
+- `[WEB]` section not configured: silently ignored, router operates normally for native clients only.
+- `[WEB]` section configured with valid cert/key paths: SNI + CORS enabled.
+- `[WEB]` section configured with missing cert files: warning + continue (non-fatal, unlike SMP router where it is fatal).
+
+## 5. Files Modified
+
+### 5.1 `src/Simplex/Messaging/Transport/Server.hs`
+
+Added `addCORSHeaders :: Bool` field to `TransportServerConfig`. Updated `mkTransportServerConfig` to accept the new parameter. All existing SMP call sites pass `False`.
+
+### 5.2 `src/Simplex/Messaging/Transport/HTTP2/Server.hs`
+
+- Extracted `expireInactiveClient` from `runHTTP2ServerWith_`'s `where` clause to a module-level function.
+- Parameterized `runHTTP2ServerWith_`: setup type changed from `((TLS p -> IO ()) -> a)` to `(((Bool, TLS p) -> IO ()) -> a)`, callback from `HTTP2ServerFunc` to `Bool -> HTTP2ServerFunc`. The `Bool` is the per-connection `sniUsed` flag, threaded through `H.run` to the callback.
+- Extended `runHTTP2Server` with `Maybe T.Credential` parameter for SNI web certificate. Its setup uses `runTransportServerState_` with `TLSServerCredential`, which naturally provides `(sniUsed, tls)` pairs matching the new `runHTTP2ServerWith_` setup type.
+- Adapted `runHTTP2ServerWith` (client-side HTTP/2, no SNI): wraps its setup to inject `(False, tls)` and its callback with `const`.
+- Updated `getHTTP2Server` (test helper) to pass `Nothing` for httpCreds.
+
+### 5.3 `src/Simplex/FileTransfer/Server/Env.hs`
+
+- Added `httpCredentials :: Maybe ServerCredentials` to `XFTPServerConfig`.
+- Added `httpServerCreds :: Maybe T.Credential` to `XFTPEnv`.
+- `newXFTPServerEnv` loads HTTP credentials when configured.
+
+### 5.4 `src/Simplex/FileTransfer/Server/Main.hs`
+
+- Added `[WEB]` section to INI template.
+- Added `httpCredentials` parsing from INI `[WEB]` section (`cert` and `key` fields).
+- Set `addCORSHeaders = isJust httpCredentials_` in transport config (conditional on web cert presence).
+
+### 5.5 `src/Simplex/FileTransfer/Server.hs`
+
+Core server changes:
+
+- `runServer` calls `runHTTP2Server` with `httpCreds_` and a `\sniUsed -> handleRequest (sniUsed && addCORSHeaders transportConfig)` callback. TLS params are `defaultSupportedParamsHTTPS` when web creds present, `defaultSupportedParams` otherwise. SNI routing, HTTP/2 setup, and client expiration are handled inside `runHTTP2Server`.
+
+- `XFTPTransportRequest` carries `addCORS :: Bool` field, threaded through to `sendXFTPResponse`.
+
+- `sendXFTPResponse` conditionally includes CORS headers based on `addCORS`.
+
+- OPTIONS requests on SNI connections return CORS preflight headers before reaching `processRequest`.
+
+- Helper functions: `corsHeaders` (response headers), `corsPreflightHeaders` (preflight headers).
+
+### 5.6 `tests/XFTPClient.hs`
+
+- Added `httpCredentials = Nothing` to `testXFTPServerConfig`.
+- Added `testXFTPServerConfigSNI` with web cert config and `addCORSHeaders = True`.
+- Added `withXFTPServerSNI` helper.
+
+### 5.7 `tests/XFTPServerTests.hs`
+
+Added SNI and CORS tests as a subsection within `xftpServerTests` (6 tests):
+
+1. **SNI cert selection** — Connect with SNI + `h2` ALPN, verify RSA web certificate is presented.
+2. **Non-SNI cert selection** — Connect without SNI + `xftp/1` ALPN, verify Ed448 XFTP certificate is presented.
+3. **CORS headers** — SNI POST request includes `Access-Control-Allow-Origin: *` and `Access-Control-Expose-Headers: *`.
+4. **OPTIONS preflight** — SNI OPTIONS request returns all CORS preflight headers.
+5. **No CORS without SNI** — Non-SNI POST request has no CORS headers.
+6. **Data packet delivery** — Full XFTP data packet upload/download through SNI-enabled router verifying no regression.
+
+## 6. Remaining Work
+
+- **Web handshake** (§6.3 of parent RFC): Challenge-response identity proof for SNI connections. The router detects web clients via the `sniUsed` flag and expects a 32-byte challenge in the first POST body (non-empty, unlike standard handshake). Response includes full cert chain + signature over `(challenge ++ sessionId)`.
+- **Static page serving** (§6.5 of parent RFC): Optional serving of the web page HTML/JS bundle on GET requests.

rfcs/done/2026-01-30-send-file-page/2026-02-02-xftp-web-handshake.md

@@ -0,0 +1,246 @@
+# Web Handshake — Challenge-Response Identity Proof
+
+RFC §6.3: Router proves XFTP identity to web clients independently of TLS CA infrastructure.
+
+## 1. Protocol
+
+**Standard handshake** (unchanged):
+```
+Client → empty POST                                        → Server
+Server → padded {vRange, sessionId, authPubKey, Nothing}    → Client
+Client → padded {version, keyHash, Nothing}                 → Server
+Server → empty                                              → Client
+```
+
+**Web handshake** (SNI connection, non-empty hello):
+```
+Client → padded {32 random bytes}                                → Server
+Server → padded {vRange, sessionId, authPubKey, Just sigBytes}   → Client
+  sigBytes = signatureBytes(sign(identityLeafKey, challenge <> sessionId))
+Client validates:
+  1. chainIdCaCerts(authPubKey.certChain) → CCValid {leafCert, idCert}
+  2. SHA-256(idCert) == keyHash   (server identity)
+  3. verify(leafCert.pubKey, sigBytes, challenge <> sessionId)  (challenge-response)
+  4. verify(leafCert.pubKey, signedPubKey.signature, signedPubKey.objectDer)  (DH key auth)
+Client → padded {version, keyHash, Just challenge}               → Server
+Server verifies: echoed challenge == stored challenge from step 1
+Server → empty                                                   → Client
+```
+
+**Detection**: `sniUsed` per-connection flag. Non-empty hello allowed only when `sniUsed`. Empty hello with SNI → standard handshake.
+
+**Why both steps 3 and 4**: Native clients verify `signedPubKey` using the TLS peer certificate (`serverKey` from `getServerVerifyKey`), which is the XFTP identity cert in non-SNI connections — TLS provides this binding. Web clients cannot access TLS peer certificate data (browser API limitation; TLS presents the web CA cert but provides no API to extract it). So web clients must verify at the application layer using `authPubKey.certChain`, which always contains the XFTP identity chain regardless of which cert TLS used. Step 3 proves the router holds its identity key *right now* (freshness via random challenge). Step 4 proves the DH session key was signed by the identity key holder (prevents MITM key substitution). Together they give web clients some assurance native clients get from TLS, except channel binding for commands.
+
+## 2. Type Changes — `src/Simplex/FileTransfer/Transport.hs`
+
+### `XFTPServerHandshake` (line 114)
+
+Add field: `webIdentityProof :: Maybe ByteString` — raw Ed448 signature bytes (114 bytes), or `Nothing` for standard handshake. No record needed — the cert chain is already in `authPubKey.certChain`.
+
+### `Encoding XFTPServerHandshake` (line 136)
+
+- `smpEncode`: append `smpEncode webIdentityProof`
+- `smpP`: `Tail compat`, if non-empty `eitherToMaybe $ smpDecode compat`
+
+Backward compat: old clients ignore via `Tail _compat`; new client + old server → empty compat → `Nothing`.
+
+### `XFTPClientHandshake` (line 121)
+
+Add field: `webChallenge :: Maybe ByteString`
+
+### `Encoding XFTPClientHandshake` (line 128)
+
+Same `Tail compat` pattern as server handshake.
+
+### Export list
+
+Both types use `(..)` export — new fields auto-exported.
+
+## 3. Router Changes — `src/Simplex/FileTransfer/Server.hs`
+
+### `XFTPTransportRequest` (line 88)
+
+Add field: `sniUsed :: SNICredentialUsed` (`Bool` from `Transport.Server`). Add import.
+
+### `Handshake` (line 117)
+
+`HandshakeSent C.PrivateKeyX25519` → `HandshakeSent C.PrivateKeyX25519 (Maybe ByteString)` — stores 32-byte web challenge or `Nothing`.
+
+### `runServer` handler (line 145–161)
+
+- Pass `sniUsed` into request construction (line 154)
+- SNI-first routing: when `sniUsed`, always route to `xftpServerHandshakeV1` (web ALPN `h2` would otherwise fall to `_` catch-all)
+
+### `xftpServerHandshakeV1` (line 162)
+
+- Destructure `sniUsed` from request
+- Match `HandshakeSent pk challenge_` → `processClientHandshake pk challenge_`
+
+### `processHello` (line 171)
+
+- Branch `(sniUsed, B.null bodyHead)`:
+  - `(_, True)` → standard: `challenge_ = Nothing`
+  - `(True, False)` → web: unpad, verify 32 bytes, `challenge_ = Just`
+  - `(False, False)` → `throwE HANDSHAKE`
+- Store: `HandshakeSent pk challenge_`
+- Compute: `webIdentityProof = C.signatureBytes . C.sign serverSignKey . (<> sessionId) <$> challenge_`
+- Construct `XFTPServerHandshake` with `webIdentityProof`
+
+### `processClientHandshake` (line 183)
+
+- Accept `challenge_` parameter
+- Decode `webChallenge` from `XFTPClientHandshake`
+- Add: `unless (challenge_ == webChallenge) $ throwE HANDSHAKE`
+  (standard: both `Nothing` → passes)
+
+## 4. Native Client — `src/Simplex/FileTransfer/Client.hs`
+
+### `xftpClientHandshakeV1` (line 142)
+
+Add `webChallenge = Nothing` in `sendClientHandshake` call.
+
+No other changes — parser handles new fields via `Tail`, native client ignores `webIdentityProof`.
+
+## 5. TypeScript Changes (DONE except Ed448)
+
+Sections 5.1 and 5.2 are implemented. Section 5.3 needs Ed448 support.
+
+## 10. Ed448 Support via `@noble/curves`
+
+**Problem**: Production servers use Ed448 certificates (default). `identity.ts` only supports Ed25519 via libsodium. libsodium has no Ed448 support and never will.
+
+**Solution**: Add `@noble/curves` dependency for Ed448 verification only. All other crypto stays with libsodium.
+
+### 10.1 `xftp-web/package.json` — Add dependency
+
+```json
+"dependencies": {
+  "libsodium-wrappers-sumo": "^0.7.13",
+  "@noble/curves": "^1.9.7"
+}
+```
+
+Use v1.x (supports both CJS and ESM). v2.x is ESM-only with `.js` extension requirement.
+
+### 10.2 `xftp-web/src/crypto/keys.ts` — Ed448 DER constants and decode
+
+Add Ed448 SPKI DER prefix (12 bytes, same prefix length as Ed25519):
+```
+30 43 30 05 06 03 2b 65 71 03 3a 00
+```
+
+| Property | Ed25519 | Ed448 |
+|----------|---------|-------|
+| OID | `2b 65 70` | `2b 65 71` |
+| SPKI prefix | `30 2a ...` | `30 43 ...` |
+| Raw key size | 32 bytes | 57 bytes |
+| SPKI total | 44 bytes | 69 bytes |
+| Signature size | 64 bytes | 114 bytes |
+
+New functions:
+- `decodePubKeyEd448(der: Uint8Array): Uint8Array` — 69 bytes → 57 bytes raw
+- `encodePubKeyEd448(raw: Uint8Array): Uint8Array` — 57 bytes → 69 bytes DER
+- `verifyEd448(publicKey: Uint8Array, sig: Uint8Array, msg: Uint8Array): boolean` — uses `ed448.verify(sig, msg, publicKey)` from `@noble/curves/ed448`
+
+Note: `@noble/curves` parameter order is `(signature, message, publicKey)`, not `(publicKey, signature, message)`.
+
+### 10.3 `xftp-web/src/crypto/identity.ts` — Algorithm-agnostic verification
+
+Replace `extractCertEd25519Key` + hardcoded Ed25519 `verify` with algorithm detection:
+
+1. `extractCertPublicKeyInfo(certDer)` → SPKI DER (already exists, works for any algorithm)
+2. Detect algorithm from SPKI: byte at offset 8 is `0x70` (Ed25519) or `0x71` (Ed448)
+3. Extract raw key with appropriate decoder
+4. Verify signatures with appropriate function
+
+```typescript
+type CertKeyAlgorithm = 'ed25519' | 'ed448'
+
+function detectKeyAlgorithm(spki: Uint8Array): CertKeyAlgorithm {
+  if (spki.length === 44 && spki[8] === 0x70) return 'ed25519'
+  if (spki.length === 69 && spki[8] === 0x71) return 'ed448'
+  throw new Error("unsupported certificate key algorithm")
+}
+```
+
+`verifyIdentityProof` changes:
+- Extract SPKI from leaf cert
+- Detect algorithm → choose `decodePubKeyEd25519`/`decodePubKeyEd448` and `verify`/`verifyEd448`
+- Both challenge signature and DH key signature use the same leaf key + algorithm
+
+Remove `extractCertEd25519Key` (replaced by generic path). Keep `extractCertPublicKeyInfo` (already generic).
+
+### 10.4 `xftp-web/src/protocol/handshake.ts` — Comment update
+
+`SignedKey.signature` comment: "raw Ed25519 signature bytes (64 bytes)" → "raw signature bytes (Ed25519: 64, Ed448: 114)"
+
+### 10.5 Tests — `tests/XFTPWebTests.hs`
+
+**Integration test**: Switch from `withXFTPServerEd25519SNI` (Ed25519 fixtures) to `withXFTPServerSNI` (default Ed448 fixtures). Update fingerprint source from `tests/fixtures/ed25519/ca.crt` to the default `tests/fixtures/ca.crt`.
+
+Optionally add a second integration test with Ed25519 to cover both paths, or rely on existing unit tests for Ed25519 coverage.
+
+### 10.6 Implementation order
+
+1. `npm install @noble/curves` in `xftp-web/`
+2. `keys.ts` — Ed448 constants, decode, encode, verifyEd448
+3. `identity.ts` — algorithm detection, generic verification
+4. `handshake.ts` — comment fix
+5. `XFTPWebTests.hs` — switch integration test to Ed448
+6. Build TS + run all tests
+
+## 6. Haskell Integration Test — `tests/XFTPServerTests.hs`
+
+Add `testWebHandshake` to "XFTP SNI and CORS" describe block.
+
+1. `withXFTPServerSNI` — server with web credentials
+2. Connect with SNI + `h2` ALPN
+3. Send padded 32-byte challenge
+4. Decode `XFTPServerHandshake`, assert `webIdentityProof` is `Just`
+5. `chainIdCaCerts` on `authPubKey.certChain` → `CCValid {leafCert, idCert}`
+6. Verify `SHA-256(idCert) == keyHash`
+7. Extract `leafCert` public key, verify challenge signature
+8. Verify `signedPubKey` signature using `leafCert` key (DH key auth)
+9. Send `XFTPClientHandshake` with `webChallenge = Just challenge`
+10. Assert empty response
+
+Imports: `XFTPServerHandshake (..)`, `XFTPClientHandshake (..)`, `ChainCertificates (..)`, `chainIdCaCerts`.
+
+## 7. TS Tests — `tests/XFTPWebTests.hs`
+
+### Unit tests
+
+- **`decodeServerHandshake` with proof**: Haskell-encode with `Just sigBytes`, TS-decode, verify bytes match.
+- **`encodeClientHandshake` with challenge**: TS-encode, compare with Haskell-encoded.
+- **`chainIdCaCerts`**: 2/3/4-cert chains return correct positions.
+- **`caFingerprint` (fixed)**: matches `sha256(idCert)` for 2 and 3-cert chains.
+
+### Integration test
+
+Node.js inline script against `withXFTPServerSNI`:
+1. Connect with SNI via `http2.connect`
+2. Send padded challenge, decode `XFTPServerHandshake` with TS
+3. `verifyIdentityProof` — full chain validation + challenge sig + DH key sig
+4. Send client handshake with echoed challenge
+5. Assert empty response
+
+## 8. Implementation Order
+
+1. `Transport.hs` — `Maybe` fields + encoding instances
+2. `Server.hs` — `sniUsed`, challenge in `Handshake`, `processHello`, `processClientHandshake`, SNI routing
+3. `Client.hs` — `webChallenge = Nothing`
+4. Build: `cabal build --ghc-options -O0`
+5. Run existing SNI/CORS tests
+6. `XFTPServerTests.hs` — `testWebHandshake`
+7. `handshake.ts` — types, decoding, `chainIdCaCerts`, fix `caFingerprint`
+8. `crypto/identity.ts` — Node.js verification functions
+9. `XFTPWebTests.hs` — unit + integration tests
+10. Build TS + run all tests
+
+## 9. Verification
+
+```bash
+cd xftp-web && npm install && npm run build && cd ..
+cabal test --ghc-options=-O0 --test-option='--match=/XFTP/XFTP server/XFTP SNI and CORS/' --test-show-details=streaming
+cabal test --ghc-options=-O0 --test-option='--match=/XFTP Web Client/' --test-show-details=streaming
+```

rfcs/done/2026-01-30-send-file-page/2026-02-03-xftp-web-browser-tests.md

@@ -0,0 +1,208 @@
+# Plan: Browser ↔ Haskell File Transfer Tests
+
+## Table of Contents
+1. Goal
+2. Current State
+3. Implementation
+4. Success Criteria
+5. Files
+6. Order
+
+## 1. Goal
+Run browser upload/download tests in headless Chromium via Vitest, proving fetch-based transport works in real browser environment.
+
+## 2. Current State
+- `client.ts`: Transport abstraction done — http2 for Node, fetch for browser ✓
+- `agent.ts`: Uses `node:crypto` (randomBytes) and `node:zlib` (deflateRawSync/inflateRawSync) — **won't run in browser**
+- `XFTPWebTests.hs`: Cross-language tests exist (Haskell calls TS via Node.js) ✓
+
+## 3. Implementation
+
+### 3.1 Make agent.ts isomorphic
+
+| Current (Node.js only) | Isomorphic replacement |
+|------------------------|------------------------|
+| `import crypto from "node:crypto"` | Remove import |
+| `import zlib from "node:zlib"` | `import pako from "pako"` |
+| `crypto.randomBytes(32)` | `crypto.getRandomValues(new Uint8Array(32))` |
+| `zlib.deflateRawSync(buf)` | `pako.deflateRaw(buf)` |
+| `zlib.inflateRawSync(buf)` | `pako.inflateRaw(buf)` |
+
+Note: `crypto.getRandomValues` available in both browser and Node.js (globalThis.crypto).
+
+### 3.2 Vitest browser mode setup
+
+`package.json` additions:
+```json
+"devDependencies": {
+  "vitest": "^3.0.0",
+  "@vitest/browser": "^3.0.0",
+  "playwright": "^1.50.0",
+  "@types/pako": "^2.0.3"
+},
+"dependencies": {
+  "pako": "^2.1.0"
+}
+```
+
+`vitest.config.ts`:
+```typescript
+import {defineConfig} from 'vitest/config'
+import {readFileSync} from 'fs'
+import {createHash} from 'crypto'
+
+// Compute fingerprint from ca.crt (same as Haskell's loadFileFingerprint)
+const caCert = readFileSync('../tests/fixtures/ca.crt')
+const fingerprint = createHash('sha256').update(caCert).digest('base64url')
+const serverAddr = `xftp://${fingerprint}@localhost:7000`
+
+export default defineConfig({
+  define: {
+    'import.meta.env.XFTP_SERVER': JSON.stringify(serverAddr)
+  },
+  test: {
+    browser: {
+      enabled: true,
+      provider: 'playwright',
+      instances: [{browser: 'chromium'}],
+      headless: true,
+      providerOptions: {
+        launch: {ignoreHTTPSErrors: true}
+      }
+    },
+    globalSetup: './test/globalSetup.ts'
+  }
+})
+```
+
+### 3.3 Server startup
+
+`test/globalSetup.ts`:
+```typescript
+import {spawn, ChildProcess} from 'child_process'
+import {resolve, join} from 'path'
+import {mkdtempSync, writeFileSync, copyFileSync} from 'fs'
+import {tmpdir} from 'os'
+
+let server: ChildProcess | null = null
+
+export async function setup() {
+  const fixtures = resolve(__dirname, '../../tests/fixtures')
+
+  // Create temp directories
+  const cfgDir = mkdtempSync(join(tmpdir(), 'xftp-cfg-'))
+  const logDir = mkdtempSync(join(tmpdir(), 'xftp-log-'))
+  const filesDir = mkdtempSync(join(tmpdir(), 'xftp-files-'))
+
+  // Copy certificates to cfgDir (xftp-server expects ca.crt, server.key, server.crt there)
+  copyFileSync(join(fixtures, 'ca.crt'), join(cfgDir, 'ca.crt'))
+  copyFileSync(join(fixtures, 'server.key'), join(cfgDir, 'server.key'))
+  copyFileSync(join(fixtures, 'server.crt'), join(cfgDir, 'server.crt'))
+
+  // Write INI config file
+  const iniContent = `[STORE_LOG]
+enable: off
+
+[TRANSPORT]
+host: localhost
+port: 7000
+
+[FILES]
+path: ${filesDir}
+
+[WEB]
+cert: ${join(fixtures, 'web.crt')}
+key: ${join(fixtures, 'web.key')}
+`
+  writeFileSync(join(cfgDir, 'file-server.ini'), iniContent)
+
+  // Spawn xftp-server with env vars
+  server = spawn('cabal', ['exec', 'xftp-server', '--', 'start'], {
+    env: {
+      ...process.env,
+      XFTP_SERVER_CFG_PATH: cfgDir,
+      XFTP_SERVER_LOG_PATH: logDir
+    },
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  // Wait for "Listening on port 7000..."
+  await waitForServerReady(server)
+}
+
+export async function teardown() {
+  server?.kill('SIGTERM')
+  await new Promise(r => setTimeout(r, 500))
+}
+
+function waitForServerReady(proc: ChildProcess): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Server start timeout')), 15000)
+    proc.stdout?.on('data', (data: Buffer) => {
+      if (data.toString().includes('Listening on port')) {
+        clearTimeout(timeout)
+        resolve()
+      }
+    })
+    proc.stderr?.on('data', (data: Buffer) => {
+      console.error('[xftp-server]', data.toString())
+    })
+    proc.on('error', reject)
+    proc.on('exit', (code) => {
+      clearTimeout(timeout)
+      if (code !== 0) reject(new Error(`Server exited with code ${code}`))
+    })
+  })
+}
+```
+
+Server env vars (from `apps/xftp-server/Main.hs` + `getEnvPath`):
+- `XFTP_SERVER_CFG_PATH` — directory containing `file-server.ini` and certs (`ca.crt`, `server.key`, `server.crt`)
+- `XFTP_SERVER_LOG_PATH` — directory for logs
+
+### 3.4 Browser test
+
+`test/browser.test.ts`:
+```typescript
+import {test, expect} from 'vitest'
+import {encryptFileForUpload, uploadFile, downloadFile} from '../src/agent.js'
+import {parseXFTPServer} from '../src/protocol/address.js'
+
+const server = parseXFTPServer(import.meta.env.XFTP_SERVER)
+
+test('browser upload + download round-trip', async () => {
+  const data = new Uint8Array(50000)
+  crypto.getRandomValues(data)
+  const encrypted = encryptFileForUpload(data, 'test.bin')
+  const {rcvDescription} = await uploadFile(server, encrypted)
+  const {content} = await downloadFile(rcvDescription)
+  expect(content).toEqual(data)
+})
+```
+
+## 4. Success Criteria
+
+1. `npm run build` — agent.ts compiles without node: imports
+2. `cabal test --test-option='--match=/XFTP Web Client/'` — existing Node.js tests still pass
+3. `npm run test:browser` — browser round-trip test passes in headless Chromium
+
+## 5. Files to Create/Modify
+
+**Modify:**
+- `xftp-web/package.json` — add vitest, @vitest/browser, playwright, pako, @types/pako
+- `xftp-web/src/agent.ts` — replace node:crypto, node:zlib with isomorphic alternatives
+
+**Create:**
+- `xftp-web/vitest.config.ts` — browser mode config
+- `xftp-web/test/globalSetup.ts` — xftp-server lifecycle
+- `xftp-web/test/browser.test.ts` — browser round-trip test
+
+## 6. Order of Implementation
+
+1. **Add pako dependency** — `npm install pako @types/pako`
+2. **Make agent.ts isomorphic** — replace node:crypto, node:zlib
+3. **Verify Node.js tests pass** — `cabal test --test-option='--match=/XFTP Web Client/'`
+4. **Set up Vitest** — add devDeps, create vitest.config.ts
+5. **Create globalSetup.ts** — write INI config, spawn xftp-server
+6. **Write browser test** — upload + download round-trip
+7. **Verify browser test passes** — `npm run test:browser`

rfcs/done/2026-01-30-send-file-page/2026-02-04-xftp-web-browser-transport.md

@@ -0,0 +1,921 @@
+
+# Browser Transport & Web Worker Architecture
+
+## TOC
+
+1. Executive Summary
+2. Transport: fetch() API
+3. Architecture: Environment Abstraction
+4. Web Worker Implementation
+5. OPFS Implementation
+6. Implementation Plan
+7. Testing Strategy
+
+## 1. Executive Summary
+
+Adapt `client.ts` from `node:http2` to `fetch()` API for isomorphic Node.js/browser support. Add environment abstraction layer so the same upload/download pipeline works with or without Web Workers and with or without OPFS. In browsers, crypto runs in a Web Worker to keep UI responsive; in Node.js tests, crypto runs directly.
+
+**Key architectural constraint:** Existing crypto functions (`encryptFile`, `decryptChunks`, etc.) remain unchanged. The abstraction layer wraps them, choosing execution context (direct vs Worker) and storage (memory vs OPFS) based on environment.
+
+**Scope:**
+- Replace `node:http2` with `fetch()` in `client.ts`
+- Add `CryptoBackend` abstraction with three implementations
+- Create Web Worker that calls existing crypto functions
+- Add OPFS storage for large files in browser
+
+**Out of scope:** Web page UI (Phase 5 in main RFC).
+
+## 2. Transport: fetch() API
+
+### 2.1 Current State
+
+`client.ts` uses `node:http2`:
+```typescript
+import http2 from "node:http2"
+const session = http2.connect(url)
+const stream = session.request({':method': 'POST', ':path': '/'})
+stream.write(commandBlock)
+stream.end(chunkData)
+```
+
+### 2.2 Target State
+
+Isomorphic `fetch()` (Node.js 18+ and browsers):
+```typescript
+const response = await fetch(url, {
+  method: 'POST',
+  body: concatStreams(commandBlock, chunkData),
+  duplex: 'half',  // Required for streaming request body
+})
+const reader = response.body!.getReader()
+```
+
+### 2.3 Key Differences
+
+| Aspect | node:http2 | fetch() |
+|--------|-----------|---------|
+| Session management | Explicit `session.connect()` / `session.close()` | Per-request (HTTP/2 connection reuse is automatic) |
+| Streaming upload | `stream.write()` chunks | `ReadableStream` body + `duplex: 'half'` |
+| Streaming download | `stream.on('data')` | `response.body.getReader()` |
+| Connection pooling | Manual | Automatic per origin |
+
+### 2.4 API Changes
+
+```typescript
+// Before (node:http2)
+export interface XFTPClient {
+  session: http2.ClientHttp2Session
+  thParams: THParams
+  server: XFTPServer
+}
+
+// After (fetch)
+export interface XFTPClient {
+  baseUrl: string           // "https://host:port"
+  thParams: THParams
+  server: XFTPServer
+}
+```
+
+`connectXFTP()` performs handshake via fetch, returns `XFTPClient` with `baseUrl`.
+Subsequent commands use `fetch(client.baseUrl, ...)`.
+
+### 2.5 Handshake via fetch()
+
+**TLS session binding:** Multiple fetch() requests to the same origin reuse the HTTP/2 connection, which means they share the same TLS session. The server's `sessionId` (derived from TLS channel binding) remains consistent across the handshake round-trips and subsequent commands.
+
+```typescript
+async function connectXFTP(server: XFTPServer): Promise<XFTPClient> {
+  const baseUrl = `https://${server.host}:${server.port}`
+
+  // Round-trip 1: challenge → server handshake + identity proof
+  const challenge = crypto.getRandomValues(new Uint8Array(32))
+  const req1 = pad(encodeWebClientHello(challenge), xftpBlockSize)
+  const resp1 = await fetch(baseUrl, {method: 'POST', body: req1})
+
+  const reader = resp1.body!.getReader()
+  const serverBlock = await readExactly(reader, xftpBlockSize)
+  const serverHs = decodeServerHandshake(unPad(serverBlock))
+  const proofBody = await readRemaining(reader)
+  verifyIdentityProof(server.keyHash, challenge, serverHs.sessionId, proofBody)
+
+  // Round-trip 2: client handshake → server ack
+  const clientHs = encodeClientHandshake({xftpVersion: 3, keyHash: server.keyHash})
+  const req2 = pad(clientHs, xftpBlockSize)
+  await fetch(baseUrl, {method: 'POST', body: req2})
+
+  return {baseUrl, thParams: {sessionId: serverHs.sessionId, ...}, server}
+}
+```
+
+### 2.6 Command Execution
+
+```typescript
+async function sendXFTPCommand(
+  client: XFTPClient,
+  key: Uint8Array,
+  entityId: Uint8Array,
+  cmd: Uint8Array,
+  chunkData?: Uint8Array
+): Promise<{response: Uint8Array, body?: ReadableStream}> {
+  const block = xftpEncodeAuthTransmission(client.thParams, key, entityId, cmd)
+
+  const reqBody = chunkData
+    ? concatBytes(block, chunkData)
+    : block
+
+  const resp = await fetch(client.baseUrl, {
+    method: 'POST',
+    body: reqBody,
+    duplex: 'half',
+  })
+
+  const reader = resp.body!.getReader()
+  const responseBlock = await readExactly(reader, xftpBlockSize)
+  const parsed = xftpDecodeTransmission(responseBlock)
+
+  // For FGET: remaining body is encrypted chunk
+  const hasMore = await peekReader(reader)
+  return {
+    response: parsed,
+    body: hasMore ? wrapAsStream(reader) : undefined
+  }
+}
+```
+
+## 3. Architecture: Environment Abstraction
+
+### 3.1 Core Principle
+
+**Existing crypto functions remain unchanged.** The functions `encryptFile()`, `decryptChunks()`, `sha512()`, etc. in `crypto/file.ts` and `crypto/digest.ts` are pure computation — they take input bytes and produce output bytes. They have no knowledge of Workers, OPFS, or execution context.
+
+The abstraction layer sits between `agent.ts` (upload/download orchestration) and these crypto functions:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  agent.ts (upload/download orchestration)                            │
+│  - Unchanged logic: encrypt → chunk → upload → build description     │
+│  - Calls CryptoBackend interface, not crypto functions directly      │
+├─────────────────────────────────────────────────────────────────────┤
+│  CryptoBackend interface (env.ts)                                    │
+│  - Abstract interface for encrypt/decrypt/readChunk/writeChunk       │
+│  - Factory function selects implementation based on environment      │
+├──────────────┬──────────────────────┬───────────────────────────────┤
+│ DirectMemory │ WorkerMemory         │ WorkerOPFS                    │
+│ Backend      │ Backend              │ Backend                       │
+│ (Node.js)    │ (Browser, ≤50MB)     │ (Browser, >50MB)              │
+├──────────────┼──────────────────────┼───────────────────────────────┤
+│ Calls crypto │ Posts to Worker,     │ Posts to Worker,              │
+│ functions    │ Worker calls crypto  │ Worker calls crypto,          │
+│ directly     │ functions, returns   │ streams through OPFS          │
+│              │ via postMessage      │                               │
+├──────────────┴──────────────────────┴───────────────────────────────┤
+│  crypto/file.ts, crypto/digest.ts (unchanged)                        │
+│  - encryptFile(), decryptChunks(), sha512(), etc.                    │
+│  - Pure functions, no environment dependencies                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 CryptoBackend Interface
+
+```typescript
+// env.ts
+export interface CryptoBackend {
+  // Encrypt file, store result (in memory or OPFS depending on backend)
+  encrypt(
+    data: Uint8Array,
+    fileName: string,
+    onProgress?: (done: number, total: number) => void
+  ): Promise<EncryptResult>
+
+  // Decrypt from stored encrypted data
+  decrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    size: number,
+    onProgress?: (done: number, total: number) => void
+  ): Promise<DecryptResult>
+
+  // Read chunk from stored encrypted data (for upload)
+  readChunk(offset: number, size: number): Promise<Uint8Array>
+
+  // Write chunk to storage (for download, before decrypt)
+  writeChunk(data: Uint8Array, offset: number): Promise<void>
+
+  // Clean up temporary storage
+  cleanup(): Promise<void>
+}
+
+export interface EncryptResult {
+  digest: Uint8Array      // SHA-512 of encrypted data
+  key: Uint8Array         // Generated encryption key
+  nonce: Uint8Array       // Generated nonce
+  chunkSizes: number[]    // Chunk sizes for upload
+  totalSize: number       // Total encrypted size
+}
+
+export interface DecryptResult {
+  header: FileHeader      // Extracted file header (fileName, etc.)
+  content: Uint8Array     // Decrypted file content
+}
+```
+
+### 3.3 Backend Implementations
+
+**DirectMemoryBackend** (Node.js):
+```typescript
+class DirectMemoryBackend implements CryptoBackend {
+  private encryptedData: Uint8Array | null = null
+
+  async encrypt(data: Uint8Array, fileName: string, onProgress?): Promise<EncryptResult> {
+    const key = randomBytes(32)
+    const nonce = randomBytes(24)
+    // Call existing crypto function directly
+    this.encryptedData = encryptFile(data, fileName, key, nonce, onProgress)
+    const digest = sha512(this.encryptedData)
+    const chunkSizes = prepareChunkSizes(this.encryptedData.length)
+    return { digest, key, nonce, chunkSizes, totalSize: this.encryptedData.length }
+  }
+
+  async decrypt(key, nonce, size, onProgress): Promise<DecryptResult> {
+    // Call existing crypto function directly
+    return decryptChunks([this.encryptedData!], key, nonce, size, onProgress)
+  }
+
+  async readChunk(offset: number, size: number): Promise<Uint8Array> {
+    return this.encryptedData!.slice(offset, offset + size)
+  }
+
+  async writeChunk(data: Uint8Array, offset: number): Promise<void> {
+    if (!this.encryptedData) this.encryptedData = new Uint8Array(offset + data.length)
+    this.encryptedData.set(data, offset)
+  }
+
+  async cleanup(): Promise<void> {
+    this.encryptedData = null
+  }
+}
+```
+
+**WorkerMemoryBackend** and **WorkerOPFSBackend** are similar but post messages to a Web Worker instead of calling crypto directly. The Worker then calls the same `encryptFile()`, `decryptChunks()` functions. See §4 for Worker implementation details.
+
+### 3.4 Factory Function
+
+```typescript
+// env.ts
+export function createCryptoBackend(fileSize: number): CryptoBackend {
+  const hasWorker = typeof Worker !== 'undefined'
+  const hasOPFS = typeof navigator?.storage?.getDirectory !== 'undefined'
+  const isLargeFile = fileSize > 50 * 1024 * 1024
+
+  if (hasWorker && hasOPFS && isLargeFile) {
+    return new WorkerOPFSBackend()   // Browser + large file
+  } else if (hasWorker) {
+    return new WorkerMemoryBackend() // Browser + small file
+  } else {
+    return new DirectMemoryBackend() // Node.js
+  }
+}
+```
+
+### 3.5 Usage in agent.ts
+
+```typescript
+// agent.ts - upload orchestration (simplified)
+export async function uploadFile(
+  server: XFTPServer,
+  fileData: Uint8Array,
+  fileName: string,
+  onProgress?: ProgressCallback
+): Promise<string> {
+  // Create backend based on environment
+  const backend = createCryptoBackend(fileData.length)
+
+  try {
+    // Encrypt (runs in Worker in browser, directly in Node)
+    const enc = await backend.encrypt(fileData, fileName, onProgress)
+
+    // Upload chunks (same code regardless of backend)
+    const client = await connectXFTP(server)
+    const sentChunks = []
+    let offset = 0
+    for (const size of enc.chunkSizes) {
+      const chunk = await backend.readChunk(offset, size)
+      const sent = await uploadChunk(client, chunk, enc.digest)
+      sentChunks.push(sent)
+      offset += size
+    }
+
+    // Build description and URI
+    const fd = buildFileDescription(enc, sentChunks)
+    return encodeFileDescriptionURI(fd)
+  } finally {
+    await backend.cleanup()
+  }
+}
+```
+
+The key point: `uploadFile()` logic is identical regardless of whether crypto runs in a Worker or directly. The `CryptoBackend` abstraction hides that detail.
+
+### 3.6 Why This Matters for Testing
+
+- **Layer 1 tests** (per-function): Call `encryptFile()`, `decryptChunks()` directly via Node — unchanged
+- **Layer 2 tests** (full flow): Call `uploadFile()`, `downloadFile()` in Node — uses `DirectMemoryBackend`, same code path as browser except for Worker
+- **Layer 3 tests** (browser): Call `uploadFile()`, `downloadFile()` in Playwright — uses `WorkerMemoryBackend` or `WorkerOPFSBackend`
+
+All three layers exercise the same crypto functions. The only difference is execution context.
+
+## 4. Web Worker Implementation
+
+### 4.1 Why Web Worker
+
+File encryption (XSalsa20-Poly1305) is sequential and CPU-bound:
+- 100 MB file ≈ 1-2 seconds of continuous computation
+- Running on main thread blocks UI (no progress updates, frozen page)
+- Chunking into async microtasks adds complexity and still causes jank
+
+Web Worker runs crypto in parallel thread. Main thread stays responsive.
+
+### 4.2 Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Main Thread                                                 │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │ UI (upload/ │  │ Progress    │  │ Network (fetch)     │  │
+│  │ download)   │  │ display     │  │                     │  │
+│  └──────┬──────┘  └──────▲──────┘  └──────────▲──────────┘  │
+│         │                │                    │              │
+│         │ postMessage    │ progress          │ encrypted    │
+│         ▼                │ events            │ chunks       │
+├─────────────────────────────────────────────────────────────┤
+│  Web Worker                                                  │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ Crypto Pipeline                                          ││
+│  │ - encryptFile() with progress callbacks                  ││
+│  │ - decryptChunks() with progress callbacks                ││
+│  │ - OPFS read/write for temp storage                       ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 4.3 Message Protocol
+
+**Main → Worker:**
+
+```typescript
+type WorkerRequest =
+  // Encrypt file, store result in OPFS (large) or memory (small)
+  | {type: 'encrypt', file: File, fileName: string, useOPFS: boolean}
+  // Read encrypted chunk from OPFS for upload
+  | {type: 'readChunk', offset: number, size: number}
+  // Write downloaded chunk to OPFS for later decryption
+  | {type: 'writeChunk', data: ArrayBuffer, offset: number}
+  // Decrypt from OPFS or provided chunks
+  | {type: 'decrypt', key: Uint8Array, nonce: Uint8Array, size: number, chunks?: ArrayBuffer[]}
+  // Delete OPFS temp files
+  | {type: 'cleanup'}
+  | {type: 'cancel'}
+```
+
+**Worker → Main:**
+
+```typescript
+type WorkerResponse =
+  | {type: 'progress', phase: 'encrypt' | 'decrypt', done: number, total: number}
+  // For OPFS: encData is empty, data lives in OPFS temp file
+  | {type: 'encrypted', encData: ArrayBuffer | null, digest: Uint8Array, key: Uint8Array, nonce: Uint8Array, chunkSizes: number[]}
+  | {type: 'chunk', data: ArrayBuffer}  // Response to readChunk
+  | {type: 'chunkWritten'}              // Response to writeChunk
+  | {type: 'decrypted', header: FileHeader, content: ArrayBuffer}
+  | {type: 'cleaned'}                   // Response to cleanup
+  | {type: 'error', message: string}
+```
+
+### 4.4 Worker Implementation
+
+```typescript
+// crypto.worker.ts
+import {encryptFile, encryptFileStreaming, decryptChunks, decryptFromOPFS} from './crypto/file.js'
+import {sha512} from './crypto/digest.js'
+import {prepareChunkSizes} from './protocol/chunks.js'
+
+let opfsHandle: FileSystemSyncAccessHandle | null = null
+
+self.onmessage = async (e: MessageEvent<WorkerRequest>) => {
+  const req = e.data
+
+  if (req.type === 'encrypt') {
+    const key = crypto.getRandomValues(new Uint8Array(32))
+    const nonce = crypto.getRandomValues(new Uint8Array(24))
+
+    if (req.useOPFS) {
+      // Large file: stream through OPFS to avoid memory pressure
+      const root = await navigator.storage.getDirectory()
+      const fileHandle = await root.getFileHandle('encrypted-temp', {create: true})
+      opfsHandle = await fileHandle.createSyncAccessHandle()
+
+      // Stream encrypt: read 64KB from File, encrypt, write to OPFS
+      const digest = await encryptFileStreaming(
+        req.file,
+        req.fileName,
+        key,
+        nonce,
+        opfsHandle,
+        (done, total) => self.postMessage({type: 'progress', phase: 'encrypt', done, total})
+      )
+
+      const encSize = opfsHandle.getSize()
+      const chunkSizes = prepareChunkSizes(encSize)
+
+      self.postMessage({
+        type: 'encrypted',
+        encData: null,  // Data in OPFS, not memory
+        digest, key, nonce, chunkSizes
+      })
+    } else {
+      // Small file: in-memory is fine
+      const source = new Uint8Array(await req.file.arrayBuffer())
+      const encData = encryptFile(source, req.fileName, key, nonce, (done, total) => {
+        self.postMessage({type: 'progress', phase: 'encrypt', done, total})
+      })
+
+      const digest = sha512(encData)
+      const chunkSizes = prepareChunkSizes(encData.length)
+
+      self.postMessage({
+        type: 'encrypted',
+        encData: encData.buffer,
+        digest, key, nonce, chunkSizes
+      }, [encData.buffer])
+    }
+  }
+
+  if (req.type === 'readChunk') {
+    // Read chunk from OPFS for upload
+    const chunk = new Uint8Array(req.size)
+    opfsHandle!.read(chunk, {at: req.offset})
+    self.postMessage({type: 'chunk', data: chunk.buffer}, [chunk.buffer])
+  }
+
+  if (req.type === 'writeChunk') {
+    // Write downloaded chunk to OPFS
+    if (!opfsHandle) {
+      const root = await navigator.storage.getDirectory()
+      const fileHandle = await root.getFileHandle('download-temp', {create: true})
+      opfsHandle = await fileHandle.createSyncAccessHandle()
+    }
+    opfsHandle.write(new Uint8Array(req.data), {at: req.offset})
+    self.postMessage({type: 'chunkWritten'})
+  }
+
+  if (req.type === 'decrypt') {
+    let result
+    if (req.chunks) {
+      // Small file: chunks provided in memory
+      const chunks = req.chunks.map(b => new Uint8Array(b))
+      result = decryptChunks(chunks, req.key, req.nonce, req.size, (done, total) => {
+        self.postMessage({type: 'progress', phase: 'decrypt', done, total})
+      })
+    } else {
+      // Large file: read from OPFS
+      result = decryptFromOPFS(opfsHandle!, req.key, req.nonce, req.size, (done, total) => {
+        self.postMessage({type: 'progress', phase: 'decrypt', done, total})
+      })
+    }
+
+    self.postMessage({
+      type: 'decrypted',
+      header: result.header,
+      content: result.content.buffer
+    }, [result.content.buffer])
+  }
+
+  if (req.type === 'cleanup') {
+    if (opfsHandle) {
+      opfsHandle.close()
+      opfsHandle = null
+    }
+    const root = await navigator.storage.getDirectory()
+    try { await root.removeEntry('encrypted-temp') } catch {}
+    try { await root.removeEntry('download-temp') } catch {}
+    self.postMessage({type: 'cleaned'})
+  }
+}
+```
+
+### 4.5 Main Thread Wrapper
+
+```typescript
+// crypto-worker.ts (main thread)
+export class CryptoWorker {
+  private worker: Worker
+  private pending: Map<string, {resolve: Function, reject: Function}> = new Map()
+  private onProgress?: (done: number, total: number) => void
+
+  constructor() {
+    this.worker = new Worker(new URL('./crypto.worker.js', import.meta.url), {type: 'module'})
+    this.worker.onmessage = (e) => this.handleMessage(e.data)
+  }
+
+  async encrypt(file: File, onProgress?: (done: number, total: number) => void): Promise<EncryptedFileInfo> {
+    const useOPFS = file.size > 50 * 1024 * 1024  // 50 MB threshold
+    return new Promise((resolve, reject) => {
+      this.pending.set('encrypt', {resolve, reject})
+      this.onProgress = onProgress
+      this.worker.postMessage({type: 'encrypt', file, fileName: file.name, useOPFS})
+    })
+  }
+
+  async decrypt(
+    chunks: Uint8Array[],
+    key: Uint8Array,
+    nonce: Uint8Array,
+    size: number,
+    onProgress?: (done: number, total: number) => void
+  ): Promise<DownloadResult> {
+    return new Promise((resolve, reject) => {
+      this.pending.set('decrypt', {resolve, reject})
+      this.onProgress = onProgress
+      this.worker.postMessage({
+        type: 'decrypt',
+        chunks: chunks.map(c => c.buffer),
+        key, nonce, size
+      }, chunks.map(c => c.buffer))
+    })
+  }
+
+  private handleMessage(msg: WorkerResponse) {
+    if (msg.type === 'progress') {
+      this.onProgress?.(msg.done, msg.total)
+    } else if (msg.type === 'encrypted') {
+      this.pending.get('encrypt')?.resolve({
+        encData: msg.encData ? new Uint8Array(msg.encData) : null,  // null when using OPFS
+        digest: msg.digest,
+        key: msg.key,
+        nonce: msg.nonce,
+        chunkSizes: msg.chunkSizes
+      })
+    } else if (msg.type === 'decrypted') {
+      this.pending.get('decrypt')?.resolve({
+        header: msg.header,
+        content: new Uint8Array(msg.content)
+      })
+    } else if (msg.type === 'error') {
+      // Reject all pending
+      for (const p of this.pending.values()) p.reject(new Error(msg.message))
+    }
+  }
+}
+```
+
+## 5. OPFS Implementation
+
+### 5.1 Purpose
+
+For files approaching 100 MB, holding encrypted data in memory while uploading creates memory pressure. OPFS provides temporary file storage:
+- Write encrypted data to OPFS as it's generated
+- Read chunks from OPFS for upload
+- Delete after upload completes
+
+### 5.2 When to Use
+
+- Files > 50 MB: Use OPFS
+- Files ≤ 50 MB: In-memory (simpler, no OPFS overhead)
+
+Threshold is configurable.
+
+### 5.3 OPFS API
+
+```typescript
+// In Web Worker (synchronous API for performance)
+const root = await navigator.storage.getDirectory()
+const fileHandle = await root.getFileHandle('encrypted-temp', {create: true})
+const accessHandle = await fileHandle.createSyncAccessHandle()
+
+// Write encrypted chunks as they're generated
+accessHandle.write(encryptedChunk, {at: offset})
+
+// Read chunk for upload
+const chunk = new Uint8Array(chunkSize)
+accessHandle.read(chunk, {at: chunkOffset})
+
+// Cleanup
+accessHandle.close()
+await root.removeEntry('encrypted-temp')
+```
+
+### 5.4 Upload Flow with OPFS
+
+```
+1. Main: user drops file
+2. Main → Worker: {type: 'encrypt', file}
+3. Worker:
+   - Create OPFS temp file
+   - Encrypt 64KB at a time, write to OPFS
+   - Post progress every 64KB
+   - Compute digest
+   - Return {digest, key, nonce, chunkSizes} (data stays in OPFS)
+4. Main: for each chunk:
+   - Main → Worker: {type: 'readChunk', offset, size}
+   - Worker: read from OPFS, return chunk
+   - Main: upload chunk via fetch()
+5. Main → Worker: {type: 'cleanup'}
+6. Worker: delete OPFS temp file
+```
+
+### 5.5 Download Flow with OPFS
+
+```
+1. Main: parse URL, get FileDescription
+2. Main: for each chunk:
+   - Download via fetch()
+   - Main → Worker: {type: 'writeChunk', data, offset}
+   - Worker: write to OPFS temp file
+3. Main → Worker: {type: 'decrypt', key, nonce, size}
+4. Worker:
+   - Read from OPFS
+   - Decrypt, verify auth tag
+   - Return {header, content}
+5. Main: trigger browser download
+6. Main → Worker: {type: 'cleanup'}
+```
+
+## 6. Implementation Plan
+
+### 6.1 Phase A: fetch() Transport
+
+**Goal:** Replace `node:http2` with `fetch()` in `client.ts`. All existing Node.js tests pass.
+
+1. Rewrite `connectXFTP()` to use fetch() for handshake
+2. Rewrite `sendXFTPCommand()` to use fetch()
+3. Update `createXFTPChunk`, `uploadXFTPChunk`, `downloadXFTPChunk`, etc.
+4. Remove `node:http2` import
+5. Run existing Haskell integration tests — must pass
+
+**Files:** `client.ts`
+
+### 6.2 Phase B: Environment Abstraction + Web Worker
+
+**Goal:** Add `CryptoBackend` abstraction (§3) so the same code works in Node (direct) and browser (Worker).
+
+1. Create `env.ts` with `CryptoBackend` interface and `createCryptoBackend()` factory (as specified in §3)
+2. Implement `DirectMemoryBackend` for Node.js
+3. Create `crypto.worker.ts` that imports and calls existing crypto functions
+4. Implement `WorkerMemoryBackend` for browser
+5. Update `agent.ts` to use `createCryptoBackend()` instead of direct crypto calls
+6. Existing tests pass (now using `DirectMemoryBackend`)
+
+**Files:** `env.ts`, `crypto.worker.ts`, `agent.ts`
+
+### 6.3 Phase C: OPFS Backend
+
+**Goal:** Large files (>50 MB) use OPFS for temp storage in browser.
+
+1. Implement `WorkerOPFSBackend` — uses OPFS sync API in worker
+2. Add OPFS helpers in worker: read/write to temp file
+3. Factory function now returns `WorkerOPFSBackend` for large files
+4. Same `agent.ts` code works — only backend implementation differs
+
+**Files:** `env.ts`, `crypto.worker.ts`
+
+### 6.4 Phase D: Browser Testing
+
+**Goal:** Verify everything works in real browsers.
+
+1. Create minimal test HTML page
+2. Test upload flow in Chrome, Firefox, Safari
+3. Test download flow
+4. Test progress reporting
+5. Test cancellation
+6. Test error handling (network failure, invalid file)
+
+## 7. Testing Strategy
+
+### 7.1 Test Layers
+
+The `CryptoBackend` abstraction (§3) enables testing at multiple levels without code duplication:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Layer 3: Browser Integration (Playwright)                        │
+│ - Web Worker message passing                                     │
+│ - OPFS read/write                                                │
+│ - Progress UI updates                                            │
+│ - Real browser fetch() with CORS                                 │
+├─────────────────────────────────────────────────────────────────┤
+│ Layer 2: Full Flow (Haskell-driven, Node.js)                     │
+│ - fetch() transport against real xftp-server                     │
+│ - Upload: encrypt → chunk → upload → build description           │
+│ - Download: parse → download → verify → decrypt                  │
+│ - Cross-language: TS upload ↔ Haskell download (and vice versa)  │
+├─────────────────────────────────────────────────────────────────┤
+│ Layer 1: Per-Function (Haskell-driven, Node.js)                  │
+│ - 172 existing tests                                             │
+│ - Byte-identical output vs Haskell functions                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 Layer 1: Per-Function Tests (Existing)
+
+Existing Haskell-driven tests in `XFTPWebTests.hs`. Each test calls a TypeScript function via Node and compares output with Haskell.
+
+```bash
+cabal test --ghc-options -O0 --test-option='--match=/XFTP Web Client/'
+```
+
+All 172 tests must pass. No changes needed for browser transport work.
+
+### 7.3 Layer 2: Full Flow Tests (Node.js + fetch)
+
+Haskell-driven integration tests using Node.js native fetch(). These test the complete upload/download flow without Worker/OPFS.
+
+```haskell
+-- XFTPWebTests.hs (extends existing test file)
+it "fetch transport: upload and download round-trip" $ do
+  withXFTPServer testXFTPServerConfigSNI $ \server -> do
+    -- TypeScript uploads via fetch(), returns URI
+    uri <- jsOut $ callTS "src/agent" "uploadFileTest" serverAddrHex <> testFileHex
+    -- TypeScript downloads via fetch()
+    content <- jsOut $ callTS "src/agent" "downloadFileTest" uriHex
+    content `shouldBe` testFileContent
+
+it "fetch transport: TS upload, Haskell download" $ do
+  withXFTPServer testXFTPServerConfigSNI $ \server -> do
+    uri <- jsOut $ callTS "src/agent" "uploadFileTest" serverAddrHex <> testFileHex
+    -- Haskell agent downloads using existing xftp CLI pattern
+    outPath <- withAgent 1 agentCfg initAgentServers testDB $ \a -> do
+      rfId <- xftpReceiveFile' a 1 uri Nothing
+      waitRfDone a
+    content <- B.readFile outPath
+    content `shouldBe` testFileContent
+```
+
+**What this tests:**
+- fetch() handshake (challenge-response, TLS session binding)
+- fetch() command execution (FNEW, FPUT, FGET, FACK)
+- Streaming request/response bodies
+- Full encrypt → upload → download → decrypt flow
+
+**What this doesn't test:**
+- Web Worker message passing
+- OPFS storage
+- Browser-specific fetch() behavior (CORS preflight, etc.)
+
+### 7.4 Layer 3: Browser Integration Tests (Playwright)
+
+Playwright tests run in real browsers, testing browser-specific functionality.
+
+**Test infrastructure:**
+
+```
+xftp-web/
+├── test/
+│   ├── browser.test.ts      # Playwright test file
+│   └── test-server.ts       # Spawns xftp-server for tests
+└── test-page/
+    ├── index.html           # Minimal test UI
+    └── test-harness.ts      # Exposes test functions to window
+```
+
+**Running browser tests:**
+
+```bash
+cd xftp-web
+npm run test:browser  # Spawns xftp-server, runs Playwright
+```
+
+**Test cases:**
+
+```typescript
+// test/browser.test.ts
+import { test, expect } from '@playwright/test'
+import { spawn } from 'child_process'
+
+let serverProcess: ChildProcess
+
+test.beforeAll(async () => {
+  // Spawn xftp-server with SNI cert for browser TLS
+  serverProcess = spawn('xftp-server', ['start', '-c', 'test-config.ini'])
+  await waitForServer()
+})
+
+test.afterAll(async () => {
+  serverProcess.kill()
+})
+
+test('small file upload/download (in-memory)', async ({ page }) => {
+  await page.goto('/test-page/')
+
+  const result = await page.evaluate(async () => {
+    const data = new Uint8Array(1024 * 1024)  // 1 MB
+    crypto.getRandomValues(data)
+    const file = new File([data], 'small.bin')
+
+    const uri = await window.xftp.uploadFile(file)
+    const downloaded = await window.xftp.downloadFile(uri)
+
+    return {
+      uploadedSize: data.length,
+      downloadedSize: downloaded.length,
+      match: arraysEqual(data, downloaded),
+      usedOPFS: window.xftp.lastUploadUsedOPFS
+    }
+  })
+
+  expect(result.match).toBe(true)
+  expect(result.usedOPFS).toBe(false)  // Small file, no OPFS
+})
+
+test('large file upload/download (OPFS)', async ({ page }) => {
+  await page.goto('/test-page/')
+
+  const result = await page.evaluate(async () => {
+    const data = new Uint8Array(60 * 1024 * 1024)  // 60 MB
+    crypto.getRandomValues(data)
+    const file = new File([data], 'large.bin')
+
+    const uri = await window.xftp.uploadFile(file)
+    const downloaded = await window.xftp.downloadFile(uri)
+
+    return {
+      match: arraysEqual(data, downloaded),
+      usedOPFS: window.xftp.lastUploadUsedOPFS
+    }
+  })
+
+  expect(result.match).toBe(true)
+  expect(result.usedOPFS).toBe(true)  // Large file, used OPFS
+})
+
+test('progress events fire during upload', async ({ page }) => {
+  await page.goto('/test-page/')
+
+  const progressEvents = await page.evaluate(async () => {
+    const events: number[] = []
+    const data = new Uint8Array(10 * 1024 * 1024)  // 10 MB
+    const file = new File([data], 'progress.bin')
+
+    await window.xftp.uploadFile(file, (done, total) => {
+      events.push(done / total)
+    })
+
+    return events
+  })
+
+  expect(progressEvents.length).toBeGreaterThan(1)
+  expect(progressEvents[progressEvents.length - 1]).toBe(1)  // 100% at end
+})
+
+test('Web Worker keeps UI responsive', async ({ page }) => {
+  await page.goto('/test-page/')
+
+  // Start upload and measure main thread responsiveness
+  const result = await page.evaluate(async () => {
+    const data = new Uint8Array(50 * 1024 * 1024)  // 50 MB
+    const file = new File([data], 'responsive.bin')
+
+    let frameCount = 0
+    let uploadDone = false
+
+    // Count animation frames during upload
+    function countFrames() {
+      frameCount++
+      if (!uploadDone) requestAnimationFrame(countFrames)
+    }
+    requestAnimationFrame(countFrames)
+
+    const start = performance.now()
+    await window.xftp.uploadFile(file)
+    uploadDone = true
+    const elapsed = performance.now() - start
+
+    // If main thread was blocked, frameCount would be very low
+    const expectedFrames = (elapsed / 1000) * 30  // ~30 fps minimum
+    return { frameCount, expectedFrames, elapsed }
+  })
+
+  // Should maintain reasonable frame rate (Worker offloaded crypto)
+  expect(result.frameCount).toBeGreaterThan(result.expectedFrames * 0.5)
+})
+```
+
+### 7.5 Cross-Browser Matrix
+
+| Browser | fetch streaming | Web Worker | OPFS sync | Status |
+|---------|----------------|------------|-----------|--------|
+| Chrome 105+ | ✓ | ✓ | ✓ | Primary target |
+| Firefox 111+ | ✓ | ✓ | ✓ | Supported |
+| Safari 16.4+ | ✓ | ✓ | ✓ | Supported |
+| Edge 105+ | ✓ | ✓ | ✓ | Supported (Chromium) |
+
+Playwright tests run against Chrome by default. CI can run against all browsers.
+
+### 7.6 Test Execution Summary
+
+| Phase | Test Layer | Command | What's Verified |
+|-------|-----------|---------|-----------------|
+| A | Layer 1 + 2 | `cabal test --test-option='--match=/XFTP Web Client/'` | fetch() transport, full flow |
+| B | Layer 3 | `npm run test:browser` | Worker message passing, progress |
+| C | Layer 3 | `npm run test:browser` | OPFS storage for large files |
+| D | Layer 3 | `npm run test:browser -- --project=firefox,webkit` | Cross-browser |

rfcs/done/2026-01-30-send-file-page/2026-02-04-xftp-web-page.md

@@ -0,0 +1,772 @@
+# Send File Web Page — Implementation Plan
+
+## TOC
+1. Executive Summary
+2. Architecture
+3. CryptoBackend & Web Worker
+4. Server Configuration
+5. Page Structure & UI
+6. Upload Flow
+7. Download Flow
+8. Build & Dev Setup
+9. agent.ts Changes
+10. Testing
+11. Files
+12. Implementation Order
+
+## 1. Executive Summary
+
+Build a static web page for browser-based XFTP file transfer (Phase 5 of master RFC). The page supports upload (drag-drop → encrypt → upload → shareable link) and download (open link → download → decrypt → save). Crypto runs in a Web Worker; large files use OPFS temp storage.
+
+Two build variants:
+- **Local**: single test server at `localhost:7000` (development/testing)
+- **Production**: 12 preset XFTP routers (6 SimpleX + 6 Flux)
+
+Uses Vite for bundling (already a dependency via vitest). No CSS framework — plain CSS per RFC spec.
+
+## 2. Architecture
+
+```
+xftp-web/
+├── src/                        # Library (existing, targeted changes)
+│   ├── agent.ts                # Modified: uploadFile readChunk, downloadFileRaw
+│   ├── client.ts               # Modified: downloadXFTPChunkRaw
+│   ├── crypto/                 # Unchanged
+│   ├── download.ts             # Unchanged
+│   └── protocol/
+│       └── description.ts      # Fix: SHA-256 → SHA-512 comment on digest field
+├── web/                        # Web page (new)
+│   ├── index.html              # Entry point (CSP meta tag)
+│   ├── main.ts                 # Router + sodium.ready init
+│   ├── upload.ts               # Upload UI + orchestration
+│   ├── download.ts             # Download UI + orchestration
+│   ├── progress.ts             # Circular progress canvas component
+│   ├── servers.ts              # Server list (build-time configured, imports servers.json)
+│   ├── servers.json            # Preset server addresses (shared with vite.config.ts)
+│   ├── crypto-backend.ts       # CryptoBackend interface + WorkerBackend
+│   ├── crypto.worker.ts        # Web Worker: encrypt/decrypt/OPFS
+│   └── style.css               # Minimal styling
+├── vite.config.ts              # Page build config (new)
+├── tsconfig.web.json           # IDE/CI type-check for web/ (new)
+├── tsconfig.worker.json        # IDE/CI type-check for worker (new)
+├── playwright.config.ts        # Page E2E test config (new)
+├── vitest.config.ts            # Test config (existing)
+├── .gitignore                  # Existing (add dist-web/)
+└── test/                       # Tests (existing + new page test)
+```
+
+Data flow:
+
+```
+                  ┌───────────────────────────────────────────┐
+                  │ Main Thread                                 │
+                  │                                             │
+                  │  Upload:  upload.ts ──► agent.ts ──► fetch()│
+                  │  Download: download.ts ──► agent.ts ──► fetch()
+                  │         │                                   │
+                  │    postMessage                        HTTP/2 │
+                  │         ▼                                   ▼
+                  │ ┌─────────────────┐             ┌──────────┐│
+                  │ │ Web Worker       │             │ XFTP     ││
+                  │ │ crypto.worker.ts │             │ Server   ││
+                  │ │ ┌─────────────┐ │             └──────────┘│
+                  │ │ │ OPFS temp   │ │                         │
+                  │ │ └─────────────┘ │                         │
+                  │ └─────────────────┘                         │
+                  └───────────────────────────────────────────┘
+```
+
+Both upload and download use `agent.ts` for orchestration (connection pooling, parallel chunk transfers, redirect handling). Upload uses a `readChunk` callback for Worker data access. Download uses an `onRawChunk` callback to route raw encrypted chunks to the Worker for decryption (see §7.2). ACK is the caller's responsibility — `downloadFileRaw` returns the resolved `FileDescription` without ACKing, so the caller can verify integrity before acknowledging.
+
+## 3. CryptoBackend & Web Worker
+
+### 3.1 Interface
+
+```typescript
+// crypto-backend.ts
+export interface CryptoBackend {
+  // Upload: encrypt file, store encrypted data in OPFS
+  encrypt(data: Uint8Array, fileName: string,
+          onProgress?: (done: number, total: number) => void
+  ): Promise<EncryptResult>
+
+  // Upload: read encrypted chunk from OPFS (called by agent.ts via readChunk callback)
+  readChunk(offset: number, size: number): Promise<Uint8Array>
+
+  // Download: transit-decrypt raw chunk and store in OPFS
+  decryptAndStoreChunk(
+    dhSecret: Uint8Array, nonce: Uint8Array,
+    body: Uint8Array, digest: Uint8Array, chunkNo: number
+  ): Promise<void>
+
+  // Download: verify digest + file-level decrypt all stored chunks
+  // Only needs size/digest/key/nonce — not the full FileDescription (avoids sending private keys to Worker)
+  verifyAndDecrypt(params: {size: number, digest: Uint8Array, key: Uint8Array, nonce: Uint8Array}
+  ): Promise<{header: FileHeader, content: Uint8Array}>
+
+  cleanup(): Promise<void>
+}
+
+// Structurally identical to EncryptedFileMetadata from agent.ts (§9.1).
+// Kept separate to avoid crypto-backend.ts importing from agent.ts
+// (which would pull in node:http2 via client.ts, breaking Worker bundling).
+// TypeScript structural typing makes them assignment-compatible.
+export interface EncryptResult {
+  digest: Uint8Array
+  key: Uint8Array
+  nonce: Uint8Array
+  chunkSizes: number[]
+}
+```
+
+### 3.2 Factory
+
+```typescript
+export function createCryptoBackend(): CryptoBackend {
+  if (typeof Worker === 'undefined') {
+    throw new Error('Web Workers required — update your browser')
+  }
+  return new WorkerBackend()
+}
+```
+
+The Worker always uses OPFS for temp storage (single code path — no memory/disk branching). OPFS I/O overhead is negligible relative to crypto and network time. Each Worker session creates a unique directory in OPFS root named `session-<Date.now()>-<crypto.randomUUID()>`, containing `upload.bin` and `download.bin` as needed. `cleanup()` deletes the entire session directory. On Worker startup (before processing messages), sweep OPFS root and delete any `session-*` directories whose embedded timestamp (parsed from the name) is older than 1 hour — this handles stale files from crashed tabs. The OPFS API does not expose directory timestamps, so the name-encoded timestamp is the only reliable mechanism. This prevents cross-tab collisions and unbounded OPFS growth.
+
+### 3.3 Worker message protocol
+
+Every request carries a numeric `id`. Responses carry the same `id`. WorkerBackend maintains a `Map<number, {resolve, reject}>` to match responses to pending promises.
+
+Main → Worker (fields marked `†` are Transferable — arrive as `ArrayBuffer` in Worker, must be wrapped with `new Uint8Array(...)` before use):
+- `{id: number, type: 'encrypt', data†: ArrayBuffer, fileName: string}` — encrypt file, store in OPFS
+- `{id: number, type: 'readChunk', offset: number, size: number}` — read encrypted chunk from OPFS
+- `{id: number, type: 'decryptAndStoreChunk', dhSecret: Uint8Array, nonce: Uint8Array, body†: ArrayBuffer, chunkDigest: Uint8Array, chunkNo: number}` — transit-decrypt + store in OPFS. `chunkDigest` is the per-chunk SHA-256 digest (verified by `decryptReceivedChunk`). Distinct from the file-level SHA-512 digest in `verifyAndDecrypt`.
+- `{id: number, type: 'verifyAndDecrypt', size: number, digest: Uint8Array, key: Uint8Array, nonce: Uint8Array}` — verify digest + file-level decrypt all chunks. Only the four fields needed for verification/decryption are sent — not the full `FileDescription`, which contains private replica keys that the Worker doesn't need.
+- `{id: number, type: 'cleanup'}` — delete OPFS temp files
+
+Worker → Main (fields marked `†` are Transferable):
+- `{id: number, type: 'progress', done: number, total: number}` — encryption/decryption progress (fire-and-forget, no promise)
+- `{id: number, type: 'encrypted', digest: Uint8Array, key: Uint8Array, nonce: Uint8Array, chunkSizes: number[]}` — all fields structured-cloned (not transferred)
+- `{id: number, type: 'chunk', data†: ArrayBuffer}` — readChunk response
+- `{id: number, type: 'stored'}` — decryptAndStore acknowledgment
+- `{id: number, type: 'decrypted', header: FileHeader, content†: ArrayBuffer}` — verifyAndDecrypt response
+- `{id: number, type: 'cleaned'}`
+- `{id: number, type: 'error', message: string}` — rejects the pending promise for this `id`
+
+All messages carrying large `ArrayBuffer` payloads use `postMessage(msg, [transferables])` to transfer ownership instead of structured-clone copying. Only `ArrayBuffer` can be transferred — `Uint8Array`, `number[]`, and other types are always structured-cloned. This applies to: `encrypt` request (`data`), `readChunk` response (`data`), `decryptAndStoreChunk` request (`body`), and `verifyAndDecrypt` response (`content`). The `WorkerBackend` implementation must ensure the transferred `ArrayBuffer` covers the full `Uint8Array` — if `byteOffset !== 0` or `byteLength !== buffer.byteLength`, slice first: `data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)`. This is required for `decryptAndStore` request bodies: `sendXFTPCommand` returns `body = fullResp.subarray(XFTP_BLOCK_SIZE)`, which has `byteOffset = XFTP_BLOCK_SIZE`. Other payloads are full-buffer views (§6 step 3 creates `new Uint8Array(await file.arrayBuffer())`; Worker responses allocate fresh buffers) but `WorkerBackend` should guard unconditionally.
+
+### 3.4 Worker internals
+
+**Imports:** The Worker imports directly from `libsodium-wrappers-sumo` (for `await sodium.ready`), `src/crypto/file.js` (`encryptFile`, `encodeFileHeader`, `decryptChunks`), `src/crypto/digest.js` (`sha512`), `src/protocol/chunks.js` (`prepareChunkSizes`, `fileSizeLen`, `authTagSize`), `src/protocol/encoding.js` (`concatBytes`), and `src/download.js` (`decryptReceivedChunk`). `download.js` directly imports `src/protocol/client.js` (for `decryptTransportChunk`). These transitively pull in `src/crypto/secretbox.js`, `src/crypto/keys.js`, and `src/crypto/padding.js`. None of these import `src/agent.ts` or `src/client.ts` — those pull in `node:http2` via dynamic import which would break Worker bundling. Vite tree-shakes the transitive deps automatically. Note: `download.js` → `protocol/client.js` → `crypto/keys.js` transitively pulls in `@noble/curves` (~50-80KB). This is unavoidable since `decryptTransportChunk` needs `dh` from `keys.js`. If Worker bundle size becomes a concern, `decryptReceivedChunk` could be refactored out of `download.js` into a separate module that doesn't import `protocol/client.js`.
+
+**ArrayBuffer → Uint8Array conversion:** All Transferable fields arrive in the Worker as `ArrayBuffer`. The Worker's message handler must wrap them before passing to library functions: `new Uint8Array(msg.data)` for encrypt, `new Uint8Array(msg.body)` for decryptAndStore. Non-transferred fields (`dhSecret`, `nonce`, `digest`, `chunkSizes`) arrive as their original types (`Uint8Array` / `number[]`) via structured clone.
+
+The Worker's encrypt handler calls the same functions as `encryptFileForUpload` in agent.ts (key/nonce generation → `encryptFile` → `sha512` → `prepareChunkSizes`). This is not reimplementation — it's calling the same library functions from a different entry point.
+
+**Libsodium init:** Both the Worker and the main thread must `await sodium.ready` before calling any crypto functions that use libsodium. The Worker does this once on startup before processing messages. The main thread needs it before `connectXFTP` (which uses libsodium via `verifyIdentityProof`) and before `downloadXFTPChunkRaw` (which uses libsodium via `generateX25519KeyPair` + `dh`). In practice, `main.ts` calls `await sodium.ready` at page load, before any XFTP calls.
+
+Encrypt (mirrors `encryptFileForUpload` in agent.ts):
+1. Generate key (32B) + nonce (24B) via `crypto.getRandomValues`
+2. `fileHdr = encodeFileHeader({fileName, fileExtra: null})`
+3. `fileSize = BigInt(fileHdr.length + source.length)`
+4. `payloadSize = Number(fileSize) + fileSizeLen + authTagSize`
+5. `chunkSizes = prepareChunkSizes(payloadSize)`
+6. `encSize = BigInt(chunkSizes.reduce((a, b) => a + b, 0))`
+7. `encData = encryptFile(source, fileHdr, key, nonce, fileSize, encSize)`
+8. `digest = sha512(encData)` — note: the `digest` field comment in `FileDescription` in `description.ts` says "SHA-256" but the actual hash is SHA-512 everywhere (`sha512` in agent.ts and download.ts). Fix the comment during implementation.
+9. Open OPFS upload file via `createSyncAccessHandle`, write `encData`, flush, close handle. Null out `encData` reference.
+10. Reopen the same OPFS file with `createSyncAccessHandle` as a persistent read handle (stored on the Worker module scope). This handle is used by all subsequent `readChunk` calls and closed on `cleanup`.
+11. Post back `{digest, key, nonce, chunkSizes}` (no encData transfer — data stays in OPFS)
+
+readChunk:
+- Use the persistent read handle: `handle.read(buf, {at: offset})` → return slice as transferable ArrayBuffer. OPFS allows only one `FileSystemSyncAccessHandle` per file; the persistent handle avoids per-call open/close overhead.
+
+decryptAndStoreChunk (removes transport encryption only — stored data is still file-level encrypted):
+1. `decryptReceivedChunk(dhSecret, nonce, new Uint8Array(body), chunkDigest)` → transit-decrypted chunk data (still file-level encrypted — only the transport layer is removed). Argument order matches signature `(dhSecret, cbNonce, encData, expectedDigest)` from download.ts. `body` arrives as `ArrayBuffer` via Transferable and must be wrapped; `dhSecret`, `nonce`, `chunkDigest` arrive as `Uint8Array` via structured clone.
+2. On first call, open the OPFS download temp file via `createSyncAccessHandle` and store as a persistent write handle. Record `{chunkNo, size: decrypted.length}` in an in-memory `chunkMeta: Map<number, {offset: number, size: number}>` — offset is the running sum of sizes for chunks stored so far (chunks may arrive out of order with `concurrency > 1`, so offset is assigned as `currentFileOffset`, then `currentFileOffset += size`)
+3. Write decrypted chunk to the persistent handle at the recorded offset
+
+verifyAndDecrypt (mirrors size/digest checks in agent.ts `downloadFile`):
+1. Close the persistent download write handle (flush first), then reopen as a read handle. Read each chunk from OPFS into a `Uint8Array[]` array, ordered by `chunkNo`: for each entry in `chunkMeta` sorted by `chunkNo`, `handle.read(buf, {at: offset})` with the recorded offset and size
+2. Concatenate for verification: `combined = concatBytes(...chunks)`
+3. Verify total size: `combined.length === params.size`
+4. Verify SHA-512 digest: `sha512(combined)` matches `params.digest`
+5. Decrypt: `decryptChunks(BigInt(params.size), chunks, params.key, params.nonce)` — `params.size` is the encrypted file size (`fd.size` = `sum(chunkSizes)` = `decryptChunks`' first param `encSize`). Called directly instead of via `processDownloadedFile` (which expects a full `FileDescription`). Pass the original `chunks` array (not `combined`), as `decryptChunks` handles concatenation internally.
+6. Delete OPFS download temp file
+7. Return `{header, content}` via transferable ArrayBuffer
+
+### 3.5 Browser requirements
+
+The page requires a modern browser with Web Worker and OPFS support:
+- Chrome 102+, Firefox 114+, Safari 15.2+ (Workers + OPFS + ES module Workers — Firefox added module Worker support in 114)
+- If Worker or OPFS is unavailable, the page shows an error message rather than falling back silently.
+
+No `DirectBackend` is needed — the page is browser-only, and tests run in vitest browser mode (real Chromium). The existing library tests (`test/browser.test.ts`) test the crypto/upload/download pipeline directly without Workers.
+
+## 4. Server Configuration
+
+### 4.1 Server lists
+
+`web/servers.json` — single source of truth for preset server addresses (imported by both `servers.ts` and `vite.config.ts`):
+
+```json
+{
+  "simplex": [
+    "xftp://da1aH3nOT-9G8lV7bWamhxpDYdJ1xmW7j3JpGaDR5Ug=@xftp1.simplex.im",
+    "xftp://5vog2Imy1ExJB_7zDZrkV1KDWi96jYFyy9CL6fndBVw=@xftp2.simplex.im",
+    "xftp://PYa32DdYNFWi0uZZOprWQoQpIk5qyjRJ3EF7bVpbsn8=@xftp3.simplex.im",
+    "xftp://k_GgQl40UZVV0Y4BX9ZTyMVqX5ZewcLW0waQIl7AYDE=@xftp4.simplex.im",
+    "xftp://-bIo6o8wuVc4wpZkZD3tH-rCeYaeER_0lz1ffQcSJDs=@xftp5.simplex.im",
+    "xftp://6nSvtY9pJn6PXWTAIMNl95E1Kk1vD7FM2TeOA64CFLg=@xftp6.simplex.im"
+  ],
+  "flux": [
+    "xftp://92Sctlc09vHl_nAqF2min88zKyjdYJ9mgxRCJns5K2U=@xftp1.simplexonflux.com",
+    "xftp://YBXy4f5zU1CEhnbbCzVWTNVNsaETcAGmYqGNxHntiE8=@xftp2.simplexonflux.com",
+    "xftp://ARQO74ZSvv2OrulRF3CdgwPz_AMy27r0phtLSq5b664=@xftp3.simplexonflux.com",
+    "xftp://ub2jmAa9U0uQCy90O-fSUNaYCj6sdhl49Jh3VpNXP58=@xftp4.simplexonflux.com",
+    "xftp://Rh19D5e4Eez37DEE9hAlXDB3gZa1BdFYJTPgJWPO9OI=@xftp5.simplexonflux.com",
+    "xftp://0AznwoyfX8Od9T_acp1QeeKtxUi676IBIiQjXVwbdyU=@xftp6.simplexonflux.com"
+  ]
+}
+```
+
+`web/servers.ts`:
+
+```typescript
+import {parseXFTPServer, type XFTPServer} from '../src/protocol/address.js'
+import presets from './servers.json'
+
+declare const __XFTP_SERVERS__: string[]
+
+const serverAddresses: string[] = typeof __XFTP_SERVERS__ !== 'undefined'
+  ? __XFTP_SERVERS__
+  : [...presets.simplex, ...presets.flux]
+
+export function getServers(): XFTPServer[] {
+  return serverAddresses.map(parseXFTPServer)
+}
+
+export function pickRandomServer(servers: XFTPServer[]): XFTPServer {
+  return servers[Math.floor(Math.random() * servers.length)]
+}
+```
+
+### 4.2 Build-time injection
+
+`vite.config.ts` defines `__XFTP_SERVERS__`:
+- `mode === 'local'`: `["xftp://<test-fingerprint>@localhost:7000"]`
+- `mode === 'production'`: not defined → falls through to hardcoded list
+
+### 4.3 Assumption
+
+Production XFTP routers must have `[WEB]` section configured with a CA-signed certificate for browser TLS. Without this, browsers will reject the self-signed XFTP identity cert. The local test router uses `tests/fixtures/` certs which Chromium accepts via `ignoreHTTPSErrors`.
+
+## 5. Page Structure & UI
+
+### 5.1 Routing
+
+`main.ts` checks `window.location.hash` once on page load:
+- Hash present → download mode
+- Hash absent → upload mode
+
+No `hashchange` listener — the shareable link opens in a new tab. Simple page-load routing.
+
+### 5.2 Upload UI states
+
+1. **Landing**: Drag-drop zone centered, file picker button, size limit note
+2. **Uploading**: Circular progress (canvas), percentage, cancel button
+3. **Complete**: Shareable link (input + copy button), "Install SimpleX" CTA
+4. **Error**: Error message + retry button. On server-unreachable, auto-retry with exponential backoff (1s, 2s, 4s, up to 3 attempts) before showing the error state.
+
+### 5.3 Download UI states
+
+1. **Ready**: Approximate file size displayed (encrypted size from `fd.size` or `fd.redirect.size` — see §7 step 2; file name is unavailable — it's inside the encrypted content), download button
+2. **Downloading**: Circular progress, percentage
+3. **Complete**: Browser save dialog triggered automatically
+4. **Error**: Error message (expired, corrupted, unreachable)
+
+### 5.4 Security summary (RFC §7.4)
+
+Both upload-complete and download-ready states display a brief non-technical security summary:
+- Files are encrypted in the browser before upload — the server never sees file contents.
+- The link contains the decryption key in the hash fragment, which the browser never sends to any server.
+- For maximum security, use the SimpleX app.
+
+### 5.5 File expiry
+
+Display on upload-complete state: "Files are typically available for 48 hours." This is an approximation — actual expiry depends on each XFTP router's `[STORE_LOG]` retention configuration. The 48-hour figure matches the current preset router defaults.
+
+### 5.6 Styling
+
+Plain CSS, no framework. White background, centered content, responsive. Circular progress via `<canvas>` (arc drawing, percentage text in center).
+
+File size limit: 100MB. Displayed on upload page.
+
+### 5.7 CSP
+
+`index.html` includes a `<meta>` Content-Security-Policy tag with a build-time placeholder:
+
+```html
+<meta http-equiv="Content-Security-Policy"
+  content="default-src 'self'; worker-src 'self' blob:; style-src 'self' 'unsafe-inline'; connect-src __CSP_CONNECT_SRC__;">
+```
+
+Vite's `transformIndexHtml` hook (in `vite.config.ts`) replaces `__CSP_CONNECT_SRC__` at build time with origins derived from the server list:
+- Local mode: `https://localhost:7000`
+- Production: `https://xftp1.simplex.im:443 https://xftp2.simplex.im:443 ...` (all 12 servers)
+
+## 6. Upload Flow
+
+`web/upload.ts`:
+
+1. User drops/picks file → `File` object
+2. Validate `file.size <= 100 * 1024 * 1024` — show error if exceeded
+3. Read file: `new Uint8Array(await file.arrayBuffer())` — note: after `backend.encrypt()` transfers the buffer to the Worker, `fileData` is detached (zero-length). Peak memory is ~2× file size (main thread holds original until transfer, Worker holds encrypted copy before OPFS write). Acceptable for the 100MB limit; do not raise the limit without considering memory implications.
+4. Create `CryptoBackend` via factory
+5. Create `XFTPClientAgent`
+6. `backend.encrypt(fileData, file.name, onProgress)` → `EncryptResult`
+   - Encryption progress shown on canvas (Worker posts progress messages)
+7. Pick one random server from configured list (V1: all chunks to same server)
+8. Call `uploadFile(agent, server, metadata, {onProgress, readChunk: (off, sz) => backend.readChunk(off, sz)})`:
+   - `metadata` = `{digest, key, nonce, chunkSizes}` from EncryptResult
+   - Network progress shown on canvas
+   - Returns `{rcvDescription, sndDescription, uri}`
+9. Construct full URL: `window.location.origin + window.location.pathname + '#' + uri`
+10. Display link, copy button
+11. Cleanup: `backend.cleanup()`, `closeXFTPAgent(agent)`
+
+**Cancel:** User can abort via cancel button. Sets an `AbortController` signal that:
+- Sends `{type: 'cleanup'}` to Worker
+- Closes the XFTPClientAgent (drops HTTP/2 connections)
+- Resets UI to landing state
+
+## 7. Download Flow
+
+`web/download.ts`:
+
+1. Parse `window.location.hash.slice(1)` → `decodeDescriptionURI(fragment)` → `FileDescription`
+2. Display file size (`fd.size` bytes, formatted human-readable). Note: `fd.size` is the encrypted size (slightly larger than plaintext due to padding + auth tag). The plaintext size is not available until decryption — display it as an approximate file size. If `fd.redirect !== null`, size comes from `fd.redirect.size` (which is the inner encrypted size).
+3. User clicks "Download"
+4. Create `CryptoBackend` and `XFTPClientAgent`
+5. Call `downloadFileRaw(agent, fd, onRawChunk, {onProgress, concurrency: 3})`:
+   - `onRawChunk` forwards each raw chunk to the Worker: `backend.decryptAndStoreChunk(raw.dhSecret, raw.nonce, raw.body, raw.digest, raw.chunkNo)`
+   - `downloadFileRaw` handles redirect resolution internally (see §7.1), parallel downloads, and connection pooling
+   - Returns the resolved `FileDescription` (inner fd for redirect case, original fd otherwise)
+6. `backend.verifyAndDecrypt({size: resolvedFd.size, digest: resolvedFd.digest, key: resolvedFd.key, nonce: resolvedFd.nonce})` → `{header, content}`
+   - Verifies size + SHA-512 digest + file-level decryption inside Worker. Only the four needed fields are sent — private replica keys stay on the main thread.
+7. ACK: `ackFileChunks(agent, resolvedFd)` — best-effort, after verification succeeds
+8. Sanitize `header.fileName` before use: strip path separators (`/`, `\`), replace null/control characters (U+0000-U+001F, U+007F), strip Unicode bidi override characters (U+202A-U+202E, U+2066-U+2069 — prevents `doc.pdf.exe` appearing as `doc.exe.pdf`), limit length to 255 chars. The filename is user-controlled (set by the uploader) and arrives via decrypted content. Then trigger browser save: `new Blob([content])` → `<a download="${sanitizedName}">` click
+9. Cleanup: `backend.cleanup()`, `closeXFTPAgent(agent)`
+
+### 7.1 Redirect handling
+
+Handled inside `downloadFileRaw` in agent.ts — the web page doesn't see it. When `fd.redirect !== null`:
+
+1. Download redirect chunks via `downloadXFTPChunkRaw` (parallel, same as regular chunks)
+2. Transit-decrypt + verify + file-level decrypt on main thread (redirect data is always small — a few KB of YAML, so main thread decryption is fine)
+3. Parse YAML → inner `FileDescription`, validate against `fd.redirect.{size, digest}`
+4. ACK redirect chunks (best-effort)
+5. Continue downloading inner description's chunks, calling `onRawChunk` for each
+
+### 7.2 Architecture note: download refactoring
+
+Both upload and download use `agent.ts` for orchestration. The key difference is where the crypto/network split happens:
+
+- **Upload**: agent.ts reads encrypted chunks from the Worker via `readChunk` callback, sends them over the network.
+- **Download**: agent.ts receives raw encrypted responses from the network via `downloadXFTPChunkRaw` (DH key exchange + network only, no decryption), passes them to the web page via `onRawChunk` callback, which routes them to the Worker for transit decryption.
+
+This split keeps all expensive crypto off the main thread. Transit decryption uses a custom JS Salsa20 implementation (`xorKeystream` in secretbox.ts) that would block the UI for ~50-200ms on a 4MB chunk. File-level decryption (`decryptChunks`) is similarly expensive. Both happen in the Worker.
+
+The cheap operations stay on the main thread: DH key exchange (`generateX25519KeyPair` + `dh` — ~1ms via libsodium WASM), XFTP command encoding/decoding, connection management.
+
+## 8. Build & Dev Setup
+
+### 8.1 vite.config.ts (new, separate from vitest.config.ts)
+
+```typescript
+import {defineConfig, type Plugin} from 'vite'
+import {readFileSync} from 'fs'
+import {createHash} from 'crypto'
+import presets from './web/servers.json'
+
+function parseHost(addr: string): string {
+  const m = addr.match(/@(.+)$/)
+  if (!m) throw new Error('bad server address: ' + addr)
+  const host = m[1].split(',')[0]
+  return host.includes(':') ? host : host + ':443'
+}
+
+function cspPlugin(servers: string[]): Plugin {
+  const origins = servers.map(s => 'https://' + parseHost(s)).join(' ')
+  return {
+    name: 'csp-connect-src',
+    transformIndexHtml: {
+      order: 'pre',
+      handler(html, ctx) {
+        if (ctx.server) {
+          // Dev mode: remove CSP meta tag entirely — Vite HMR needs inline scripts
+          return html.replace(/<meta\s[^>]*?Content-Security-Policy[\s\S]*?>/i, '')
+        }
+        return html.replace('__CSP_CONNECT_SRC__', origins)
+      }
+    }
+  }
+}
+
+export default defineConfig(({mode}) => {
+  const define: Record<string, string> = {}
+  let servers: string[]
+
+  if (mode === 'local') {
+    const pem = readFileSync('../tests/fixtures/ca.crt', 'utf-8')
+    const der = Buffer.from(pem.replace(/-----[^-]+-----/g, '').replace(/\s/g, ''), 'base64')
+    const fp = createHash('sha256').update(der).digest('base64')
+      .replace(/\+/g, '-').replace(/\//g, '_')
+    servers = [`xftp://${fp}@localhost:7000`]
+    define['__XFTP_SERVERS__'] = JSON.stringify(servers)
+  } else {
+    servers = [...presets.simplex, ...presets.flux]
+  }
+
+  return {
+    root: 'web',
+    build: {outDir: '../dist-web'},
+    define,
+    worker: {format: 'es'},
+    plugins: [cspPlugin(servers)],
+  }
+})
+```
+
+### 8.2 package.json scripts
+
+```json
+"dev": "vite --mode local",
+"build:local": "vite build --mode local",
+"build:prod": "vite build --mode production",
+"preview": "vite preview",
+"check:web": "tsc -p tsconfig.web.json --noEmit && tsc -p tsconfig.worker.json --noEmit"
+```
+
+Note: `check:web` type-checks `src/` twice (once per config) — acceptable for this small library.
+
+Add `vite` as an explicit devDependency (`^6.0.0` — matching the version vitest 3.x depends on transitively). Relying on transitive resolution is fragile across package managers.
+
+### 8.3 TypeScript configuration
+
+The existing `tsconfig.json` has `rootDir: "src"` and `include: ["src/**/*.ts"]` — this is for library compilation only (output to `dist/`). Vite handles `web/` TypeScript compilation independently via esbuild, so the main tsconfig is unchanged. `web/*.ts` files import from `../src/*.js` using relative paths.
+
+Add two tsconfigs for `web/` type-checking — split by environment to avoid type pollution between DOM and WebWorker globals:
+
+`tsconfig.web.json` — main-thread files (DOM globals: `document`, `window`, etc.):
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "types": [],
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["web/**/*.ts", "src/**/*.ts"],
+  "exclude": ["web/crypto.worker.ts"]
+}
+```
+
+`tsconfig.worker.json` — Worker file (`self`, `FileSystemSyncAccessHandle`, etc.):
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "types": [],
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "WebWorker"]
+  },
+  "include": ["web/crypto.worker.ts", "src/**/*.ts"]
+}
+```
+
+Both configs set `"types": []` to prevent auto-inclusion of `@types/node` and `"moduleResolution": "bundler"` for Vite-compatible resolution (JSON imports, `.js` extension mapping). The base config's `"moduleResolution": "node"` would cause false type errors on `import ... from './servers.json'`. Both override `@types/node`, which would pollute DOM/WebWorker environments with Node.js globals (`process`, `Buffer`, etc.). This means `src/client.ts`'s dynamic `import("node:http2")` will produce a type error in these configs. This is acceptable — `src/client.ts` provides `createNodeTransport` which is never used in browser code (Vite tree-shakes it out), and full `src/` type-checking is handled by the base `tsconfig.json`. If the error is distracting, add `src/client.ts` to both configs' `exclude` arrays.
+
+Both extend the library tsconfig (inheriting `strict`, `module`, etc.) and include `src/**/*.ts` so imports from `../src/*.js` resolve. `"noEmit": true` means they're only used for type-checking — Vite handles actual compilation. The inherited `"exclude": ["node_modules", "dist", "test"]` intentionally excludes `test/` — test files are type-checked by their own vitest/playwright configs, not by `check:web`.
+
+### 8.4 Dev workflow
+
+`npm run dev` → Vite dev server at `localhost:5173`, configured for local test server. Start `xftp-server` on port 7000 separately (or via the existing globalSetup).
+
+Note: The CSP meta tag's `default-src 'self'` blocks Vite's injected HMR inline scripts in dev mode. The `cspPlugin` handles this by removing the entire CSP `<meta>` tag in serve mode (dev server), so HMR works without restrictions. Production builds always have the correct CSP.
+
+## 9. Library Changes (agent.ts + client.ts)
+
+Changes to support the web page: upload `readChunk` callback, download `onRawChunk` callback with parallel chunk downloads.
+
+### 9.1 Type changes
+
+Split the existing `EncryptedFileInfo` (which currently has `encData`, `digest`, `key`, `nonce`, `chunkSizes` as direct fields) into a metadata-only base and an extension:
+
+```typescript
+// Metadata-only variant (no encData — data lives in Worker/OPFS)
+export interface EncryptedFileMetadata {
+  digest: Uint8Array
+  key: Uint8Array
+  nonce: Uint8Array
+  chunkSizes: number[]
+}
+
+// Full variant (existing, extends metadata with data)
+export interface EncryptedFileInfo extends EncryptedFileMetadata {
+  encData: Uint8Array
+}
+```
+
+### 9.2 uploadFile signature change
+
+Replace positional optional params with an options bag. Add optional `readChunk`. When provided, `encrypted.encData` is not accessed.
+
+```typescript
+export interface UploadOptions {
+  onProgress?: (uploaded: number, total: number) => void
+  redirectThreshold?: number
+  readChunk?: (offset: number, size: number) => Promise<Uint8Array>
+}
+
+export async function uploadFile(
+  agent: XFTPClientAgent,
+  server: XFTPServer,
+  encrypted: EncryptedFileMetadata,
+  options?: UploadOptions
+): Promise<UploadResult>
+```
+
+Inside `uploadFile`:
+- Chunk read: if `options?.readChunk` is provided, use it. Otherwise, verify `'encData' in encrypted` at runtime (throws `"uploadFile: readChunk required when encData is absent"` if missing), then use `(off, sz) => Promise.resolve((encrypted as EncryptedFileInfo).encData.subarray(off, off + sz))`. This guards against calling `uploadFile` with `EncryptedFileMetadata` but no `readChunk`. For each chunk, call `readChunk(offset, size)` once and use the returned `Uint8Array` for both `getChunkDigest(chunkData)` and `uploadXFTPChunk(..., chunkData)` — do not call `readChunk` twice per chunk.
+- Progress total: `const total = encrypted.chunkSizes.reduce((a, b) => a + b, 0)` — replaces `encrypted.encData.length` (line 129) since `EncryptedFileMetadata` has no `encData`. The values are identical: `encData.length === sum(chunkSizes)`.
+- `buildDescription` parameter type: change from `EncryptedFileInfo` to `EncryptedFileMetadata` — it only accesses `chunkSizes`, `digest`, `key`, `nonce` (not `encData`).
+
+`uploadRedirectDescription` (internal) is unchanged — redirect descriptions are always small and created in-memory by `encryptFileForUpload`.
+
+### 9.3 Backward compatibility
+
+The signature change from positional params `(agent, server, encrypted, onProgress?, redirectThreshold?)` to `(agent, server, encrypted, options?)` is a breaking change for callers that pass `onProgress` or `redirectThreshold`. In practice, the only callers are the browser test (which passes no options — no change needed) and the web page (new code). `EncryptedFileInfo` extends `EncryptedFileMetadata`, so existing callers that pass `EncryptedFileInfo` work without change.
+
+### 9.4 client.ts: downloadXFTPChunkRaw
+
+Split `downloadXFTPChunk` at the network/crypto boundary. The new function does DH key exchange and network I/O but skips transit decryption:
+
+```typescript
+export interface RawChunkResponse {
+  dhSecret: Uint8Array
+  nonce: Uint8Array
+  body: Uint8Array
+}
+
+export async function downloadXFTPChunkRaw(
+  c: XFTPClient, rpKey: Uint8Array, fId: Uint8Array
+): Promise<RawChunkResponse> {
+  const {publicKey, privateKey} = generateX25519KeyPair()
+  const cmd = encodeFGET(encodePubKeyX25519(publicKey))
+  const {response, body} = await sendXFTPCommand(c, rpKey, fId, cmd)
+  if (response.type !== "FRFile") throw new Error("unexpected response: " + response.type)
+  const dhSecret = dh(response.rcvDhKey, privateKey)
+  return {dhSecret, nonce: response.nonce, body}
+}
+```
+
+`RawChunkResponse` contains only what client.ts produces (DH secret, nonce, encrypted body). The chunk metadata (`chunkNo`, `digest`) is added by agent.ts when constructing `RawDownloadedChunk` (see §9.5).
+
+The existing `downloadXFTPChunk` is refactored to call `downloadXFTPChunkRaw` + `decryptReceivedChunk`:
+
+```typescript
+export async function downloadXFTPChunk(
+  c: XFTPClient, rpKey: Uint8Array, fId: Uint8Array, digest?: Uint8Array
+): Promise<Uint8Array> {
+  const {dhSecret, nonce, body} = await downloadXFTPChunkRaw(c, rpKey, fId)
+  return decryptReceivedChunk(dhSecret, nonce, body, digest ?? null)
+}
+```
+
+### 9.5 agent.ts: downloadFileRaw, ackFileChunks, RawDownloadedChunk
+
+New type combining client.ts's `RawChunkResponse` with chunk metadata from agent.ts:
+
+```typescript
+export interface RawDownloadedChunk {
+  chunkNo: number
+  dhSecret: Uint8Array
+  nonce: Uint8Array
+  body: Uint8Array
+  digest: Uint8Array
+}
+```
+
+New function providing download orchestration with a raw chunk callback. Handles connection pooling, parallel downloads, redirect resolution, and progress. Does **not** ACK — the caller ACKs after verification.
+
+```typescript
+export interface DownloadRawOptions {
+  onProgress?: (downloaded: number, total: number) => void
+  concurrency?: number  // max parallel chunk downloads, default 1
+}
+
+export async function downloadFileRaw(
+  agent: XFTPClientAgent,
+  fd: FileDescription,
+  onRawChunk: (chunk: RawDownloadedChunk) => Promise<void>,
+  options?: DownloadRawOptions
+): Promise<FileDescription>
+```
+
+Returns the resolved `FileDescription` — for redirect files this is the inner fd, for non-redirect files this is the original fd. The caller uses this for verification and ACK.
+
+Internal structure:
+
+1. Validate `fd` via `validateFileDescription` (may double-validate if caller already validated via `decodeDescriptionURI` — harmless)
+2. If `fd.redirect !== null`: resolve redirect on main thread (redirect data is small):
+   a. Download redirect chunks via `downloadXFTPChunk` (not raw — main thread decryption is fine for a few KB)
+   b. Verify size + digest, `processDownloadedFile` → YAML bytes
+   c. Parse inner `FileDescription`, validate against `fd.redirect.{size, digest}`
+   d. ACK redirect chunks (best-effort — redirect chunks are small and separate from the file chunks)
+   e. Replace `fd` with inner description
+3. Pre-connect: call `getXFTPServerClient(agent, server)` for each unique server before launching concurrent workers. This ensures the client connection exists in the agent's map, avoiding a race condition where multiple concurrent workers all see the client as missing and each call `connectXFTP` independently (leaking all but the last connection). Known limitation: if a connection drops mid-download and multiple workers attempt reconnection simultaneously, the same TOCTOU race reappears. This is a pre-existing issue in `getXFTPServerClient`; a proper fix (per-key connection promise) is out of scope for this plan but should be tracked for follow-up.
+4. Download file chunks in parallel (concurrency-limited via sliding window):
+   - Create a queue of chunk indices `[0, 1, ..., N-1]`. Launch `min(concurrency, N)` async workers, each pulling the next index from the queue until empty. Each worker loops: pull index → derive key → `getXFTPServerClient` → `downloadXFTPChunkRaw` → `await onRawChunk(...)` → update progress → next index. `await Promise.all(workers)` to wait for completion.
+   - For each chunk: derive key (`decodePrivKeyEd25519` → `ed25519KeyPairFromSeed`), get client (`getXFTPServerClient`), call `downloadXFTPChunkRaw`, `await onRawChunk(...)` with result + `chunkNo` + `chunk.digest`
+   - Each concurrency slot awaits its `onRawChunk` before starting the next download on that slot. With `concurrency > 1`, multiple `onRawChunk` calls may be in-flight concurrently (one per slot). The Worker handles this correctly — messages are queued and processed sequentially.
+   - Update progress after each chunk: `downloaded += chunk.chunkSize; onProgress?.(downloaded, resolvedFd.size)` — both values use encrypted sizes for consistency
+5. Return the resolved `fd`
+
+New helper for ACKing after verification:
+
+```typescript
+export async function ackFileChunks(
+  agent: XFTPClientAgent, fd: FileDescription
+): Promise<void> {
+  for (const chunk of fd.chunks) {
+    const replica = chunk.replicas[0]
+    if (!replica) continue
+    try {
+      const client = await getXFTPServerClient(agent, parseXFTPServer(replica.server))
+      const seed = decodePrivKeyEd25519(replica.replicaKey)
+      const kp = ed25519KeyPairFromSeed(seed)
+      await ackXFTPChunk(client, kp.privateKey, replica.replicaId)
+    } catch (_) {}
+  }
+}
+```
+
+The existing `downloadFile` is refactored to use `downloadFileRaw` internally:
+
+```typescript
+export async function downloadFile(
+  agent: XFTPClientAgent,
+  fd: FileDescription,
+  onProgress?: (downloaded: number, total: number) => void
+): Promise<DownloadResult> {
+  const chunks: Uint8Array[] = []
+  const resolvedFd = await downloadFileRaw(agent, fd, async (raw) => {
+    chunks[raw.chunkNo - 1] = decryptReceivedChunk(
+      raw.dhSecret, raw.nonce, raw.body, raw.digest
+    )
+  }, {onProgress})
+  // verify + file-level decrypt using resolvedFd (inner fd for redirect case)
+  const combined = chunks.length === 1 ? chunks[0] : concatBytes(...chunks)
+  if (combined.length !== resolvedFd.size) throw new Error("downloadFile: file size mismatch")
+  const digest = sha512(combined)
+  if (!digestEqual(digest, resolvedFd.digest)) throw new Error("downloadFile: file digest mismatch")
+  // processDownloadedFile re-concatenates chunks internally — this mirrors the
+  // existing downloadFile pattern (verify on concatenated data, then pass chunks
+  // array to decryptChunks which concatenates again). Acceptable overhead for
+  // correctness: verification must happen on transit-decrypted data before
+  // file-level decryption transforms it.
+  const result = processDownloadedFile(resolvedFd, chunks)
+  await ackFileChunks(agent, resolvedFd)
+  return result
+}
+```
+
+Existing callers retain serial behavior (`concurrency` defaults to 1). The web page opts into parallelism by passing `concurrency: 3`. The browser test (`test/browser.test.ts`) continues to work unchanged. The chunks array is initialized empty (`[]`) and populated by sparse index assignment (`chunks[raw.chunkNo - 1] = ...`), so it correctly handles both redirect and non-redirect cases regardless of the outer fd's chunk count. `digestEqual` is an existing module-private helper in agent.ts (line 327) that performs constant-time byte comparison.
+
+### 9.6 Backward compatibility (download)
+
+`downloadFile` signature is unchanged — existing callers are unaffected. The refactoring adds `downloadFileRaw`, `ackFileChunks`, and `RawDownloadedChunk` as new exports from agent.ts, and `downloadXFTPChunkRaw` + `RawChunkResponse` as new exports from client.ts.
+
+## 10. Testing
+
+### 10.1 Existing tests (unchanged)
+
+- `npm run test:browser` — vitest browser round-trip (library-level)
+- `cabal test --test-option='--match=/XFTP Web Client/'` — Haskell per-function tests
+
+### 10.2 New: page E2E test
+
+Add `test/page.spec.ts` using `@playwright/test` (not vitest browser mode — vitest tests run IN the browser and can't control page navigation; Playwright tests run in Node.js and control the browser). Add `@playwright/test` as a devDependency.
+
+Add `playwright.config.ts` at the project root (`xftp-web/`):
+- `webServer: { command: 'vite build --mode local && vite preview', url: 'http://localhost:4173', reuseExistingServer: !process.env.CI }` — the `url` property tells Playwright to wait until the preview server is ready before running tests
+- `use.ignoreHTTPSErrors: true` (test server uses self-signed cert)
+- `use.launchOptions: { args: ['--ignore-certificate-errors'] }` — required because Playwright's `ignoreHTTPSErrors` only affects page navigation, not `fetch()` calls from in-page JavaScript. Without this flag, the page's `createBrowserTransport` fetch to `https://localhost:7000` would fail TLS validation.
+- `globalSetup`: `'./test/globalSetup.ts'` (starts xftp-server, shared with vitest)
+
+```typescript
+import {test, expect} from '@playwright/test'
+
+test('page upload + download round-trip', async ({page}) => {
+  await page.goto(PAGE_URL)
+  // Set file input via page.setInputFiles()
+  // Wait for upload link to appear: page.waitForSelector('[data-testid="share-link"]')
+  // Extract hash from link text
+  // Navigate to PAGE_URL + '#' + hash
+  // Wait for download complete state
+  // Verify file was offered for save (check download event)
+})
+```
+
+Add script: `"test:page": "playwright test test/page.spec.ts"`
+
+This tests the real bundle including Worker loading, OPFS, and CSP. The existing `test/browser.test.ts` continues to test the library-level pipeline (vitest browser mode, no Workers).
+
+### 10.3 Manual testing
+
+`npm run dev` → open `localhost:5173` in browser → drag file → get link → open link in new tab → download. Requires xftp-server running on port 7000 (local mode).
+
+## 11. Files
+
+**Create:**
+- `xftp-web/web/index.html` — page entry point (includes CSP meta tag)
+- `xftp-web/web/main.ts` — router + libsodium init
+- `xftp-web/web/upload.ts` — upload UI + orchestration
+- `xftp-web/web/download.ts` — download UI + orchestration
+- `xftp-web/web/progress.ts` — circular progress canvas component
+- `xftp-web/web/servers.json` — preset server addresses (shared by servers.ts and vite.config.ts)
+- `xftp-web/web/servers.ts` — server configuration (imports servers.json)
+- `xftp-web/web/crypto-backend.ts` — CryptoBackend interface + WorkerBackend + factory
+- `xftp-web/web/crypto.worker.ts` — Web Worker implementation
+- `xftp-web/web/style.css` — styles
+- `xftp-web/vite.config.ts` — page build config (CSP generation, server list)
+- `xftp-web/tsconfig.web.json` — IDE/CI type-checking for `web/` main-thread files (DOM)
+- `xftp-web/tsconfig.worker.json` — IDE/CI type-checking for `web/crypto.worker.ts` (WebWorker)
+- `xftp-web/playwright.config.ts` — Playwright E2E test config (webServer, globalSetup)
+- `xftp-web/test/page.spec.ts` — page E2E test (Playwright)
+
+**Modify:**
+- `xftp-web/src/agent.ts` — add `EncryptedFileMetadata` type, `uploadFile` options bag with `readChunk`, `downloadFileRaw` with `onRawChunk` callback + parallel downloads, `ackFileChunks`, `RawDownloadedChunk` type, refactor `downloadFile` on top of `downloadFileRaw`, add `import {decryptReceivedChunk} from "./download.js"` (needed by refactored `downloadFile`)
+- `xftp-web/src/client.ts` — add `downloadXFTPChunkRaw`, `RawChunkResponse` type, refactor `downloadXFTPChunk` to use raw variant
+- `xftp-web/package.json` — add dev/build/check:web/test:page scripts, add `vite` + `@playwright/test` devDeps
+- `xftp-web/src/protocol/description.ts` — fix stale "SHA-256" comment on `FileDescription.digest` to "SHA-512"
+- `xftp-web/.gitignore` — add `dist-web/`
+
+## 12. Implementation Order
+
+1. **Library refactoring** — `client.ts`: add `downloadXFTPChunkRaw`; `agent.ts`: add `downloadFileRaw` + parallel downloads, `uploadFile` options bag with `readChunk`; refactor existing `downloadFile` on top of `downloadFileRaw`. Run existing tests to verify no regressions.
+2. **Vite config + HTML shell** — `vite.config.ts`, `index.html`, `main.ts`, verify dev server works
+3. **Server config** — `servers.ts` with both local and production server lists
+4. **CryptoBackend + Worker** — interface, WorkerBackend, Worker implementation, OPFS logic
+5. **Upload flow** — `upload.ts` with drag-drop, encrypt via Worker, upload via agent, show link
+6. **Download flow** — `download.ts` with URL parsing, download via agent `downloadFileRaw`, Worker decrypt, browser save
+7. **Progress component** — `progress.ts` canvas drawing
+8. **Styling** — `style.css`
+9. **Testing** — page E2E test, manual browser verification
+10. **Build scripts** — `build:local`, `build:prod` in package.json

rfcs/done/2026-01-30-send-file-page/2026-02-04-xftp-web-persistent-connections.md

@@ -0,0 +1,53 @@
+# XFTPClientAgent Pattern
+
+## TOC
+1. Executive Summary
+2. Changes: client.ts
+3. Changes: agent.ts
+4. Changes: test/browser.test.ts
+5. Verification
+
+## Executive Summary
+
+Add `XFTPClientAgent` — a per-server connection pool matching the Haskell pattern. The agent caches `XFTPClient` instances by server URL. All orchestration functions (`uploadFile`, `downloadFile`, `deleteFile`) take `agent` as first parameter and use `getXFTPServerClient(agent, server)` instead of calling `connectXFTP` directly. Connections stay open on success; the caller creates and closes the agent.
+
+`connectXFTP` and `closeXFTP` stay exported (used by `XFTPWebTests.hs` Haskell tests). The `browserClients` hack, per-function `connections: Map`, and `getOrConnect` are deleted.
+
+## Changes: client.ts
+
+**Add** after types section: `XFTPClientAgent` interface, `newXFTPAgent`, `getXFTPServerClient`, `closeXFTPServerClient`, `closeXFTPAgent`.
+
+**Delete**: `browserClients` Map and all `isNode` browser-cache checks in `connectXFTP` and `closeXFTP`.
+
+**Revert `closeXFTP`** to unconditional `c.transport.close()` (browser transport.close() is already a no-op).
+
+`connectXFTP` stays exported (backward compat) but becomes a raw low-level function — no caching.
+
+## Changes: agent.ts
+
+**Imports**: replace `connectXFTP`/`closeXFTP` with `getXFTPServerClient`/`closeXFTPAgent` etc.
+
+**Re-export** from agent.ts: `newXFTPAgent`, `closeXFTPAgent`, `XFTPClientAgent`.
+
+**`uploadFile`**: add `agent: XFTPClientAgent` as first param. Replace `connectXFTP` → `getXFTPServerClient`. Remove `finally { closeXFTP }`. Pass `agent` to `uploadRedirectDescription`.
+
+**`uploadRedirectDescription`**: change from `(client, server, innerFd)` to `(agent, server, innerFd)`. Get client via `getXFTPServerClient`.
+
+**`downloadFile`**: add `agent` param. Delete local `connections: Map`. Replace `getOrConnect` → `getXFTPServerClient`. Remove finally cleanup. Pass `agent` to `downloadWithRedirect`.
+
+**`downloadWithRedirect`**: add `agent` param. Same replacements. Remove try/catch cleanup. Recursive call passes `agent`.
+
+**`deleteFile`**: add `agent` param. Same pattern.
+
+**Delete**: `getOrConnect` function entirely.
+
+## Changes: test/browser.test.ts
+
+Create agent before operations, pass to upload/download, close in finally.
+
+## Verification
+
+1. `npx vitest --run` — browser round-trip test passes
+2. No remaining `browserClients`, `getOrConnect`, or per-function `connections: Map` locals
+3. `connectXFTP` and `closeXFTP` still exported (XFTPWebTests.hs compat)
+4. All orchestration functions take `agent` as first param

rfcs/done/2026-01-30-send-file-page/2026-02-05-xftp-web-e2e-tests.md

@@ -0,0 +1,859 @@
+# XFTP Web Page E2E Tests Plan
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [Test Infrastructure](#2-test-infrastructure)
+3. [Test Infrastructure - Page Objects](#3-test-infrastructure---page-objects)
+4. [Upload Flow Tests](#4-upload-flow-tests)
+5. [Download Flow Tests](#5-download-flow-tests)
+6. [Edge Cases](#6-edge-cases)
+7. [Implementation Order](#7-implementation-order)
+8. [Test Utilities](#8-test-utilities)
+
+---
+
+## 1. Executive Summary
+
+This document specifies comprehensive Playwright E2E tests for the XFTP web page. The existing test (`page.spec.ts`) performs a basic upload/download round-trip. This plan extends coverage to:
+
+- **Upload flow**: File selection (picker + drag-drop), validation, progress, cancellation, link sharing, error handling
+- **Download flow**: Invalid link handling, download button, progress, file save, error states
+- **Edge cases**: Boundary file sizes, special characters, network failures, multi-packet files with redirect, UI information display
+
+**Key constraints**:
+- Tests run against a local XFTP router (started via `globalSetup.ts`)
+- Server port is dynamic (read from `/tmp/xftp-test-server.port`)
+- Browser uses `--ignore-certificate-errors` for self-signed certs
+- OPFS and Web Workers are required (Chromium supports both)
+
+**Test file location**: `/code/simplexmq/xftp-web/test/page.spec.ts`
+
+**Architecture**: Tests use the Page Object Model pattern to encapsulate UI interactions, making tests read as domain-specific scenarios rather than raw Playwright API calls.
+
+---
+
+## 2. Test Infrastructure
+
+### 2.1 Current Setup
+
+```
+xftp-web/
+├── playwright.config.ts      # Playwright config (webServer, globalSetup)
+├── test/
+│   ├── globalSetup.ts        # Starts xftp-server, writes port to PORT_FILE
+│   ├── page.spec.ts          # E2E tests (to be extended)
+│   └── pages/                # Page Objects (new)
+│       ├── UploadPage.ts
+│       └── DownloadPage.ts
+```
+
+### 2.2 Prerequisites
+
+- `globalSetup.ts` starts the XFTP router and writes port to `PORT_FILE`
+- Tests must read the port dynamically: `readFileSync(PORT_FILE, 'utf-8').trim()`
+- Vite builds and serves the page at `http://localhost:4173`
+
+---
+
+## 3. Test Infrastructure - Page Objects
+
+Page Objects encapsulate page-specific selectors and actions, providing a clean API for tests. This follows the standard Page Object Model pattern used in simplex-chat and most professional test suites.
+
+### 3.1 UploadPage
+
+```typescript
+// test/pages/UploadPage.ts
+import {Page, Locator, expect} from '@playwright/test'
+
+export class UploadPage {
+  readonly page: Page
+  readonly dropZone: Locator
+  readonly fileInput: Locator
+  readonly progressStage: Locator
+  readonly progressCanvas: Locator
+  readonly statusText: Locator
+  readonly cancelButton: Locator
+  readonly completeStage: Locator
+  readonly shareLink: Locator
+  readonly copyButton: Locator
+  readonly errorStage: Locator
+  readonly errorMessage: Locator
+  readonly retryButton: Locator
+  readonly expiryNote: Locator
+  readonly securityNote: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.dropZone = page.locator('#drop-zone')
+    this.fileInput = page.locator('#file-input')
+    this.progressStage = page.locator('#upload-progress')
+    this.progressCanvas = page.locator('#progress-container canvas')
+    this.statusText = page.locator('#upload-status')
+    this.cancelButton = page.locator('#cancel-btn')
+    this.completeStage = page.locator('#upload-complete')
+    this.shareLink = page.locator('[data-testid="share-link"]')
+    this.copyButton = page.locator('#copy-btn')
+    this.errorStage = page.locator('#upload-error')
+    this.errorMessage = page.locator('#error-msg')
+    this.retryButton = page.locator('#retry-btn')
+    this.expiryNote = page.locator('.expiry')
+    this.securityNote = page.locator('.security-note')
+  }
+
+  async goto() {
+    await this.page.goto('http://localhost:4173')
+  }
+
+  async selectFile(name: string, content: Buffer, mimeType = 'application/octet-stream') {
+    await this.fileInput.setInputFiles({name, mimeType, buffer: content})
+  }
+
+  async selectTextFile(name: string, content: string) {
+    await this.selectFile(name, Buffer.from(content, 'utf-8'), 'text/plain')
+  }
+
+  async selectLargeFile(name: string, sizeBytes: number) {
+    // Create large file in browser to avoid memory issues in test process
+    await this.page.evaluate(({name, size}) => {
+      const input = document.getElementById('file-input') as HTMLInputElement
+      const buffer = new ArrayBuffer(size)
+      new Uint8Array(buffer).fill(0x55)
+      const file = new File([buffer], name, {type: 'application/octet-stream'})
+      const dt = new DataTransfer()
+      dt.items.add(file)
+      input.files = dt.files
+      input.dispatchEvent(new Event('change', {bubbles: true}))
+    }, {name, size: sizeBytes})
+  }
+
+  async dragDropFile(name: string, content: Buffer) {
+    // Drag-drop uses same file input handler internally
+    await this.selectFile(name, content)
+  }
+
+  async waitForEncrypting(timeout = 10_000) {
+    await expect(this.statusText).toContainText('Encrypting', {timeout})
+  }
+
+  async waitForUploading(timeout = 30_000) {
+    await expect(this.statusText).toContainText('Uploading', {timeout})
+  }
+
+  async waitForShareLink(timeout = 60_000): Promise<string> {
+    await expect(this.shareLink).toBeVisible({timeout})
+    return await this.shareLink.inputValue()
+  }
+
+  async clickCopy() {
+    await this.copyButton.click()
+    await expect(this.copyButton).toContainText('Copied!')
+  }
+
+  async clickCancel() {
+    await this.cancelButton.click()
+  }
+
+  async clickRetry() {
+    await this.retryButton.click()
+  }
+
+  async expectError(messagePattern: string | RegExp) {
+    await expect(this.errorStage).toBeVisible()
+    await expect(this.errorMessage).toContainText(messagePattern)
+  }
+
+  async expectDropZoneVisible() {
+    await expect(this.dropZone).toBeVisible()
+  }
+
+  async expectProgressVisible() {
+    await expect(this.progressStage).toBeVisible()
+    await expect(this.progressCanvas).toBeVisible()
+  }
+
+  async expectCompleteWithExpiry() {
+    await expect(this.completeStage).toBeVisible()
+    await expect(this.expiryNote).toContainText('48 hours')
+  }
+
+  async expectSecurityNote() {
+    await expect(this.securityNote).toBeVisible()
+    await expect(this.securityNote).toContainText('encrypted')
+  }
+
+  getHashFromLink(url: string): string {
+    return new URL(url).hash
+  }
+}
+```
+
+### 3.2 DownloadPage
+
+```typescript
+// test/pages/DownloadPage.ts
+import {Page, Locator, expect, Download} from '@playwright/test'
+
+export class DownloadPage {
+  readonly page: Page
+  readonly readyStage: Locator
+  readonly downloadButton: Locator
+  readonly progressStage: Locator
+  readonly progressCanvas: Locator
+  readonly statusText: Locator
+  readonly errorStage: Locator
+  readonly errorMessage: Locator
+  readonly retryButton: Locator
+  readonly securityNote: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.readyStage = page.locator('#dl-ready')
+    this.downloadButton = page.locator('#dl-btn')
+    this.progressStage = page.locator('#dl-progress')
+    this.progressCanvas = page.locator('#dl-progress-container canvas')
+    this.statusText = page.locator('#dl-status')
+    this.errorStage = page.locator('#dl-error')
+    this.errorMessage = page.locator('#dl-error-msg')
+    this.retryButton = page.locator('#dl-retry-btn')
+    this.securityNote = page.locator('.security-note')
+  }
+
+  async goto(hash: string) {
+    await this.page.goto(`http://localhost:4173${hash}`)
+  }
+
+  async gotoWithLink(fullUrl: string) {
+    const hash = new URL(fullUrl).hash
+    await this.goto(hash)
+  }
+
+  async expectFileReady() {
+    await expect(this.readyStage).toBeVisible()
+    await expect(this.downloadButton).toBeVisible()
+  }
+
+  async expectFileSizeDisplayed() {
+    await expect(this.readyStage).toContainText(/\d+(?:\.\d+)?\s*(?:KB|MB|B)/)
+  }
+
+  async clickDownload(): Promise<Download> {
+    const downloadPromise = this.page.waitForEvent('download')
+    await this.downloadButton.click()
+    return downloadPromise
+  }
+
+  async waitForDownloading(timeout = 30_000) {
+    await expect(this.statusText).toContainText('Downloading', {timeout})
+  }
+
+  async waitForDecrypting(timeout = 30_000) {
+    await expect(this.statusText).toContainText('Decrypting', {timeout})
+  }
+
+  async expectProgressVisible() {
+    await expect(this.progressStage).toBeVisible()
+    await expect(this.progressCanvas).toBeVisible()
+  }
+
+  async expectInitialError(messagePattern: string | RegExp) {
+    // For malformed links - error shown in card without #dl-error stage
+    await expect(this.page.locator('.card .error')).toBeVisible()
+    await expect(this.page.locator('.card .error')).toContainText(messagePattern)
+  }
+
+  async expectRuntimeError(messagePattern: string | RegExp) {
+    // For runtime download errors - uses #dl-error stage
+    await expect(this.errorStage).toBeVisible()
+    await expect(this.errorMessage).toContainText(messagePattern)
+  }
+
+  async expectSecurityNote() {
+    await expect(this.securityNote).toBeVisible()
+    await expect(this.securityNote).toContainText('encrypted')
+  }
+}
+```
+
+### 3.3 Test Fixtures
+
+```typescript
+// test/fixtures.ts
+import {test as base} from '@playwright/test'
+import {UploadPage} from './pages/UploadPage'
+import {DownloadPage} from './pages/DownloadPage'
+import {readFileSync} from 'fs'
+
+// Extend Playwright test with page objects
+export const test = base.extend<{
+  uploadPage: UploadPage
+  downloadPage: DownloadPage
+}>({
+  uploadPage: async ({page}, use) => {
+    const uploadPage = new UploadPage(page)
+    await uploadPage.goto()
+    await use(uploadPage)
+  },
+  downloadPage: async ({page}, use) => {
+    await use(new DownloadPage(page))
+  },
+})
+
+export {expect} from '@playwright/test'
+
+// Test data helpers
+export function createTestContent(size: number, fill = 0x41): Buffer {
+  return Buffer.alloc(size, fill)
+}
+
+export function createTextContent(text: string): Buffer {
+  return Buffer.from(text, 'utf-8')
+}
+
+export function uniqueFileName(base: string, ext = 'txt'): string {
+  return `${base}-${Date.now()}.${ext}`
+}
+```
+
+---
+
+## 4. Upload Flow Tests
+
+### 4.1 File Selection - File Picker Button
+
+**Test ID**: `upload-file-picker`
+
+```typescript
+test('upload via file picker button', async ({uploadPage}) => {
+  await uploadPage.expectDropZoneVisible()
+
+  await uploadPage.selectTextFile('picker-test.txt', 'test content ' + Date.now())
+  await uploadPage.waitForEncrypting()
+  await uploadPage.waitForUploading()
+
+  const link = await uploadPage.waitForShareLink()
+  expect(link).toMatch(/^http:\/\/localhost:\d+\/#/)
+})
+```
+
+### 4.2 File Selection - Drag and Drop
+
+**Test ID**: `upload-drag-drop`
+
+```typescript
+test('upload via drag and drop', async ({uploadPage}) => {
+  await uploadPage.dragDropFile('dragdrop-test.txt', createTextContent('drag drop test'))
+  await uploadPage.expectProgressVisible()
+
+  const link = await uploadPage.waitForShareLink()
+  expect(link).toContain('#')
+})
+```
+
+### 4.3 File Size Validation - Too Large
+
+**Test ID**: `upload-file-too-large`
+
+```typescript
+test('upload rejects file over 100MB', async ({uploadPage}) => {
+  await uploadPage.selectLargeFile('large.bin', 100 * 1024 * 1024 + 1)
+  await uploadPage.expectError('too large')
+  await uploadPage.expectError('100 MB')
+})
+```
+
+### 4.4 File Size Validation - Empty File
+
+**Test ID**: `upload-file-empty`
+
+```typescript
+test('upload rejects empty file', async ({uploadPage}) => {
+  await uploadPage.selectFile('empty.txt', Buffer.alloc(0))
+  await uploadPage.expectError('empty')
+})
+```
+
+### 4.5 Progress Display
+
+**Test ID**: `upload-progress-display`
+
+```typescript
+test('upload shows progress during encryption and upload', async ({uploadPage}) => {
+  await uploadPage.selectFile('progress-test.bin', createTestContent(500 * 1024))
+
+  await uploadPage.expectProgressVisible()
+  await uploadPage.waitForEncrypting()
+  await uploadPage.waitForUploading()
+  await uploadPage.waitForShareLink()
+})
+```
+
+### 4.6 Cancel Button
+
+**Test ID**: `upload-cancel`
+
+```typescript
+test('cancel button aborts upload and returns to landing', async ({uploadPage}) => {
+  await uploadPage.selectFile('cancel-test.bin', createTestContent(1024 * 1024))
+  await uploadPage.expectProgressVisible()
+
+  await uploadPage.clickCancel()
+
+  await uploadPage.expectDropZoneVisible()
+  await expect(uploadPage.shareLink).toBeHidden()
+})
+```
+
+### 4.7 Share Link Display and Copy
+
+**Test ID**: `upload-share-link-copy`
+
+```typescript
+test('share link copy button works', async ({uploadPage, context}) => {
+  await context.grantPermissions(['clipboard-read', 'clipboard-write'])
+
+  await uploadPage.selectTextFile('copy-test.txt', 'copy test content')
+  const link = await uploadPage.waitForShareLink()
+
+  await uploadPage.clickCopy()
+
+  // Verify clipboard (may fail in headless)
+  try {
+    const clipboardText = await uploadPage.page.evaluate(() => navigator.clipboard.readText())
+    expect(clipboardText).toBe(link)
+  } catch {
+    // Clipboard API may not be available
+  }
+})
+```
+
+### 4.8 Error Handling and Retry
+
+**Test ID**: `upload-error-retry`
+
+```typescript
+test('error state shows retry button', async ({uploadPage}) => {
+  await uploadPage.selectFile('error-test.txt', Buffer.alloc(0))
+  await uploadPage.expectError('empty')
+  await expect(uploadPage.retryButton).toBeVisible()
+})
+```
+
+---
+
+## 5. Download Flow Tests
+
+### 5.1 Invalid Link Handling - Malformed Hash
+
+**Test ID**: `download-invalid-hash-malformed`
+
+```typescript
+test('download shows error for malformed hash', async ({downloadPage}) => {
+  await downloadPage.goto('#not-valid-base64!!!')
+  await downloadPage.expectInitialError(/[Ii]nvalid|corrupted/)
+  await expect(downloadPage.downloadButton).not.toBeVisible()
+})
+```
+
+### 5.2 Invalid Link Handling - Valid Base64 but Invalid Structure
+
+**Test ID**: `download-invalid-hash-structure`
+
+```typescript
+test('download shows error for invalid structure', async ({downloadPage}) => {
+  await downloadPage.goto('#AAAA')
+  await downloadPage.expectInitialError(/[Ii]nvalid|corrupted/)
+})
+```
+
+### 5.3 Download Button Click
+
+**Test ID**: `download-button-click`
+
+```typescript
+test('download button initiates download', async ({uploadPage, downloadPage}) => {
+  // Upload first
+  await uploadPage.selectTextFile('dl-btn-test.txt', 'download test content')
+  const link = await uploadPage.waitForShareLink()
+
+  // Navigate to download
+  await downloadPage.gotoWithLink(link)
+  await downloadPage.expectFileReady()
+
+  // Click download
+  const download = await downloadPage.clickDownload()
+  expect(download.suggestedFilename()).toBe('dl-btn-test.txt')
+})
+```
+
+### 5.4 Progress Display
+
+**Test ID**: `download-progress-display`
+
+```typescript
+test('download shows progress', async ({uploadPage, downloadPage}) => {
+  await uploadPage.selectFile('dl-progress.bin', createTestContent(500 * 1024))
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const downloadPromise = downloadPage.clickDownload()
+
+  await downloadPage.expectProgressVisible()
+  await downloadPage.waitForDownloading()
+
+  await downloadPromise
+})
+```
+
+### 5.5 File Save Verification
+
+**Test ID**: `download-file-save`
+
+```typescript
+test('downloaded file content matches upload', async ({uploadPage, downloadPage}) => {
+  const content = 'verification content ' + Date.now()
+  const fileName = 'verify.txt'
+
+  await uploadPage.selectTextFile(fileName, content)
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).toBe(fileName)
+
+  const path = await download.path()
+  if (path) {
+    const downloadedContent = (await import('fs')).readFileSync(path, 'utf-8')
+    expect(downloadedContent).toBe(content)
+  }
+})
+```
+
+---
+
+## 6. Edge Cases
+
+### 6.1 Very Small Files
+
+**Test ID**: `edge-small-file`
+
+```typescript
+test('upload and download 1-byte file', async ({uploadPage, downloadPage}) => {
+  await uploadPage.selectFile('tiny.bin', Buffer.from([0x42]))
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).toBe('tiny.bin')
+
+  const path = await download.path()
+  if (path) {
+    const content = (await import('fs')).readFileSync(path)
+    expect(content.length).toBe(1)
+    expect(content[0]).toBe(0x42)
+  }
+})
+```
+
+### 6.2 Files Near 100MB Limit
+
+**Test ID**: `edge-near-limit`
+
+```typescript
+test.slow()
+test('upload file at exactly 100MB', async ({uploadPage}) => {
+  await uploadPage.selectLargeFile('exactly-100mb.bin', 100 * 1024 * 1024)
+
+  // Should succeed (not show error)
+  await expect(uploadPage.errorStage).toBeHidden({timeout: 5000})
+  await uploadPage.expectProgressVisible()
+
+  // Wait for completion (may take a while)
+  await uploadPage.waitForShareLink(300_000)
+})
+```
+
+### 6.3 Special Characters in Filename
+
+**Test ID**: `edge-special-chars-filename`
+
+```typescript
+test('upload and download file with unicode filename', async ({uploadPage, downloadPage}) => {
+  const fileName = 'test-\u4e2d\u6587-\u0420\u0443\u0441\u0441\u043a\u0438\u0439.txt'
+
+  await uploadPage.selectTextFile(fileName, 'unicode filename test')
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).toBe(fileName)
+})
+
+test('upload and download file with spaces', async ({uploadPage, downloadPage}) => {
+  const fileName = 'my document (final) v2.txt'
+
+  await uploadPage.selectTextFile(fileName, 'spaces test')
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).toBe(fileName)
+})
+
+test('filename with path separators is sanitized', async ({uploadPage, downloadPage}) => {
+  await uploadPage.selectTextFile('../../../etc/passwd', 'path traversal test')
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).not.toContain('/')
+  expect(download.suggestedFilename()).not.toContain('\\')
+})
+```
+
+### 6.4 Network Errors (Mocked)
+
+**Test ID**: `edge-network-error`
+
+```typescript
+test('upload handles network error gracefully', async ({uploadPage}) => {
+  // Intercept and abort POST requests
+  await uploadPage.page.route('**/localhost:*', route => {
+    if (route.request().method() === 'POST') {
+      route.abort('failed')
+    } else {
+      route.continue()
+    }
+  })
+
+  await uploadPage.selectTextFile('network-error.txt', 'network error test')
+  await uploadPage.expectError(/.+/) // Any error message
+})
+```
+
+### 6.5 Binary File Content Integrity
+
+**Test ID**: `edge-binary-content`
+
+```typescript
+test('binary file with all byte values', async ({uploadPage, downloadPage}) => {
+  // Create buffer with all 256 byte values
+  const buffer = Buffer.alloc(256)
+  for (let i = 0; i < 256; i++) buffer[i] = i
+
+  await uploadPage.selectFile('all-bytes.bin', buffer)
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  const path = await download.path()
+  if (path) {
+    const content = (await import('fs')).readFileSync(path)
+    expect(content.length).toBe(256)
+    for (let i = 0; i < 256; i++) {
+      expect(content[i]).toBe(i)
+    }
+  }
+})
+```
+
+### 6.6 Multiple Concurrent Downloads
+
+**Test ID**: `edge-concurrent-downloads`
+
+```typescript
+test('concurrent downloads from same link', async ({browser}) => {
+  const context = await browser.newContext({ignoreHTTPSErrors: true})
+  const page1 = await context.newPage()
+  const upload = new UploadPage(page1)
+
+  await upload.goto()
+  await upload.selectTextFile('concurrent.txt', 'concurrent download test')
+  const link = await upload.waitForShareLink()
+  const hash = upload.getHashFromLink(link)
+
+  // Open two tabs and download concurrently
+  const page2 = await context.newPage()
+  const page3 = await context.newPage()
+  const dl2 = new DownloadPage(page2)
+  const dl3 = new DownloadPage(page3)
+
+  await dl2.goto(hash)
+  await dl3.goto(hash)
+
+  const [download2, download3] = await Promise.all([
+    dl2.clickDownload(),
+    dl3.clickDownload()
+  ])
+
+  expect(download2.suggestedFilename()).toBe('concurrent.txt')
+  expect(download3.suggestedFilename()).toBe('concurrent.txt')
+
+  await context.close()
+})
+```
+
+### 6.7 Redirect File Handling (Multi-packet)
+
+**Test ID**: `edge-redirect-file`
+
+```typescript
+test.slow()
+test('upload and download multi-chunk file with redirect', async ({uploadPage, downloadPage}) => {
+  // Use ~5MB file to get multiple chunks
+  await uploadPage.selectLargeFile('multi-chunk.bin', 5 * 1024 * 1024)
+  const link = await uploadPage.waitForShareLink(120_000)
+
+  await downloadPage.gotoWithLink(link)
+  const download = await downloadPage.clickDownload()
+
+  expect(download.suggestedFilename()).toBe('multi-chunk.bin')
+
+  const path = await download.path()
+  if (path) {
+    const stat = (await import('fs')).statSync(path)
+    expect(stat.size).toBe(5 * 1024 * 1024)
+  }
+})
+```
+
+### 6.8 UI Information Display
+
+**Test ID**: `edge-ui-info`
+
+```typescript
+test('upload complete shows expiry and security note', async ({uploadPage}) => {
+  await uploadPage.selectTextFile('ui-test.txt', 'ui test')
+  await uploadPage.waitForShareLink()
+
+  await uploadPage.expectCompleteWithExpiry()
+  await uploadPage.expectSecurityNote()
+})
+
+test('download page shows file size and security note', async ({uploadPage, downloadPage}) => {
+  await uploadPage.selectFile('size-test.bin', createTestContent(1024))
+  const link = await uploadPage.waitForShareLink()
+
+  await downloadPage.gotoWithLink(link)
+  await downloadPage.expectFileSizeDisplayed()
+  await downloadPage.expectSecurityNote()
+})
+```
+
+---
+
+## 7. Implementation Order
+
+### Phase 1: Core Infrastructure (Priority: High)
+1. Create `test/pages/UploadPage.ts` with Page Object
+2. Create `test/pages/DownloadPage.ts` with Page Object
+3. Create `test/fixtures.ts` with extended test function
+4. Refactor existing test to use Page Objects
+
+### Phase 2: Core Happy Path (Priority: High)
+5. `upload-file-picker` - Basic upload via file picker
+6. `download-button-click` - Basic download
+7. `download-file-save` - Content verification
+
+### Phase 3: Validation (Priority: High)
+8. `upload-file-too-large` - Size validation
+9. `upload-file-empty` - Empty file validation
+10. `download-invalid-hash-malformed` - Invalid link handling
+11. `download-invalid-hash-structure` - Invalid structure handling
+
+### Phase 4: Progress and Cancel (Priority: Medium)
+12. `upload-progress-display` - Progress visibility
+13. `upload-cancel` - Cancel functionality
+14. `download-progress-display` - Download progress
+
+### Phase 5: Link Sharing (Priority: Medium)
+15. `upload-share-link-copy` - Copy button functionality
+16. `upload-drag-drop` - Drag-drop upload
+
+### Phase 6: Edge Cases (Priority: Low)
+17. `edge-small-file` - 1-byte file
+18. `edge-special-chars-filename` - Unicode/special characters
+19. `edge-binary-content` - Binary content integrity
+20. `edge-near-limit` - 100MB file (slow test)
+21. `edge-network-error` - Network error handling
+
+### Phase 7: Error Recovery and Advanced (Priority: Low)
+22. `upload-error-retry` - Retry after error
+23. `edge-concurrent-downloads` - Concurrent access
+24. `edge-redirect-file` - Multi-packet file with redirect (slow)
+25. `edge-ui-info` - Expiry message, security notes
+
+---
+
+## 8. Test Utilities
+
+### 8.1 Shared Test Setup
+
+```typescript
+// test/page.spec.ts
+import {test, expect, createTestContent, createTextContent, uniqueFileName} from './fixtures'
+
+test.describe('Upload Flow', () => {
+  test('upload via file picker', async ({uploadPage}) => {
+    // Tests use uploadPage fixture which navigates automatically
+  })
+})
+
+test.describe('Download Flow', () => {
+  test('download works', async ({uploadPage, downloadPage}) => {
+    // Both pages available via fixtures
+  })
+})
+
+test.describe('Edge Cases', () => {
+  // Edge case tests
+})
+```
+
+### 8.2 File Structure
+
+```
+xftp-web/test/
+├── fixtures.ts           # Playwright fixtures with page objects
+├── pages/
+│   ├── UploadPage.ts     # Upload page object
+│   └── DownloadPage.ts   # Download page object
+├── page.spec.ts          # All E2E tests
+└── globalSetup.ts        # Server startup (existing)
+```
+
+---
+
+## Appendix: Test Matrix
+
+| Test ID | Category | Priority | Estimated Time | Dependencies |
+|---------|----------|----------|----------------|--------------|
+| upload-file-picker | Upload | High | 30s | - |
+| upload-drag-drop | Upload | Medium | 30s | - |
+| upload-file-too-large | Upload | High | 5s | - |
+| upload-file-empty | Upload | High | 5s | - |
+| upload-progress-display | Upload | Medium | 45s | - |
+| upload-cancel | Upload | Medium | 30s | - |
+| upload-share-link-copy | Upload | Medium | 30s | - |
+| upload-error-retry | Upload | Low | 30s | - |
+| download-invalid-hash-malformed | Download | High | 5s | - |
+| download-invalid-hash-structure | Download | High | 5s | - |
+| download-button-click | Download | High | 45s | upload |
+| download-progress-display | Download | Medium | 60s | upload |
+| download-file-save | Download | High | 45s | upload |
+| edge-small-file | Edge | Low | 30s | - |
+| edge-near-limit | Edge | Low | 300s | - |
+| edge-special-chars-filename | Edge | Low | 30s | - |
+| edge-network-error | Edge | Low | 45s | - |
+| edge-binary-content | Edge | Low | 30s | - |
+| edge-concurrent-downloads | Edge | Low | 60s | upload |
+| edge-redirect-file | Edge | Low | 120s | - |
+| edge-ui-info | Edge | Low | 60s | upload |
+
+**Total estimated time**: ~18 minutes (excluding 100MB and 5MB tests)

rfcs/done/2026-01-30-send-file-page/2026-02-08-xftp-web-hello-header.md

@@ -0,0 +1,221 @@
+# XFTP Web Hello Header — Session Re-handshake for Browser Connection Reuse
+
+## 1. Problem Statement
+
+Browser HTTP/2 connection pooling reuses TLS connections across page navigations (same origin = same connection pool). The XFTP router maintains per-TLS-connection session state in `TMap SessionId Handshake` keyed by `tlsUniq tls`. When a browser navigates from the upload page to the download page (or reloads), the new page sends a fresh ClientHello on the reused HTTP/2 connection. The server is already in `HandshakeAccepted` state for that connection, so it routes the request to `processRequest`, which expects a 16384-byte command block but receives a 34-byte ClientHello → `ERR BLOCK`.
+
+**Root cause**: The router cannot distinguish a ClientHello from a command on an already-handshaked connection because both arrive on the same HTTP/2 connection (same `tlsUniq`), and there is no content-level discriminator (ClientHello is unpadded, but the router never gets to parse it — the size check in `processRequest` rejects it first).
+
+**Browser limitation**: `fetch()` provides zero control over HTTP/2 connection pooling. There is no browser API to force a new connection or detect connection reuse before a request is sent.
+
+## 2. Solution Summary
+
+Add an HTTP header `xftp-web-hello` to web ClientHello requests. When the router sees this header on an already-handshaked connection (`HandshakeAccepted` state), it re-runs `processHello` **reusing the existing session keys** (same X25519 key pair from the original handshake). The client then completes the normal handshake flow (sends ClientHandshake, receives ack) and proceeds with commands.
+
+Key properties:
+- Router reuses existing `serverPrivKey` — no new key material generated on re-handshake, so `thAuth` remains consistent with any in-flight commands on concurrent HTTP/2 streams.
+- Header is only checked when `sniUsed` is true (web/browser connections). Native XFTP clients are unaffected.
+- CORS preflight already allows all headers (`Access-Control-Allow-Headers: *`).
+- Web clients always send this header on ClientHello — it's harmless on first connection (`Nothing` state) and enables re-handshake on reused connections (`HandshakeAccepted` state).
+
+## 3. Detailed Technical Design
+
+### 3.1 Router change: parameterize `processHello` (`src/Simplex/FileTransfer/Server.hs`)
+
+The entire router change is parameterizing the existing `processHello` with `Maybe C.PrivateKeyX25519`. Zero new functions.
+
+#### Current code (lines 165-191):
+
+```haskell
+xftpServerHandshakeV1 chain serverSignKey sessions
+  XFTPTransportRequest {thParams = thParams0@THandleParams {sessionId}, reqBody = HTTP2Body {bodyHead}, sendResponse, sniUsed, addCORS} = do
+    s <- atomically $ TM.lookup sessionId sessions
+    r <- runExceptT $ case s of
+      Nothing -> processHello
+      Just (HandshakeSent pk) -> processClientHandshake pk
+      Just (HandshakeAccepted thParams) -> pure $ Just thParams
+    either sendError pure r
+    where
+      processHello = do
+        challenge_ <-
+          if
+            | B.null bodyHead -> pure Nothing
+            | sniUsed -> do
+                XFTPClientHello {webChallenge} <- liftHS $ smpDecode bodyHead
+                pure webChallenge
+            | otherwise -> throwE HANDSHAKE
+        (k, pk) <- atomically . C.generateKeyPair =<< asks random
+        atomically $ TM.insert sessionId (HandshakeSent pk) sessions
+        -- ...build and send ServerHandshake...
+        pure Nothing
+```
+
+#### After (diff is ~10 lines):
+
+```haskell
+xftpServerHandshakeV1 chain serverSignKey sessions
+  XFTPTransportRequest {thParams = thParams0@THandleParams {sessionId}, request, reqBody = HTTP2Body {bodyHead}, sendResponse, sniUsed, addCORS} = do
+--                                                                      ^^^^^^^ bind request
+    s <- atomically $ TM.lookup sessionId sessions
+    r <- runExceptT $ case s of
+      Nothing -> processHello Nothing
+      Just (HandshakeSent pk) -> processClientHandshake pk
+      Just (HandshakeAccepted thParams)
+        | webHello -> processHello (serverPrivKey <$> thAuth thParams)
+        | otherwise -> pure $ Just thParams
+    either sendError pure r
+    where
+      webHello = sniUsed && any (\(t, _) -> tokenKey t == "xftp-web-hello") (fst $ H.requestHeaders request)
+      processHello pk_ = do
+        challenge_ <-
+          if
+            | B.null bodyHead -> pure Nothing
+            | sniUsed -> do
+                XFTPClientHello {webChallenge} <- liftHS $ smpDecode bodyHead
+                pure webChallenge
+            | otherwise -> throwE HANDSHAKE
+        (k, pk) <- maybe
+          (atomically . C.generateKeyPair =<< asks random)
+          (\pk -> pure (C.publicKey pk, pk))
+          pk_
+        atomically $ TM.insert sessionId (HandshakeSent pk) sessions
+        -- ...rest unchanged...
+        pure Nothing
+```
+
+#### What changes:
+
+1. **Bind `request`** in the `XFTPTransportRequest` pattern (+1 field)
+2. **Add `webHello`** binding in `where` clause (1 line) — checks header only when `sniUsed`
+3. **Add `pk_` parameter** to `processHello` (change signature)
+4. **Replace key generation** with `maybe` that generates fresh keys when `pk_ = Nothing`, or derives public from existing private when `pk_ = Just pk` (3 lines replace 1 line)
+5. **Add guard** in `HandshakeAccepted` branch (2 lines replace 1 line)
+6. **Call site** `Nothing -> processHello Nothing` (+1 word)
+7. **One import** added: `Network.HPACK.Token (tokenKey)`
+
+#### Imports to add:
+
+```haskell
+import Network.HPACK.Token (tokenKey)
+```
+
+`OverloadedStrings` (already enabled in Server.hs) provides the `IsString` instance for `CI ByteString`, so `tokenKey t == "xftp-web-hello"` works without importing `Data.CaseInsensitive`. Verified on Hackage: `requestHeaders :: Request -> HeaderTable`, `tokenKey :: Token -> CI ByteString`.
+
+### 3.2 Re-handshake flow
+
+When `webHello` is true in `HandshakeAccepted` state:
+
+1. `processHello (serverPrivKey <$> thAuth thParams)` is called with `Just pk` (existing private key)
+2. `(k, pk) <- pure (C.publicKey pk, pk)` — reuses same key pair, no generation
+3. `TM.insert sessionId (HandshakeSent pk) sessions` — transitions state back to `HandshakeSent` with same `pk`
+4. Server sends `ServerHandshake` response (same format as initial handshake)
+5. Client sends `ClientHandshake` on next stream → enters `Just (HandshakeSent pk) -> processClientHandshake pk` → normal flow
+6. `processClientHandshake` stores `HandshakeAccepted thParams` with same `serverPrivKey = pk`
+
+### 3.3 Web client change (`xftp-web/src/client.ts`)
+
+Add optional `headers?` parameter to `Transport.post()`, thread it through `fetch()` and `session.request()`, and pass `{"xftp-web-hello": "1"}` in the ClientHello call in `connectXFTP`.
+
+### 3.4 What does NOT change
+
+- **CORS**: Already has `Access-Control-Allow-Headers: *` (Server.hs:106).
+- **Native Haskell client**: Uses `[]` headers. No header = existing behavior.
+- **Protocol wire format**: ClientHello, ServerHandshake, ClientHandshake, commands — all unchanged.
+- **`processRequest`**, **`processClientHandshake`**, **`sendError`**, **`encodeXftp`** — unchanged.
+
+### 3.5 Haskell test (`tests/XFTPServerTests.hs`)
+
+Add `testWebReHandshake` next to the existing `testWebHandshake` (line 504). It reuses the same SNI + HTTP/2 setup pattern, performs a full handshake, then sends a second ClientHello with the `xftp-web-hello` header on the same connection and verifies the router responds with a valid ServerHandshake (same `sessionId`), then completes the second handshake.
+
+```haskell
+-- Register in xftpServerTests (after line 86):
+it "should re-handshake on same connection with xftp-web-hello header" testWebReHandshake
+
+-- Test (after testWebHandshake):
+testWebReHandshake :: Expectation
+testWebReHandshake =
+  withXFTPServerSNI $ \_ -> do
+    Fingerprint fp <- loadFileFingerprint "tests/fixtures/ca.crt"
+    let keyHash = C.KeyHash fp
+        cfg = defaultTransportClientConfig {clientALPN = Just ["h2"], useSNI = True}
+    runTLSTransportClient defaultSupportedParamsHTTPS Nothing cfg Nothing "localhost" xftpTestPort (Just keyHash) $ \(tls :: TLS 'TClient) -> do
+      let h2cfg = HC.defaultHTTP2ClientConfig {HC.bodyHeadSize = 65536}
+      h2 <- either (error . show) pure =<< HC.attachHTTP2Client h2cfg (THDomainName "localhost") xftpTestPort mempty 65536 tls
+      g <- C.newRandom
+      -- First handshake (same as testWebHandshake)
+      challenge1 <- atomically $ C.randomBytes 32 g
+      let helloReq1 = H2.requestBuilder "POST" "/" [] $ byteString (smpEncode (XFTPClientHello {webChallenge = Just challenge1}))
+      resp1 <- either (error . show) pure =<< HC.sendRequest h2 helloReq1 (Just 5000000)
+      shs1 <- either error pure $ smpDecode =<< C.unPad (bodyHead (HC.respBody resp1))
+      let XFTPServerHandshake {sessionId = sid1} = shs1
+      clientHsPadded <- either (error . show) pure $ C.pad (smpEncode (XFTPClientHandshake {xftpVersion = VersionXFTP 1, keyHash})) xftpBlockSize
+      resp1b <- either (error . show) pure =<< HC.sendRequest h2 (H2.requestBuilder "POST" "/" [] $ byteString clientHsPadded) (Just 5000000)
+      B.length (bodyHead (HC.respBody resp1b)) `shouldBe` 0
+      -- Second handshake on same connection with xftp-web-hello header
+      challenge2 <- atomically $ C.randomBytes 32 g
+      let helloReq2 = H2.requestBuilder "POST" "/" [("xftp-web-hello", "1")] $ byteString (smpEncode (XFTPClientHello {webChallenge = Just challenge2}))
+      resp2 <- either (error . show) pure =<< HC.sendRequest h2 helloReq2 (Just 5000000)
+      shs2 <- either error pure $ smpDecode =<< C.unPad (bodyHead (HC.respBody resp2))
+      let XFTPServerHandshake {sessionId = sid2} = shs2
+      sid2 `shouldBe` sid1  -- same TLS connection → same sessionId
+      -- Complete second handshake
+      resp2b <- either (error . show) pure =<< HC.sendRequest h2 (H2.requestBuilder "POST" "/" [] $ byteString clientHsPadded) (Just 5000000)
+      B.length (bodyHead (HC.respBody resp2b)) `shouldBe` 0
+```
+
+The only difference from `testWebHandshake`: the second `helloReq2` passes `[("xftp-web-hello", "1")]` instead of `[]`. The test verifies:
+1. Server responds with `ServerHandshake` (not `ERR BLOCK`)
+2. Same `sessionId` (same TLS connection)
+3. Second `ClientHandshake` completes with empty ACK
+
+## 4. Implementation Plan
+
+### Step 1: Router — parameterize `processHello`
+
+Apply the diff from Section 3.1 to `src/Simplex/FileTransfer/Server.hs`.
+
+### Step 2: Test — add `testWebReHandshake`
+
+Add the test from Section 3.5 to `tests/XFTPServerTests.hs`.
+
+### Step 3: Client — add `xftp-web-hello` header
+
+Add optional `headers?` to `Transport.post()`, pass `{"xftp-web-hello": "1"}` on ClientHello in `connectXFTP`.
+
+### Step 4: Test
+
+Run Haskell tests (`cabal test`) and E2E Playwright tests (`npx playwright test` in `xftp-web/`).
+
+## 5. Race Condition Analysis
+
+### Single-tab navigation (the common case)
+
+1. Upload page completes, all fetch() requests finish
+2. Browser navigates to download page (or reloads)
+3. All upload-page fetches are aborted on page unload
+4. Download page sends ClientHello with `xftp-web-hello` header
+5. Server is in `HandshakeAccepted` → `processHello (Just pk)` → `HandshakeSent pk` (same key)
+6. No concurrent streams → no race
+
+**Safe.**
+
+### Multi-tab (edge case)
+
+Tab A (upload) and Tab B (download) share the same HTTP/2 connection.
+
+1. Tab A has active command streams (e.g., FPUT upload in progress)
+2. Tab B sends ClientHello with header
+3. Server reads `HandshakeAccepted` atomically for both streams
+4. Tab A's stream already has its `thParams` snapshot → proceeds with `processRequest` using old `thParams`
+5. Tab B's stream triggers `processHello (Just pk)` → stores `HandshakeSent pk` (same pk!)
+6. Tab A's in-progress FPUT continues with snapshot `thParams` → completes normally (same `serverPrivKey`)
+7. Tab A's NEXT command reads `HandshakeSent` from TMap → enters `processClientHandshake` → fails (command body ≠ ClientHandshake format) → HANDSHAKE error
+
+**Tab A's in-flight commands succeed. Tab A's subsequent commands fail with HANDSHAKE error.** This is the inherent multi-tab problem — unavoidable with per-connection session state and HTTP/2 connection sharing. The failure is clean (HANDSHAKE error, not silent corruption).
+
+## 6. Security Considerations
+
+- **No new key material**: Re-handshake reuses existing `serverPrivKey`. No opportunity for key confusion or downgrade.
+- **Identity re-verification**: Router re-signs the web challenge with its long-term signing key. Client verifies identity again.
+- **Header cannot escalate privileges**: The header only triggers re-handshake (which the router was already capable of doing on first connection). It does not bypass any authentication.
+- **Timing**: Re-handshake takes the same code path as initial handshake, so timing side-channels are unchanged.

rfcs/done/2026-01-30-send-file-page/2026-02-11-xftp-web-error-handling.md

@@ -0,0 +1,948 @@
+# XFTP Web Error Handling and Connection Resilience
+
+## 1. Problem Statement
+
+The XFTP web client is fundamentally fragile: any transient error (browser opening a new HTTP/2 connection, network hiccup, router restart) causes an unrecoverable failure with a cryptic error message. There is no retry logic, no fetch timeout, no error categorization, and the upload uses a single router instead of distributing data packets across preset routers. This makes the app frustrating — it works most of the time but fails unpredictably, which is worse than being completely broken.
+
+### Confirmed root cause (from diagnostic logs)
+
+When the browser opens a new HTTP/2 connection mid-operation, the new connection has a different TLS SessionId with no handshake state in the router's `TMap SessionId Handshake`. The router's `Nothing` branch in `xftpServerHandshakeV1` (Server.hs:169) unconditionally calls `processHello`, which tries to decode the command body as `XFTPClientHello`, fails, and sends a raw padded "HANDSHAKE" error string. The client cannot parse this as a proper transmission (first byte 'H' = 72 is read as batch count), producing `"expected batch count 1, got 72"`.
+
+Router log confirming the SessionId change:
+```
+DEBUG dispatch: Accepted+command sessId="ZSo1GGETgIvjbB7CWHbvGPpbMjx_b2IlC1eTI6aKfqc="
+...20 successful commands...
+DEBUG dispatch: Nothing sessId="mJC7Sck9xxW5UsXoPGoUWduuHghSVgf6CnD6ZC6SBhU=" webHello=False
+```
+
+### Why re-handshake is required (cannot be made optional)
+
+1. **SessionId is baked into signed command data.** `encodeAuthTransmission` signs `concat(encode(sessionId), tInner)` with Ed25519. Router's `tDecodeServer` (Protocol.hs:2242) verifies `sessId == sessionId`. New connection = different sessionId = signature mismatch.
+2. **Router generates per-session DH keys.** `processHello` creates fresh X25519 keypair stored in `HandshakeSent`. For SMP browser clients (future), `verifyCmdAuth` (Protocol.hs:1322) requires the matching `serverPrivKey` from `thAuth`.
+3. **This applies to both XFTP and future SMP browser clients** — the session management approach is the same.
+
+### Why multiple preset routers cannot work
+
+Upload (`agent.ts:105-157`) takes a single `server: XFTPServer` parameter and uploads ALL data packets to it. `web/upload.ts:133` calls `pickRandomServer(servers)` which selects ONE random router from all presets. The multi-router preset configuration is pointless — only one router is ever used per upload. The design intent (RFC section 11.6: "upload in parallel to 8 randomly selected routers") is not implemented. This must be fixed in Phase 2 (section 3.7).
+
+## 2. Solution Summary
+
+### Phase 1: Error handling and connection resilience
+
+1. **Router: strict dispatch for allowed protocol combinations** — reject all invalid combinations
+2. **Client: automatic retry with re-handshake** on SESSION/HANDSHAKE errors
+3. **Client: fetch timeout** with configurable duration
+4. **UI: error categorization and retry** — auto-retry temporary, human-readable permanent
+5. **Client: connection state with Promise-based lock and per-router queues** — `ServerConnection` with `client: Promise<XFTPClient>` + `queue: Promise<void>`
+6. **Client: fix cache key** — include keyHash
+
+### Phase 2: Multi-router upload (after Phase 1)
+
+7. **Multi-router upload with router selection and failover** — distribute data packets across routers, retry FNEW on different router if one fails
+
+## 3. Detailed Technical Design
+
+### 3.1 Router: strict dispatch for allowed protocol combinations
+
+**Principle:** Everything not explicitly done by existing Haskell/TS clients is prohibited. It is better to fail on impossible combinations than to be permissive — permissiveness complicates debugging and creates attack vectors via unexpected behaviors.
+
+**Allowed behaviors by client type:**
+
+| Client | SNI | webHello header | Hello body | When |
+|--------|-----|----------------|------------|------|
+| Haskell | No | No | Empty | New connection only |
+| Web | Yes | Yes | Non-empty (XFTPClientHello) | New OR existing connection |
+
+**Minimal surgical change.** The existing dispatch (Server.hs:169-189) already correctly handles `HandshakeSent` and `HandshakeAccepted` — their guards cover all valid and invalid combinations. The ONLY missing case is `Nothing` + web client sending a command on a stale session.
+
+`processHello` (Server.hs:194-217) already internally routes: `B.null bodyHead` → Haskell hello, `sniUsed` → web hello decode, else → HANDSHAKE. For stale web sessions, it currently tries to decode a command body as `XFTPClientHello`, fails, and throws HANDSHAKE. The fix: detect this case BEFORE calling processHello and throw SESSION instead, so the client knows to re-handshake (not that its hello was malformed).
+
+**Change: add one guard to `Nothing` branch, remove debug logging.**
+
+```haskell
+-- Before (1 line):
+Nothing -> processHello Nothing
+
+-- After (3 lines):
+Nothing
+  | sniUsed && not webHello -> throwE SESSION  -- web command on stale session
+  | otherwise -> processHello Nothing          -- normal hello (web or Haskell)
+```
+
+`throwE SESSION` is caught by `either sendError pure r` (line 190). `sendError` pads `smpEncode SESSION` = `"SESSION"` (Transport.hs:298) to `xftpBlockSize`. The client's padded error detection (section 3.2) catches this as a retriable error and triggers re-handshake. SESSION is a valid `XFTPErrorType` constructor (Transport.hs:225) — no new helpers needed.
+
+**All other branches remain unchanged.** `HandshakeSent` guards (`webHello` → processHello, `otherwise` → processClientHandshake with body size check inside) are correct. `HandshakeAccepted` guards (`webHello`, `webHandshake`, `otherwise` → command) are correct.
+
+### 3.2 Client: automatic retry with re-handshake
+
+**Location:** `sendXFTPCommand` in `client.ts`
+
+**Design:** Retry loop inside `sendXFTPCommand`. Maximum 3 attempts. On retriable error, close old client, re-handshake, retry.
+
+**Error classification:**
+
+| Error | Type | Retriable? | Human-readable message |
+|-------|------|-----------|----------------------|
+| Padded "HANDSHAKE" | Temporary | Yes (auto) | "Connection interrupted, reconnecting..." |
+| Padded "SESSION" | Temporary | Yes (auto) | "Session expired, reconnecting..." |
+| `FRErr SESSION` | Temporary | Yes (auto) | "Session expired, reconnecting..." |
+| `FRErr HANDSHAKE` | Temporary | Yes (auto) | "Connection interrupted, reconnecting..." |
+| `fetch()` TypeError | Temporary | Yes (auto) | "Network error, retrying..." |
+| AbortError (timeout) | Temporary | Yes (auto) | "Router timeout, retrying..." |
+| `FRErr AUTH` | Permanent | No | "File is invalid, expired, or has been removed" |
+| `FRErr NO_FILE` | Permanent | No | "File not found — it may have expired" |
+| `FRErr SIZE` | Permanent | No | "File size exceeds router limit" |
+| `FRErr QUOTA` | Permanent | No | "Router storage quota exceeded" |
+| `FRErr BLOCKED` | Permanent | No | "File has been blocked by router" |
+| `FRErr DIGEST` | Permanent | No | "File integrity check failed" |
+| `FRErr INTERNAL` | Permanent | No | "Router internal error" |
+| `CMD *` | Permanent | No | "Protocol error" |
+
+**Retry behavior:**
+- Auto-retry up to 3 times for temporary errors, transparent to user
+- After 3 failures: show human-readable error with diagnosis, offer manual retry button
+- Permanent errors: show human-readable error immediately, NO manual retry button (user can reload page)
+
+**Implementation:**
+
+```typescript
+async function sendXFTPCommand(
+  agent: XFTPClientAgent,
+  server: XFTPServer,
+  privateKey: Uint8Array,
+  entityId: Uint8Array,
+  cmdBytes: Uint8Array,
+  chunkData?: Uint8Array,
+  maxRetries: number = 3
+): Promise<{response: FileResponse, body: Uint8Array}> {
+  let clientP = getXFTPServerClient(agent, server)
+  let client = await clientP
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await sendXFTPCommandOnce(client, privateKey, entityId, cmdBytes, chunkData)
+    } catch (e) {
+      if (!isRetriable(e)) {
+        // Permanent error (AUTH, NO_FILE, etc.) — connection is fine, don't touch it
+        throw categorizeError(e)
+      }
+      if (attempt === maxRetries) {
+        // Retriable error exhausted — connection is bad, remove stale promise
+        removeStaleConnection(agent, server, clientP)
+        throw categorizeError(e)
+      }
+      clientP = reconnectClient(agent, server)
+      client = await clientP
+    }
+  }
+  throw new Error("unreachable")
+}
+```
+
+**`sendXFTPCommandOnce`** — renamed from current `sendXFTPCommand`. Two changes:
+
+1. **Padded error detection** (before `decodeTransmission`):
+
+```typescript
+// After getting respBlock, before decodeTransmission:
+const raw = blockUnpad(respBlock)
+if (raw.length < 20) {
+  const text = new TextDecoder().decode(raw)
+  if (/^[A-Z_]+$/.test(text)) {
+    throw new XFTPRetriableError(text)  // "HANDSHAKE" or "SESSION"
+  }
+}
+```
+
+2. **FRErr classification** (replaces current unconditional throw):
+
+```typescript
+// After decodeResponse, instead of throw new Error("Router error: " + err.type):
+if (response.type === "FRErr") {
+  const err = response.err
+  if (err.type === "SESSION" || err.type === "HANDSHAKE") {
+    throw new XFTPRetriableError(err.type)
+  }
+  throw new XFTPPermanentError(err.type, humanReadableMessage(err))
+}
+```
+
+### 3.3 Client: fetch timeout
+
+**Location:** `createBrowserTransport` and `createNodeTransport` in `client.ts`
+
+**Design:** `AbortController` with configurable timeout on every `fetch()`.
+
+```typescript
+interface TransportConfig {
+  timeoutMs: number  // default 30000, lower for tests
+}
+
+function createBrowserTransport(baseUrl: string, config: TransportConfig): Transport {
+  return {
+    async post(body: Uint8Array, headers?: Record<string, string>): Promise<Uint8Array> {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), config.timeoutMs)
+      try {
+        const resp = await fetch(effectiveUrl, {
+          method: "POST", headers, body,
+          signal: controller.signal
+        })
+        if (!resp.ok) throw new Error(`Server request failed: ${resp.status}`)
+        return new Uint8Array(await resp.arrayBuffer())
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+    close() {}
+  }
+}
+```
+
+For Node.js transport, use `setTimeout` on the HTTP/2 request stream.
+
+Default: 30s for production, 5s for tests. Threaded through `connectXFTP` → `createTransport`.
+
+### 3.4 UI: error categorization and retry
+
+**Behavior (Option D):**
+
+- **Temporary errors:** Auto-retry loop (3 attempts). After 3 failures, show human-readable diagnosis with manual retry button. Diagnosis examples: "Router timeout — the router may be temporarily unavailable", "Connection interrupted — your network may be unstable".
+- **Permanent errors:** Show human-readable error immediately, NO retry button. User can reload page if they want to retry. Examples: "File is invalid, expired, or has been removed" (AUTH), "File not found" (NO_FILE).
+
+**Current UI retry buttons:**
+- `upload.ts:73-75` — retry calls `startUpload(pendingFile)` from scratch
+- `download.ts:60` — retry calls `startDownload()` from scratch
+
+**Improvement:** Track uploaded/downloaded data packet indices. On manual retry, skip completed data packets:
+
+```typescript
+// Upload: track which data packets completed
+const completedChunks: Set<number> = new Set()
+for (let i = 0; i < specs.length; i++) {
+  if (completedChunks.has(i)) continue
+  // ... create + upload data packet
+  completedChunks.add(i)
+}
+
+// Download: already naturally resumable — each data packet is independent
+```
+
+### 3.5 Client: connection state with Promise-based lock and per-router queues
+
+**Design:** Each router gets a `ServerConnection` record containing a `Promise<XFTPClient>` (the connection lock) and a `Promise<void>` (the sequential command queue). The `XFTPClientAgent` maps router keys to these records.
+
+The promise IS the lock — every consumer awaits the same promise. When reconnect is needed, the promise is replaced atomically.
+
+```typescript
+interface ServerConnection {
+  client: Promise<XFTPClient>   // resolves to connected client; replaced on reconnect
+  queue: Promise<void>          // tail of sequential command chain
+}
+
+interface XFTPClientAgent {
+  connections: Map<string, ServerConnection>
+}
+
+function newXFTPAgent(): XFTPClientAgent {
+  return {connections: new Map()}
+}
+```
+
+**Connection lifecycle — `getXFTPServerClient` and `reconnectClient`:**
+
+```typescript
+function getXFTPServerClient(agent: XFTPClientAgent, server: XFTPServer): Promise<XFTPClient> {
+  const key = formatXFTPServer(server)
+  let conn = agent.connections.get(key)
+  if (!conn) {
+    const p = connectXFTP(server)
+    conn = {client: p, queue: Promise.resolve()}
+    agent.connections.set(key, conn)
+    // On connection failure, remove from map so next call retries
+    p.catch(() => {
+      const cur = agent.connections.get(key)
+      if (cur && cur.client === p) agent.connections.delete(key)
+    })
+  }
+  return conn.client
+}
+
+function reconnectClient(agent: XFTPClientAgent, server: XFTPServer): Promise<XFTPClient> {
+  const key = formatXFTPServer(server)
+  const old = agent.connections.get(key)
+  // Close old client (fire-and-forget)
+  old?.client.then(c => c.transport.close(), () => {})
+  // Replace with new connection promise — all concurrent callers will await this
+  // Queue survives reconnect — pending operations stay ordered
+  const p = connectXFTP(server)
+  const conn: ServerConnection = {client: p, queue: old?.queue ?? Promise.resolve()}
+  agent.connections.set(key, conn)
+  p.catch(() => {
+    const cur = agent.connections.get(key)
+    if (cur && cur.client === p) agent.connections.delete(key)
+  })
+  return p
+}
+
+function closeXFTPServerClient(agent: XFTPClientAgent, server: XFTPServer): void {
+  const key = formatXFTPServer(server)
+  const conn = agent.connections.get(key)
+  if (conn) {
+    agent.connections.delete(key)
+    conn.client.then(c => c.transport.close(), () => {})
+  }
+}
+
+function closeXFTPAgent(agent: XFTPClientAgent): void {
+  for (const conn of agent.connections.values()) {
+    conn.client.then(c => c.transport.close(), () => {})
+  }
+  agent.connections.clear()
+}
+```
+
+**Precise semantics:**
+
+1. `getXFTPServerClient(agent, server)` — returns existing `conn.client` promise if present, otherwise creates a new `ServerConnection` with fresh connection and empty queue
+2. When error detected, first caller calls `reconnectClient` which replaces `conn.client` with a new connection promise. The queue is preserved across reconnect.
+3. All concurrent callers awaiting the OLD promise receive the error
+4. They then call `getXFTPServerClient` which returns the NEW promise
+5. If reconnection fails, auto-cleanup (`p.catch(() => delete)`) removes the entry so the next caller starts fresh
+
+**Stale error cleanup rule:** When a caller exhausts retries for a retriable error, it removes the failed entry from the map (only if no concurrent caller has already replaced it via `reconnectClient`). This prevents the next caller from receiving a stale rejected promise. Permanent errors (AUTH, NO_FILE, etc.) do NOT remove the connection — the transport is fine, only the command failed.
+
+```typescript
+function removeStaleConnection(
+  agent: XFTPClientAgent, server: XFTPServer, failedP: Promise<XFTPClient>
+): void {
+  const key = formatXFTPServer(server)
+  const conn = agent.connections.get(key)
+  // Only remove if current promise is the one that failed — not if already replaced by reconnect
+  if (conn && conn.client === failedP) {
+    agent.connections.delete(key)
+    failedP.then(c => c.transport.close(), () => {})
+  }
+}
+```
+
+**Per-router sequential queue:** `queue` is a `Promise<void>` — the tail of the sequential operation chain. Each new operation `.then()`s onto it. It's `void` because callers hold their own typed promises; the queue only tracks completion order:
+
+```typescript
+async function enqueueCommand<T>(
+  agent: XFTPClientAgent,
+  server: XFTPServer,
+  fn: () => Promise<T>   // no client param — fn uses command wrappers (agent+server)
+): Promise<T> {
+  const key = formatXFTPServer(server)
+  // Ensure connection exists (with auto-cleanup on failure)
+  await getXFTPServerClient(agent, server)
+  const conn = agent.connections.get(key)!  // guaranteed to exist after getXFTPServerClient
+  // Chain onto the queue — fn runs after previous operation completes
+  let resolve_: (v: T) => void, reject_: (e: any) => void
+  const result = new Promise<T>((res, rej) => { resolve_ = res; reject_ = rej })
+  conn.queue = conn.queue.then(
+    () => fn().then(resolve_!, reject_!),
+    () => fn().then(resolve_!, reject_!)
+  ).then(() => {}, () => {})  // swallow errors in the chain
+  return result
+}
+```
+
+Commands to the same router execute one at a time via the queue. Commands to different routers execute concurrently because each has its own queue. `enqueueCommand` provides sequencing; `sendXFTPCommand` (called inside `fn` via command wrappers) provides retry. They compose as: `enqueueCommand` sequences calls to wrappers that internally use `sendXFTPCommand`.
+
+**Download change:** Group data packets by router, process each router's data packets sequentially, routers in parallel. Uses `for` loop for per-router sequencing (same pattern as Stage 2 upload). `enqueueCommand` is available for cases where different callers target the same router.
+
+```typescript
+const byServer = new Map<string, FileChunk[]>()
+for (const chunk of resolvedFd.chunks) {
+  const srv = chunk.replicas[0]?.server ?? ""
+  if (!byServer.has(srv)) byServer.set(srv, [])
+  byServer.get(srv)!.push(chunk)
+}
+await Promise.all([...byServer.entries()].map(async ([srv, chunks]) => {
+  const server = parseXFTPServer(srv)
+  for (const chunk of chunks) {
+    const seed = decodePrivKeyEd25519(chunk.replicas[0].replicaKey)
+    const kp = ed25519KeyPairFromSeed(seed)
+    const raw = await downloadXFTPChunkRaw(agent, server, kp.privateKey, chunk.replicas[0].replicaId)
+    await onRawChunk({chunkNo: chunk.chunkNo, dhSecret: raw.dhSecret, nonce: raw.nonce, body: raw.body, digest: chunk.digest})
+    downloaded += chunk.chunkSize
+    onProgress?.(downloaded, resolvedFd.size)
+  }
+}))
+```
+
+### 3.6 Fix cache key
+
+**Bug:** `getXFTPServerClient` (client.ts:110) uses `"https://" + server.host + ":" + server.port` as cache key, ignoring `keyHash`. Two routers with same host:port but different keyHash share a cached connection, bypassing identity verification.
+
+**Fix:** Use `formatXFTPServer(server)` as cache key (includes keyHash). Already available in `protocol/address.ts:52-54`.
+
+```typescript
+// Before:
+const key = "https://" + server.host + ":" + server.port
+
+// After:
+const key = formatXFTPServer(server)
+```
+
+Note: With the redesign in 3.5, the cache key fix is inherent — the `connections` Map uses `formatXFTPServer(server)` everywhere.
+
+### 3.7 Phase 2: Multi-router upload with router selection and failover
+
+**Problem:** Current upload (`agent.ts:105-157`) takes a single `server: XFTPServer` and uploads ALL data packets to it. The 12 preset routers (6 SimpleX + 6 Flux) are pointless — only one is ever used.
+
+**Design goal:** Distribute data packets across routers. Retry FNEW on a different router if one fails. Once working routers are found, prefer them (heuristic: router unlikely to fail mid-process, more likely to be broken initially due to maintenance/downtime).
+
+**Reference implementation:** Haskell `Agent.hs:457-486` (`createChunk` / `createWithNextSrv`) + `Client.hs:2335-2385` (`getNextServer_` / `withNextSrv`).
+
+#### Haskell algorithm summary
+
+Two-stage architecture:
+
+1. **Allocate stage (serial per file in Haskell):** For each data packet, call FNEW on a randomly-selected router. If FNEW fails, pick a different router and retry. Track tried hosts to avoid retrying the same router. After all data packets are assigned to routers, spawn one upload worker per router.
+
+2. **Upload stage (parallel per router):** Each router worker uploads its assigned data packets sequentially (FPUT). On FPUT failure, retry on the same router with backoff (because the data packet replica already exists on that router). No router failover for FPUT.
+
+Router selection constraints (hierarchical, `getNextServer_` Client.hs:2335-2350):
+1. Prefer routers from unused operators (operator diversity)
+2. Prefer routers with unused hosts (host diversity)
+3. Random pick from the most-constrained candidate set
+4. If all exhausted, reset tried set and start over
+
+#### Web client adaptation
+
+The web client doesn't have operators or a database. Simplified algorithm with two stages:
+
+**Stage 1 — Allocate:** Create data packet records on routers (FNEW). Unlike Haskell which is serial here, web FNEW runs concurrently within a concurrency limit. FNEW is a small command — concurrent FNEW on the same connection is not a problem, and concurrent FNEW across routers improves upload startup time.
+
+**Stage 2 — Upload:** Upload data packet content (FPUT). Parallel across routers, sequential per router (reuses per-router queues from 3.5). FPUT retries on the same router with backoff — no router rotation because the data packet replica already exists on that router. Stage 2 reads data packet content by offset (via `readChunk`), so `SentChunk` must be extended with `chunkOffset: number` (from ChunkSpec).
+
+```typescript
+interface UploadState {
+  untriedServers: XFTPServer[]    // routers not yet attempted — initially all routers
+  workingServers: XFTPServer[]    // routers that succeeded FNEW
+}
+
+const MAX_FNEW_ATTEMPTS = 5  // per data packet: try up to 5 different routers
+
+async function uploadFile(
+  agent: XFTPClientAgent,
+  allServers: XFTPServer[],
+  encrypted: EncryptedFileMetadata,
+  options?: UploadOptions
+): Promise<UploadResult> {
+  const state: UploadState = {untriedServers: [...allServers], workingServers: []}
+  const specs = prepareChunkSpecs(encrypted.chunkSizes)
+  const concurrency = options?.concurrency ?? 4
+
+  // Stage 1: Allocate — concurrent FNEW within concurrency limit
+  const sentChunks: SentChunk[] = new Array(specs.length)
+  const queue = specs.map((spec, i) => ({spec, chunkNo: i + 1, index: i}))
+  let idx = 0
+  async function allocateWorker() {
+    while (idx < queue.length) {
+      const item = queue[idx++]
+      const {server, chunk} = await createChunkWithFailover(
+        agent, allServers, state, concurrency, item.spec, item.chunkNo
+      )
+      sentChunks[item.index] = chunk
+    }
+  }
+  const allocateWorkers = Array.from(
+    {length: Math.min(concurrency, queue.length)},
+    () => allocateWorker()
+  )
+  await Promise.all(allocateWorkers)
+
+  // Stage 2: Upload — parallel across routers, sequential per router
+  // readChunk reads from the encrypted file by offset (same as Phase 1 uploadFile)
+  let uploaded = 0
+  const total = encrypted.chunkSizes.reduce((a, b) => a + b, 0)
+  const byServer = groupBy(sentChunks, c => formatXFTPServer(c.server))
+  await Promise.all([...byServer.entries()].map(async ([srvKey, chunks]) => {
+    for (const chunk of chunks) {
+      const chunkData = await readChunk(chunk.chunkOffset, chunk.chunkSize)
+      await uploadXFTPChunk(agent, chunk.server, chunk.senderKey, chunk.senderId, chunkData)
+      uploaded += chunk.chunkSize
+      options?.onProgress?.(uploaded, total)
+    }
+  }))
+
+  return buildDescriptions(encrypted, sentChunks)
+}
+```
+
+**`createChunkWithFailover`** — router selection with per-data-packet retry limit:
+
+```typescript
+async function createChunkWithFailover(
+  agent: XFTPClientAgent,
+  allServers: XFTPServer[],
+  state: UploadState,
+  concurrency: number,
+  spec: ChunkSpec,
+  chunkNo: number
+): Promise<{server: XFTPServer, chunk: SentChunk}> {
+  const maxAttempts = Math.min(allServers.length, MAX_FNEW_ATTEMPTS)
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const server = pickServer(allServers, state, concurrency)
+    try {
+      const chunk = await createAndPrepareChunk(agent, server, spec, chunkNo)
+      // Success — add to working set (if not already there)
+      if (!state.workingServers.some(s => formatXFTPServer(s) === formatXFTPServer(server))) {
+        state.workingServers.push(server)
+      }
+      return {server, chunk}
+    } catch (e) {
+      // Remove from working if it was there
+      state.workingServers = state.workingServers.filter(
+        s => formatXFTPServer(s) !== formatXFTPServer(server)
+      )
+      if (attempt === maxAttempts - 1) throw e
+    }
+  }
+  throw new Error("unreachable")
+}
+```
+
+**`pickServer`** — two-list selection:
+
+```typescript
+function pickServer(
+  allServers: XFTPServer[],
+  state: UploadState,
+  concurrency: number
+): XFTPServer {
+  // Once enough working routers found, only use those
+  if (state.workingServers.length >= concurrency) {
+    return randomPick(state.workingServers)
+  }
+  // Still exploring — pick from untried
+  if (state.untriedServers.length > 0) {
+    const idx = Math.floor(Math.random() * state.untriedServers.length)
+    return state.untriedServers.splice(idx, 1)[0]  // remove from untried
+  }
+  // All tried — reset untried to non-working routers and retry
+  state.untriedServers = allServers.filter(
+    s => !state.workingServers.some(w => formatXFTPServer(w) === formatXFTPServer(s))
+  )
+  if (state.untriedServers.length > 0) {
+    const idx = Math.floor(Math.random() * state.untriedServers.length)
+    return state.untriedServers.splice(idx, 1)[0]
+  }
+  // Every router is working — pick any working
+  return randomPick(state.workingServers)
+}
+```
+
+**Algorithm:** Two lists — `untriedServers` (initially all) and `workingServers` (initially empty). When `workingServers.length < concurrency`, pick from `untriedServers` (removing on pick). On FNEW success, add to `workingServers`. On FNEW failure, router is already removed from `untriedServers`; remove from `workingServers` if present. When `untriedServers` is empty, reset it to all non-working routers. Once `workingServers.length >= concurrency`, pick randomly only from `workingServers`.
+
+**Termination condition:** Each data packet tries at most `min(routerCount, 5)` different routers. If all attempts fail, the data packet fails and the upload fails with the last error. Rationale: if 5 out of 12 routers are down, something systemic is wrong and continuing is unlikely to help. Timeouts count as failures — the timed-out router is removed from working and a different router is picked next.
+
+**Key differences from Haskell:**
+- No operator concept — just host diversity via random selection
+- No database — state tracked in-memory during upload
+- FNEW runs concurrently (Haskell is serial) — improves startup time
+- FNEW is cheap and retried with router rotation; FPUT retries on same router
+
+**Download changes (also Phase 2):** Default concurrency should be 4 (matching Haskell). Download already groups by router in 3.5. If `replicas[0]` download fails, try `replicas[1]`, `replicas[2]`, etc. (fallback across replicas).
+
+## 4. Implementation Plan
+
+### Phase 1: Error handling and connection resilience
+
+Steps are ordered by dependency and should be implemented one by one.
+
+#### Step 1: Fix cache key (3.6)
+- Change cache key to `formatXFTPServer(server)` in `getXFTPServerClient` and `closeXFTPServerClient`
+- Add import for `formatXFTPServer`
+- Run existing tests to verify no regression
+
+#### Step 2: Typed error detection for padded router errors (3.2 client-side)
+- Add `XFTPRetriableError` class
+- In `sendXFTPCommand`, detect padded error strings before `decodeTransmission`
+- Classify `FRErr` responses as retriable or permanent with human-readable messages
+- Run existing tests
+
+#### Step 3: Fetch timeout (3.3)
+- Add `TransportConfig` with `timeoutMs`
+- Thread config through `createTransport` → `connectXFTP` → command wrappers
+- Add `AbortController` to browser `fetch()` and `setTimeout` to Node.js HTTP/2
+- Add vitest test: timeout triggers after configured duration
+- Run existing tests
+
+#### Step 4: Connection state with Promise-based lock and per-router queues (3.5)
+- Introduce `ServerConnection` record: `{client: Promise<XFTPClient>, queue: Promise<void>}`
+- Replace `XFTPClientAgent.clients: Map<string, XFTPClient>` with `connections: Map<string, ServerConnection>`
+- Implement `reconnectClient` — replaces `conn.client` with new promise, preserves queue
+- Implement `enqueueCommand` — chains operation onto router's queue
+- Implement `removeStaleConnection` — removes entry only if current promise is the failed one
+- Auto-cleanup: `p.catch(() => delete)` removes failed connections so next caller starts fresh
+- Adapt `closeXFTPServerClient` and `closeXFTPAgent`
+- Add vitest tests:
+  - Concurrent calls to same router produce single connection
+  - Failed promise is cleaned up, next caller gets fresh connection
+
+#### Step 5: Automatic retry in sendXFTPCommand (3.2)
+- Add retry loop with reconnect
+- Change `sendXFTPCommand` signature: takes `agent + server` instead of `client`; export it (needed by tests and by agent.ts callers)
+- Rename current `sendXFTPCommand` → `sendXFTPCommandOnce` (private); add padded error detection + FRErr classification (throw `XFTPRetriableError` for SESSION/HANDSHAKE, `XFTPPermanentError` for AUTH/NO_FILE/etc.)
+- All command wrappers (`createXFTPChunk`, `uploadXFTPChunk`, etc.) pass agent + server
+- Update agent.ts call sites: remove `getXFTPServerClient` calls before command wrappers (in `uploadFile`, `uploadRedirectDescription`, `downloadFileRaw`, `resolveRedirect`, `deleteFile`)
+- Max 3 retries for retriable errors, immediate throw for permanent
+- On retriable error: call `reconnectClient` and retry. On retriable error exhausted: call `removeStaleConnection` to clean up. On permanent error: throw immediately without touching connection
+- Add vitest tests:
+  - Router started with delay → first attempt fails, retry succeeds
+  - 3 retries exhausted → error propagates with human-readable message
+  - Non-retriable error (AUTH) → no retry, immediate failure
+
+#### Step 6: Router-side stale session handling (3.1)
+- Add one guard to `Nothing` branch: `sniUsed && not webHello -> throwE SESSION`
+- Remove debug `hPutStrLn stderr` lines (all 6 occurrences in dispatch)
+- All other branches unchanged
+- Run Haskell tests + Playwright tests
+
+#### Step 7: Download with per-router grouping
+- Modify `downloadFileRaw` to group data packets by router, sequential within each router (`for` loop), parallel across routers (`Promise.all`)
+- Add vitest test: concurrent downloads from different routers run in parallel
+
+#### Step 8: UI error improvements (3.4)
+- Temporary errors: auto-retry loop (3 attempts), then show human-readable diagnosis + manual retry button
+- Permanent errors: show human-readable error, NO retry button
+- Manual retry resumes from last successful data packet (not full restart)
+
+#### Step 9: Remove debug logging
+- Remove all `console.log('[DEBUG ...]')` and `hPutStrLn stderr "DEBUG ..."` lines
+- Keep `console.error('[XFTP] ...')` error logging
+
+### Phase 2: Multi-router upload
+
+Implement after Phase 1 is complete and tested.
+
+#### Step 10: Multi-router upload with failover (3.7)
+- Extend `SentChunk` with `chunkOffset: number` (from ChunkSpec) and `server: XFTPServer` (assigned during allocate) — Stage 2 reads data by offset and groups data packets by router
+- Change `uploadFile` signature: takes `allServers: XFTPServer[]` instead of single `server`
+- Implement `UploadState` with `untriedServers` and `workingServers`
+- Implement `createChunkWithFailover` and `pickServer`: two-list selection (untried → working once enough found), max `min(routerCount, 5)` attempts per data packet
+- Allocate stage: concurrent FNEW within concurrency limit (default 4)
+- Upload stage: parallel across routers, sequential per router (reuse queue from Step 7)
+- Update `web/upload.ts`: pass `getServers()` instead of `pickRandomServer(getServers())`
+- Update description building: each data packet references its actual router
+- Add vitest tests:
+  - File split across N routers (verify different routers in description)
+  - One router down → data packets redistributed to others
+  - All routers down → error after exhausting 5 attempts per data packet
+
+#### Step 11: Download concurrency and replica fallback
+- Change default download concurrency from 1 to 4
+- If `replicas[0]` download fails, try `replicas[1]`, `replicas[2]`, etc.
+- Uses per-router queues from Step 7
+
+## 5. Testing Plan
+
+### Principle
+
+Prefer low-level vitest tests over Playwright E2E. Each new function gets one focused test. Pure functions tested without mocks; connection management tested with mock `connectXFTP`; router behavior tested with real router. Total: 13 tests across 4 files.
+
+Tests A-C run in browser context (`@vitest/browser` with Chromium headless), configured in `vitest.config.ts`. Test D (integration) requires a separate Node.js vitest config since it uses `node:http2`. Existing `globalSetup.ts` provides a real XFTP router for integration tests.
+
+### Test file A: `test/errors.test.ts` — pure, no router
+
+Tests error classification and padded error detection (Steps 2, 5).
+
+**T1. `isRetriable` classifies errors correctly**
+```typescript
+// Retriable:
+expect(isRetriable(new XFTPRetriableError("SESSION"))).toBe(true)
+expect(isRetriable(new XFTPRetriableError("HANDSHAKE"))).toBe(true)
+expect(isRetriable(new TypeError("fetch failed"))).toBe(true)          // network error
+expect(isRetriable(Object.assign(new Error(), {name: "AbortError"}))).toBe(true)  // timeout
+// Not retriable:
+expect(isRetriable(new XFTPPermanentError("AUTH", "..."))).toBe(false)
+expect(isRetriable(new XFTPPermanentError("NO_FILE", "..."))).toBe(false)
+expect(isRetriable(new XFTPPermanentError("INTERNAL", "..."))).toBe(false)
+```
+
+**T2. `categorizeError` produces human-readable messages**
+```typescript
+// categorizeError receives thrown errors (from sendXFTPCommandOnce or transport)
+const e = categorizeError(new XFTPPermanentError("AUTH", "File is invalid, expired, or has been removed"))
+expect(e.message).toContain("expired")
+// Verify every permanent error type maps to a non-empty human-readable message
+for (const errType of ["AUTH", "NO_FILE", "SIZE", "QUOTA", "BLOCKED", "DIGEST", "INTERNAL"]) {
+  expect(humanReadableMessage({type: errType}).length).toBeGreaterThan(0)
+}
+// Retriable errors also get human-readable messages after exhaustion
+const re = categorizeError(new XFTPRetriableError("SESSION"))
+expect(re.message).toContain("expired")  // "Session expired, reconnecting..."
+```
+
+**T3. Padded error detection extracts error string from padded block**
+```typescript
+import {blockPad, blockUnpad} from '../src/protocol/transmission.js'
+// Simulate router sending padded "SESSION"
+const padded = blockPad(new TextEncoder().encode("SESSION"))
+const raw = blockUnpad(padded)
+expect(raw.length).toBeLessThan(20)
+expect(new TextDecoder().decode(raw)).toBe("SESSION")
+// Normal transmission block (batch count + large-encoded data) is NOT a short string
+const sessionId = new Uint8Array(32)  // dummy
+const normalBlock = encodeTransmission(sessionId, new Uint8Array(0), new Uint8Array(0), encodePING())
+const normalRaw = blockUnpad(normalBlock)
+expect(normalRaw.length).toBeGreaterThan(20)  // not mistaken for padded error
+```
+
+### Test file B: `test/connection.test.ts` — mock connectXFTP, no router
+
+Tests connection management functions (Steps 4, 5). Uses `vi.mock` to replace `connectXFTP` with a controllable promise factory.
+
+**T4. `getXFTPServerClient` coalesces concurrent calls**
+```typescript
+// Mock connectXFTP to return a deferred promise
+const {promise, resolve} = promiseWithResolvers<XFTPClient>()
+vi.mocked(connectXFTP).mockReturnValueOnce(promise)
+const agent = newXFTPAgent()
+const p1 = getXFTPServerClient(agent, server)
+const p2 = getXFTPServerClient(agent, server)
+expect(p1).toBe(p2)  // same promise, single connection
+resolve(mockClient)
+expect(await p1).toBe(mockClient)
+```
+
+**T5. `getXFTPServerClient` auto-cleans failed connections**
+```typescript
+vi.mocked(connectXFTP).mockReturnValueOnce(Promise.reject(new Error("down")))
+const agent = newXFTPAgent()
+const p1 = getXFTPServerClient(agent, server)
+await expect(p1).rejects.toThrow("down")
+// After microtask, entry is removed
+await new Promise(r => setTimeout(r, 0))
+expect(agent.connections.has(formatXFTPServer(server))).toBe(false)
+// Next call creates fresh connection
+vi.mocked(connectXFTP).mockReturnValueOnce(Promise.resolve(mockClient))
+const p2 = getXFTPServerClient(agent, server)
+expect(p2).not.toBe(p1)
+```
+
+**T6. `removeStaleConnection` respects promise identity**
+```typescript
+const agent = newXFTPAgent()
+const p1 = Promise.resolve(mockClient)
+agent.connections.set(key, {client: p1, queue: Promise.resolve()})
+// Replace with reconnect
+const p2 = Promise.resolve(mockClient2)
+agent.connections.set(key, {client: p2, queue: Promise.resolve()})
+// removeStaleConnection with old promise does NOT remove new entry
+removeStaleConnection(agent, server, p1)
+expect(agent.connections.has(key)).toBe(true)
+expect(agent.connections.get(key)!.client).toBe(p2)
+// removeStaleConnection with current promise removes it
+removeStaleConnection(agent, server, p2)
+expect(agent.connections.has(key)).toBe(false)
+```
+
+**T7. `reconnectClient` replaces promise but preserves queue**
+```typescript
+const agent = newXFTPAgent()
+const origQueue = Promise.resolve()
+agent.connections.set(key, {client: Promise.resolve(mockClient), queue: origQueue})
+vi.mocked(connectXFTP).mockReturnValueOnce(Promise.resolve(mockClient2))
+reconnectClient(agent, server)
+const conn = agent.connections.get(key)!
+expect(await conn.client).toBe(mockClient2)  // new client
+expect(conn.queue).toBe(origQueue)            // queue preserved
+```
+
+**T8. Retry loop: retriable error triggers reconnect, permanent error does not**
+
+Mock approach: `vi.mock('../src/client.js')` to mock `connectXFTP` (exported). `reconnectClient` is not exported — its behavior is controlled indirectly via `connectXFTP` mock (it calls `connectXFTP` internally). Verify retry count via `connectXFTP` call count. Note: vitest module mocking may need adjustment depending on ESM transform behavior — if intra-module calls bypass the mock, extract `connectXFTP` to a separate module or use dependency injection for testing.
+
+```typescript
+// Script: first connectXFTP returns client whose post throws retriable,
+// second connectXFTP (from reconnect) returns client whose post succeeds
+vi.mocked(connectXFTP)
+  .mockResolvedValueOnce({
+    ...mockClient,
+    transport: { post: async () => { throw new XFTPRetriableError("SESSION") }, close: () => {} }
+  })
+  .mockResolvedValueOnce({
+    ...mockClient,
+    transport: { post: async () => okResponseBlock, close: () => {} }
+  })
+
+const agent = newXFTPAgent()
+const result = await sendXFTPCommand(agent, server, dummyKey, dummyId, encodePING())
+expect(result.response.type).toBe("FROk")
+expect(vi.mocked(connectXFTP)).toHaveBeenCalledTimes(2)  // initial + 1 reconnect
+
+// Reset — all 3 retries exhausted: connectXFTP called 3 times (initial + 2 reconnects)
+vi.mocked(connectXFTP).mockClear()
+vi.mocked(connectXFTP).mockResolvedValue({
+  ...mockClient,
+  transport: { post: async () => { throw new XFTPRetriableError("SESSION") }, close: () => {} }
+})
+const agent2 = newXFTPAgent()
+await expect(sendXFTPCommand(agent2, server, dummyKey, dummyId, encodePING()))
+  .rejects.toThrow(/reconnecting|expired/)
+expect(vi.mocked(connectXFTP)).toHaveBeenCalledTimes(3)  // initial + 2 reconnects
+
+// Reset — permanent error: connectXFTP called once (initial only, no reconnect)
+vi.mocked(connectXFTP).mockClear()
+vi.mocked(connectXFTP).mockResolvedValue({
+  ...mockClient,
+  transport: { post: async () => authErrorBlock, close: () => {} }
+})
+const agent3 = newXFTPAgent()
+await expect(sendXFTPCommand(agent3, server, dummyKey, dummyId, encodePING()))
+  .rejects.toThrow(/expired/)
+expect(vi.mocked(connectXFTP)).toHaveBeenCalledTimes(1)  // initial only, no reconnect
+```
+
+### Test file C: `test/server-selection.test.ts` — pure, no router
+
+Tests `pickServer` state machine (Step 10). Determinism: seed `Math.random` or test invariants not specific picks.
+
+**T9. `pickServer` picks from untried when working < concurrency**
+```typescript
+const servers = [s1, s2, s3, s4, s5]
+const state: UploadState = {untriedServers: [...servers], workingServers: []}
+const picked = pickServer(servers, state, 4)
+// picked is from untried, and was removed from untried
+expect(state.untriedServers.length).toBe(4)
+expect(state.untriedServers).not.toContainEqual(picked)
+```
+
+**T10. `pickServer` picks only from working when working >= concurrency**
+```typescript
+const state: UploadState = {
+  untriedServers: [s5],  // still has untried
+  workingServers: [s1, s2, s3, s4]
+}
+const picked = pickServer(servers, state, 4)
+// Must pick from working, NOT from untried
+expect([s1, s2, s3, s4]).toContainEqual(picked)
+expect(state.untriedServers.length).toBe(1)  // untried unchanged
+```
+
+**T11. `pickServer` resets untried when exhausted**
+```typescript
+const state: UploadState = {
+  untriedServers: [],        // all tried
+  workingServers: [s1, s2]   // only 2 working, concurrency=4
+}
+const picked = pickServer(servers, state, 4)
+// Should have reset untried to non-working routers and picked from them
+expect([s3, s4, s5]).toContainEqual(picked)
+expect(state.untriedServers.length).toBe(2)  // 3 non-working minus 1 picked
+```
+
+### Test file D: `test/integration.test.ts` — real router, Node.js mode
+
+Requires separate vitest config with `browser: {enabled: false}` since these tests use `node:http2` directly. Alternatively, add `test/vitest.node.config.ts` that includes only `test/integration.test.ts` and runs in Node.js.
+
+**T12. Stale session returns padded SESSION error (requires Step 6)**
+```typescript
+import http2 from 'node:http2'
+// Connect and handshake normally via the client
+const client = await connectXFTP(server)
+// Create a raw HTTP/2 session (new TLS SessionId, no handshake state on router)
+const session = http2.connect(client.baseUrl, {rejectUnauthorized: false})
+// Build a dummy command block using the old client's sessionId.
+// Content doesn't matter — router detects stale session before parsing command.
+const dummyKey = new Uint8Array(64)  // Ed25519 private key (dummy)
+const dummyId = new Uint8Array(24)   // entity ID (dummy)
+const cmdBlock = encodeAuthTransmission(client.sessionId, new Uint8Array(0), dummyId, encodePING(), dummyKey)
+const resp = await new Promise<Uint8Array>((resolve, reject) => {
+  const req = session.request({":method": "POST", ":path": "/"})
+  const chunks: Buffer[] = []
+  req.on("data", (c: Buffer) => chunks.push(c))
+  req.on("end", () => resolve(new Uint8Array(Buffer.concat(chunks))))
+  req.on("error", reject)
+  req.end(Buffer.from(cmdBlock))
+})
+// Router should return padded "SESSION" (not crash, not "HANDSHAKE")
+const raw = blockUnpad(resp.subarray(0, XFTP_BLOCK_SIZE))
+expect(new TextDecoder().decode(raw)).toBe("SESSION")
+session.close()
+closeXFTP(client)
+```
+
+**T13. Fetch timeout fires within configured duration**
+```typescript
+// connectXFTP with 1ms timeout — handshake requires multiple round trips,
+// so even on localhost it will exceed 1ms and trigger abort
+await expect(
+  connectXFTP(server, {timeoutMs: 1})
+).rejects.toThrow(/abort|timeout/i)
+```
+
+### What existing tests already cover (no new tests needed)
+
+| Behavior | Covered by |
+|----------|-----------|
+| Cache key fix (Step 1) | Existing round-trip test — uses `formatXFTPServer` after refactor |
+| Basic upload/download | 24 Playwright tests + 1 vitest browser test |
+| File size limits, unicode filenames | Playwright edge case tests |
+| Router startup/teardown | `globalSetup.ts` / `globalTeardown.ts` |
+| Handshake + identity verification | `connectXFTP` in existing round-trip test |
+
+### Test ordering
+
+Tests must be added alongside their implementation step:
+- **Step 2**: Add T1, T2, T3 (test/errors.test.ts)
+- **Step 3**: Add T13 (test/integration.test.ts) — requires Node.js vitest config
+- **Step 4**: Add T4, T5, T6, T7 (test/connection.test.ts)
+- **Step 5**: Add T8 (test/connection.test.ts)
+- **Step 6**: Add T12 (test/integration.test.ts) — requires router change + Node.js vitest config
+- **Step 10**: Add T9, T10, T11 (test/server-selection.test.ts)
+
+## 6. Context for Implementation Sessions
+
+### Files to re-read on session start
+
+**TypeScript (xftp-web/src/):**
+- `client.ts` — `XFTPClient`, `XFTPClientAgent`, `getXFTPServerClient`, `closeXFTPServerClient`, `connectXFTP`, `sendXFTPCommand`, `createBrowserTransport`, `createNodeTransport`, all command wrappers
+- `agent.ts` — `uploadFile`, `downloadFileRaw`, `downloadFile`, `resolveRedirect`, `encryptFileForUpload`
+- `protocol/transmission.ts` — `encodeAuthTransmission`, `decodeTransmission`, `blockPad`, `blockUnpad`
+- `protocol/commands.ts` — `XFTPErrorType`, `FileResponse`, `decodeResponse`, `decodeXFTPError`
+- `protocol/handshake.ts` — `decodeServerHandshake` (padded error detection heuristic)
+- `protocol/address.ts` — `XFTPServer`, `parseXFTPServer`, `formatXFTPServer`
+- `web/upload.ts` — UI error handling, retry button
+- `web/download.ts` — UI error handling, retry button
+- `web/servers.ts` — `getServers`, `pickRandomServer`
+
+**TypeScript (xftp-web/test/):**
+- `browser.test.ts` — vitest Node.js test template (uses real Haskell router)
+- `globalSetup.ts` — router startup, config generation, port file
+- `page.spec.ts` — Playwright page tests
+
+**Haskell (reference for multi-router):**
+- `src/Simplex/FileTransfer/Agent.hs` — `createChunk` (lines 457-486, allocate stage), `runXFTPSndPrepareWorker` (lines 391-430, serial allocate in Haskell), `runXFTPSndWorker` (lines 494-548, per-router upload worker)
+- `src/Simplex/Messaging/Agent/Client.hs` — `getNextServer_` (lines 2335-2350), `withNextSrv` (lines 2366-2385), `pickServer` (lines 2309-2314)
+
+**Haskell (router):**
+- `src/Simplex/FileTransfer/Server.hs` — `xftpServerHandshakeV1` (lines 165-244), `processRequest` (lines 403-435)
+- `src/Simplex/Messaging/Protocol.hs` — `tDecodeServer` (lines 2239-2265) — sessionId verification at line 2242
+
+### Key design constraints
+
+1. `tDecodeServer` (Protocol.hs:2242) verifies `sessId == sessionId` — commands signed with old sessionId WILL fail on new connection
+2. Router generates per-session DH key in `processHello` (Server.hs:207) — cannot be shared across sessions
+3. `fetch()` provides zero control over HTTP/2 connection reuse — browser decides
+4. `xftp-web-hello` header is only checked in dispatch (Server.hs:192), NOT inside `processHello`
+5. Handshake-phase errors are raw padded strings; command-phase errors are proper ERR transmissions
+6. Ed25519 signature verification (`TASignature` path, Protocol.hs:1314) does NOT use `thAuth` — but SMP will
+7. Reconnect must re-handshake to get new sessionId AND new router DH key
+8. The new `throwE SESSION` guard (Step 6) sends a raw padded "SESSION" string — no sessionId framing. Client detects this via padded error heuristic (section 3.2), not via sessionId mismatch
+9. FNEW is cheap (creates data packet record on router) — retry with different router on failure
+10. FPUT retries on same router (data packet replica already exists there) — close connection + backoff
+
+## 7. Plan Maintenance
+
+This plan must be updated as implementation proceeds:
+- Mark completed steps with date
+- Record any deviations from the plan with rationale
+- Add new issues discovered during implementation
+- Update file references if code moves