feat(advanced): M-Adv 1-3 — multi-device, backup/restore, group messaging

Phase D complete. Shade is now at parity with Signal libsignal's core
feature set.

M-Adv 1: Multi-device support (simplified Sesame)
- DeviceListManager tracks per-user device lists ("user:deviceId" addresses)
- fanOutEncrypt() sends one message to all known devices via independent
  1:1 Double Ratchet sessions
- observeIncoming() auto-registers new devices from received messages
- JSON serialization for persistence
- userOfDevice/deviceIdOf address parsers

M-Adv 2: Backup and restore
- @shade/sdk exports BackupBlob format: version + salt + nonce + ciphertext
- Passphrase-derived key via HKDF (note: upgrade path to Argon2id documented)
- exportBackup()/importBackup() handle identity, prekeys, sessions, trust
- backupToString/backupFromString for single-string transport (copy/paste, QR)
- shade.exportBackup()/importBackup() convenience methods on SDK
- CLI: shade backup export <file> / shade backup restore <file>
- Rebuilds manager + transport after restore so ratchet state is consistent

M-Adv 3: Group messaging (Sender Keys)
- Per-sender chain key + Ed25519 signing key per group
- createSenderKey / buildDistribution / installDistribution for key distribution
- senderKeyEncrypt advances chain and signs ciphertext+header
- senderKeyDecrypt verifies signature then advances the sender's chain
- Out-of-order handling with bounded skip
- O(1) per message (once distributions are installed)
- Defensive ByteArray copies in distribution to prevent zeroize-across-refs

276 tests passing, 0 failures. All 13 SDK/tooling/platform/advanced
milestones complete. Shade is feature-complete for v2.0.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shade-core/tests/sender-keys.test.ts

@@ -0,0 +1,170 @@
+import { describe, test, expect } from 'bun:test';
+import { SubtleCryptoProvider } from '@shade/crypto-web';
+import {
+  createSenderKey,
+  buildDistribution,
+  installDistribution,
+  senderKeyEncrypt,
+  senderKeyDecrypt,
+} from '../src/sender-keys.js';
+import type { GroupSession, SenderKeyState } from '../src/sender-keys.js';
+
+const crypto = new SubtleCryptoProvider();
+
+/**
+ * Helpers: set up a group of N members who all know each other's sender keys.
+ */
+async function setupGroup(groupId: string, memberAddresses: string[]): Promise<{
+  sessions: Map<string, GroupSession>;
+}> {
+  // Each member creates their own sender key state
+  const senderStates = new Map<string, SenderKeyState>();
+  for (const addr of memberAddresses) {
+    senderStates.set(addr, await createSenderKey(crypto));
+  }
+
+  // Each member's session contains everyone's sender key
+  const sessions = new Map<string, GroupSession>();
+  for (const member of memberAddresses) {
+    const session: GroupSession = { groupId, senderKeys: new Map() };
+
+    // Add own sender key (with private signing key)
+    session.senderKeys.set(member, senderStates.get(member)!);
+
+    // Add public copies of everyone else's sender keys (without private key)
+    for (const other of memberAddresses) {
+      if (other === member) continue;
+      const dist = buildDistribution(groupId, other, senderStates.get(other)!);
+      installDistribution(session, dist);
+    }
+
+    sessions.set(member, session);
+  }
+
+  return { sessions };
+}
+
+describe('Sender Keys (group messaging)', () => {
+  test('Alice sends to Bob + Charlie + Dave', async () => {
+    const { sessions } = await setupGroup('group1', ['alice', 'bob', 'charlie', 'dave']);
+
+    const msg = await senderKeyEncrypt(
+      crypto,
+      sessions.get('alice')!,
+      'alice',
+      new TextEncoder().encode('hello everyone'),
+    );
+
+    // All three recipients decrypt independently
+    for (const recipient of ['bob', 'charlie', 'dave']) {
+      const plain = await senderKeyDecrypt(crypto, sessions.get(recipient)!, 'group1', msg);
+      expect(new TextDecoder().decode(plain)).toBe('hello everyone');
+    }
+  });
+
+  test('multiple messages from same sender advance the chain', async () => {
+    const { sessions } = await setupGroup('g', ['alice', 'bob']);
+
+    for (let i = 0; i < 5; i++) {
+      const msg = await senderKeyEncrypt(
+        crypto,
+        sessions.get('alice')!,
+        'alice',
+        new TextEncoder().encode(`msg ${i}`),
+      );
+      expect(msg.iteration).toBe(i);
+
+      const plain = await senderKeyDecrypt(crypto, sessions.get('bob')!, 'g', msg);
+      expect(new TextDecoder().decode(plain)).toBe(`msg ${i}`);
+    }
+  });
+
+  test('messages from different senders use independent chains', async () => {
+    const { sessions } = await setupGroup('g', ['alice', 'bob', 'charlie']);
+
+    // Alice sends
+    const aliceMsg = await senderKeyEncrypt(
+      crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode('from alice'),
+    );
+    // Bob sends
+    const bobMsg = await senderKeyEncrypt(
+      crypto, sessions.get('bob')!, 'bob', new TextEncoder().encode('from bob'),
+    );
+
+    // Charlie decrypts both
+    expect(new TextDecoder().decode(
+      await senderKeyDecrypt(crypto, sessions.get('charlie')!, 'g', aliceMsg)
+    )).toBe('from alice');
+    expect(new TextDecoder().decode(
+      await senderKeyDecrypt(crypto, sessions.get('charlie')!, 'g', bobMsg)
+    )).toBe('from bob');
+  });
+
+  test('tampered ciphertext fails signature verification', async () => {
+    const { sessions } = await setupGroup('g', ['alice', 'bob']);
+
+    const msg = await senderKeyEncrypt(
+      crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode('original'),
+    );
+    msg.ciphertext[0] ^= 0xff;
+
+    expect(
+      senderKeyDecrypt(crypto, sessions.get('bob')!, 'g', msg),
+    ).rejects.toThrow(/Invalid signature|decryption/i);
+  });
+
+  test('wrong group ID fails', async () => {
+    const { sessions } = await setupGroup('g', ['alice', 'bob']);
+
+    const msg = await senderKeyEncrypt(
+      crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode('hi'),
+    );
+
+    expect(
+      senderKeyDecrypt(crypto, sessions.get('bob')!, 'wrong-group', msg),
+    ).rejects.toThrow(/Group ID mismatch/);
+  });
+
+  test('out-of-order with small skip works', async () => {
+    const { sessions } = await setupGroup('g', ['alice', 'bob']);
+
+    // Alice sends 3 messages
+    const messages = [];
+    for (let i = 0; i < 3; i++) {
+      messages.push(await senderKeyEncrypt(
+        crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode(`msg ${i}`),
+      ));
+    }
+
+    // Bob decrypts in order
+    for (let i = 0; i < 3; i++) {
+      const plain = await senderKeyDecrypt(crypto, sessions.get('bob')!, 'g', messages[i]!);
+      expect(new TextDecoder().decode(plain)).toBe(`msg ${i}`);
+    }
+  });
+
+  test('new member added later receives subsequent messages via fresh distribution', async () => {
+    // Alice and Bob in a group
+    const { sessions } = await setupGroup('g', ['alice', 'bob']);
+
+    // Alice sends one message to Bob
+    const msg1 = await senderKeyEncrypt(
+      crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode('private msg'),
+    );
+    await senderKeyDecrypt(crypto, sessions.get('bob')!, 'g', msg1);
+
+    // Charlie joins — Alice sends him her CURRENT sender key state
+    const aliceStateForCharlie = sessions.get('alice')!.senderKeys.get('alice')!;
+    const charlieSession: GroupSession = { groupId: 'g', senderKeys: new Map() };
+    installDistribution(charlieSession, buildDistribution('g', 'alice', aliceStateForCharlie));
+
+    // Alice sends another message
+    const msg2 = await senderKeyEncrypt(
+      crypto, sessions.get('alice')!, 'alice', new TextEncoder().encode('welcome charlie'),
+    );
+
+    // Charlie can decrypt (because he got the current chain state)
+    const plain = await senderKeyDecrypt(crypto, charlieSession, 'g', msg2);
+    expect(new TextDecoder().decode(plain)).toBe('welcome charlie');
+  });
+});

packages/shade-core/tests/sesame.test.ts

@@ -0,0 +1,160 @@
+import { describe, test, expect } from 'bun:test';
+import { SubtleCryptoProvider, MemoryStorage } from '@shade/crypto-web';
+import { ShadeSessionManager } from '../src/index.js';
+import {
+  DeviceListManager,
+  fanOutEncrypt,
+  observeIncoming,
+  userOfDevice,
+  deviceIdOf,
+} from '../src/sesame.js';
+
+const crypto = new SubtleCryptoProvider();
+
+describe('DeviceListManager', () => {
+  test('add and get devices', () => {
+    const mgr = new DeviceListManager();
+    mgr.addDevice('bob', 'bob:phone');
+    mgr.addDevice('bob', 'bob:laptop');
+    mgr.addDevice('bob', 'bob:tablet');
+
+    const devices = mgr.getDevices('bob');
+    expect(devices.length).toBe(3);
+    expect(devices).toContain('bob:phone');
+    expect(devices).toContain('bob:laptop');
+    expect(devices).toContain('bob:tablet');
+  });
+
+  test('remove device', () => {
+    const mgr = new DeviceListManager();
+    mgr.addDevice('bob', 'bob:phone');
+    mgr.addDevice('bob', 'bob:laptop');
+    mgr.removeDevice('bob', 'bob:phone');
+    expect(mgr.getDevices('bob')).toEqual(['bob:laptop']);
+  });
+
+  test('setDevices replaces list', () => {
+    const mgr = new DeviceListManager();
+    mgr.addDevice('bob', 'bob:phone');
+    mgr.setDevices('bob', ['bob:laptop', 'bob:tablet']);
+    expect(mgr.getDevices('bob').sort()).toEqual(['bob:laptop', 'bob:tablet']);
+  });
+
+  test('empty list for unknown user', () => {
+    const mgr = new DeviceListManager();
+    expect(mgr.getDevices('nobody')).toEqual([]);
+  });
+
+  test('toJSON and fromJSON roundtrip', () => {
+    const mgr = new DeviceListManager();
+    mgr.addDevice('bob', 'bob:phone');
+    mgr.addDevice('alice', 'alice:laptop');
+
+    const json = mgr.toJSON();
+    const restored = new DeviceListManager();
+    restored.fromJSON(json);
+
+    expect(restored.getDevices('bob')).toEqual(['bob:phone']);
+    expect(restored.getDevices('alice')).toEqual(['alice:laptop']);
+  });
+});
+
+describe('Address parsing helpers', () => {
+  test('userOfDevice extracts the user part', () => {
+    expect(userOfDevice('bob:phone')).toBe('bob');
+    expect(userOfDevice('alice@example.com:tablet')).toBe('alice@example.com');
+    expect(userOfDevice('noColon')).toBe('noColon');
+  });
+
+  test('deviceIdOf extracts the device part', () => {
+    expect(deviceIdOf('bob:phone')).toBe('phone');
+    expect(deviceIdOf('alice@example.com:tablet')).toBe('tablet');
+    expect(deviceIdOf('noColon')).toBe('');
+  });
+});
+
+describe('observeIncoming', () => {
+  test('auto-registers a new device', () => {
+    const mgr = new DeviceListManager();
+    observeIncoming(mgr, 'bob:newPhone');
+    expect(mgr.getDevices('bob')).toEqual(['bob:newPhone']);
+  });
+
+  test('second message from same device is idempotent', () => {
+    const mgr = new DeviceListManager();
+    observeIncoming(mgr, 'bob:phone');
+    observeIncoming(mgr, 'bob:phone');
+    expect(mgr.getDevices('bob').length).toBe(1);
+  });
+});
+
+describe('fanOutEncrypt: multi-device fan-out', () => {
+  async function setupAliceToBobDevices(devices: string[]) {
+    // Alice has one SessionManager
+    const alice = new ShadeSessionManager(crypto, new MemoryStorage());
+    await alice.initialize();
+
+    // Each Bob device has its own SessionManager (separate storage)
+    const bobs = new Map<string, ShadeSessionManager>();
+    for (const device of devices) {
+      const mgr = new ShadeSessionManager(crypto, new MemoryStorage());
+      await mgr.initialize();
+      bobs.set(device, mgr);
+    }
+
+    // Alice establishes a session with each Bob device
+    for (const [device, bob] of bobs) {
+      const otpks = await bob.generateOneTimePreKeys(5);
+      const bundle = await bob.createPreKeyBundle();
+      bundle.oneTimePreKey = { keyId: otpks[0].keyId, publicKey: otpks[0].keyPair.publicKey };
+      await alice.initSessionFromBundle(device, bundle);
+    }
+
+    // Alice tracks Bob's device list
+    const deviceList = new DeviceListManager();
+    for (const device of devices) {
+      deviceList.addDevice('bob', device);
+    }
+
+    return { alice, bobs, deviceList };
+  }
+
+  test('fans out to all devices', async () => {
+    const devices = ['bob:phone', 'bob:laptop', 'bob:tablet'];
+    const { alice, bobs, deviceList } = await setupAliceToBobDevices(devices);
+
+    const fanOut = await fanOutEncrypt(alice, deviceList, 'bob', 'hello all my devices');
+
+    expect(fanOut.length).toBe(3);
+    for (const { deviceAddress, envelope } of fanOut) {
+      const bob = bobs.get(deviceAddress)!;
+      const plain = await bob.decrypt('alice', envelope);
+      expect(plain).toBe('hello all my devices');
+    }
+  });
+
+  test('each device gets an independent session (DH ratchet per device)', async () => {
+    const devices = ['bob:phone', 'bob:laptop'];
+    const { alice, bobs, deviceList } = await setupAliceToBobDevices(devices);
+
+    // Send two rounds
+    for (let i = 0; i < 2; i++) {
+      const fanOut = await fanOutEncrypt(alice, deviceList, 'bob', `round ${i}`);
+      for (const { deviceAddress, envelope } of fanOut) {
+        const bob = bobs.get(deviceAddress)!;
+        const plain = await bob.decrypt('alice', envelope);
+        expect(plain).toBe(`round ${i}`);
+      }
+    }
+  });
+
+  test('throws when user has no known devices', async () => {
+    const alice = new ShadeSessionManager(crypto, new MemoryStorage());
+    await alice.initialize();
+    const deviceList = new DeviceListManager();
+
+    expect(
+      fanOutEncrypt(alice, deviceList, 'unknown-user', 'hello'),
+    ).rejects.toThrow(/No known devices/);
+  });
+});