Shade/MIGRATION.md

Migration Guide

This document describes how to migrate existing systems with ad-hoc encryption to Shade's Signal Protocol implementation.

Why migrate?

If you currently use:

• A static AES-256-GCM key per pair (e.g., ECDH at handshake, then never rotated)
• Pre-shared keys distributed at registration time
• Simple per-device symmetric encryption (like Nova's push notifications)

…then you're missing forward secrecy and post-compromise recovery. Shade gives you both with minimal code changes.

Migration phases

The recommended migration is a three-phase rollout that lets you ship without downtime:

Phase 1: Dual-write

• Set up the Shade prekey server alongside your existing system
• New devices register with both systems
• Old devices continue using the legacy encryption
• Both encrypted formats are accepted on read

Phase 2: Switch reads

• Once the majority of devices are on Shade, prefer Shade for new sessions
• Continue accepting legacy messages for older clients
• Monitor decryption failure rates

Phase 3: Deprecate

• Remove legacy encryption code
• Force all devices to re-pair via Shade
• Clean up legacy database columns

Concrete examples

Example A: Replacing a static AES tunnel

Before (crypto/e2ee.ts):

import { generateKeyPair, deriveSharedSecret, encrypt, decrypt } from './crypto/e2ee.js';

// During pairing
const myKp = await generateKeyPair();
const sharedSecret = await deriveSharedSecret(myKp.privateKey, peerPublicKey);
db.serverConnection.insert({ sharedSecret: exportSecret(sharedSecret) });

// On every message
const { ciphertext, nonce } = await encrypt(sharedSecret, plaintext);
ws.send({ ciphertext, nonce });

After (with Shade):

import { ShadeSessionManager } from '@shade/core';
import { SubtleCryptoProvider } from '@shade/crypto-web';
import { SQLiteStorage } from '@shade/storage-sqlite';
import { ShadeWebSocket, ShadeFetchTransport } from '@shade/transport';

const crypto = new SubtleCryptoProvider();
const storage = new SQLiteStorage('/data/shade.db');
const manager = new ShadeSessionManager(crypto, storage);
await manager.initialize();

// During pairing — fetch peer's bundle and start session
const transport = new ShadeFetchTransport({
  baseUrl: 'https://prekey.example.com',
  crypto,
  signingPrivateKey: (await storage.getIdentityKeyPair())!.signingPrivateKey,
});
const peerBundle = await transport.fetchBundle('peer-id');
await manager.initSessionFromBundle('peer-id', peerBundle);

// On every message — wrap the WebSocket
const shadeWs = new ShadeWebSocket(rawWs, manager, 'peer-id');
shadeWs.onMessage((plaintext) => handleMessage(plaintext));
await shadeWs.send('Hello peer');

The key differences:

1. No static shared secret — keys ratchet forward with each message
2. Identity is persistent — same identity across reconnects, but session keys regenerate
3. The transport wrapper is transparent — your application code doesn't change

Example B: Replacing per-device push encryption

Before (per-device static AES key):

// Server side
const device = db.pushDevices.findFirst({ where: { id } });
const key = Buffer.from(device.encryptionKey, 'base64');
const encrypted = encryptPayload(notificationJson, key);
sendToFCM({ data: { enc: encrypted, v: '1' } });

After (Shade per-device session):

// Server side
const manager = new ShadeSessionManager(crypto, storage);
await manager.initialize();

// First time per device: fetch their bundle and establish session
if (!await storage.getSession(`device:${deviceId}`)) {
  const bundle = await prekeyTransport.fetchBundle(`device:${deviceId}`);
  await manager.initSessionFromBundle(`device:${deviceId}`, bundle);
}

const envelope = await manager.encrypt(`device:${deviceId}`, notificationJson);
sendToFCM({ data: { enc: encodeEnvelope(envelope), v: '2' } });

Client side:

// Decode the envelope, decrypt via Shade
val envelope = decodeEnvelope(data["enc"]!!)
val plaintext = shadeManager.decrypt("server", envelope)

Database migration

If your existing system stores symmetric keys in the database:

Before

CREATE TABLE devices (
  id TEXT PRIMARY KEY,
  encryption_key TEXT NOT NULL  -- base64 AES-256
);

After

CREATE TABLE devices (
  id TEXT PRIMARY KEY,
  shade_address TEXT NOT NULL  -- e.g. "device:abc123"
  -- Shade tables (created automatically by SQLiteStorage):
  -- shade_identity, shade_sessions, shade_signed_prekeys, etc.
);

The Shade tables are auto-created when you instantiate the storage backend. No manual migration needed.

Migration for Orchestrator

The Orchestrator project's orchestrator-shared/src/crypto/e2ee.ts provides a static ECDH-derived AES-256-GCM key for the workstation↔server sync tunnel. To migrate:

1. Add Shade dependencies to orchestrator-shared/package.json
2. Replace e2ee.ts with imports from @shade/core and @shade/transport
3. Update the pairing flow in sync-server.ts and sync-client.ts to exchange Shade prekey bundles instead of raw ECDH public keys
4. Wrap the sync WebSocket with ShadeWebSocket for transparent encryption
5. Migrate the serverConnection table to a shade_sessions table (or run dual-write during the rollout)

The key insight: Shade replaces the static sharedSecret column with a full ratcheting session, but the WebSocket transport, message types, and application logic don't change.

Migration for Nova (push notifications)

Nova's pushDevices.encryptionKey column is a per-device static AES key. To migrate:

1. Run a Shade prekey server (Docker container, see examples/05-dokploy-deployment)
2. On Android device registration, generate Shade identity + upload prekey bundle to the server (instead of generating a raw AES key)
3. In the Nova backend, fetch the device's bundle and establish a Shade session per device
4. Encrypt notifications via the Shade session instead of encryptPayload()
5. On the Android client, decrypt with Shade instead of the static key
6. Cross-platform interop: this requires the shade-android Kotlin module (not yet built — planned for the M8 milestone)

During the rollout, send notifications with a v: 1 (legacy) or v: 2 (Shade) field so old and new clients coexist.

Common pitfalls

1. Don't store private keys in shared databases without encryption at rest — Shade trusts the storage layer to be secure. Use filesystem encryption or PostgreSQL TDE if the database is on shared infrastructure.
2. Don't skip identity verification — Shade gives you fingerprints (getIdentityFingerprint()), but it's the user's responsibility to compare them out-of-band on first contact.
3. Don't reuse session storage between identities — each user/device should have its own Shade storage. Mixing identities in one storage will corrupt the ratchet state.
4. Keep prekey stocks topped up — call ensurePreKeyStock() periodically (e.g., on app start or every hour). When the server runs out of one-time prekeys, new sessions will fall back to using just the signed prekey, which is slightly less secure.