release(v4.0.0): Shade GA — V3.x consolidation + audit prep

V3.1 → V3.12 consolidated and tagged for the first GA release. Wire
format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers
byte-for-byte. The version bump is semantic: audit-cycle complete,
opt-in surface fully exposed, threat model refreshed for every new
surface.

Highlights:
- All 24 @shade/* packages bumped to 4.0.0 in lockstep.
- CHANGELOG 4.0.0 section is the canonical manifest of what landed.
- THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12
  Web-Worker boundary) + residual-risks table refreshed.
- OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox,
  bridge, observer, /metrics, /healthz, /ready.
- MIGRATION 0.3.x → 4.0 documented + smoke-tested against
  shade migrate-storage on a real SQLite DB.
- docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer.
- scripts/soak.ts harness for the GA-stable 2-week soak window.
- All V*.md plans archived under docs/archive/ with Status: Done.
- Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen
  non-realtime stack.

Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green.
Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports
  version 4.0.0 on /health.

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

packages/shade-core/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@shade/core",
-  "version": "0.3.0",
+  "version": "4.0.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "dependencies": {
+    "@shade/observability": "workspace:*"
+  },
   "peerDependencies": {
     "@shade/crypto-web": "workspace:*"
   },

packages/shade-core/src/errors.ts

@@ -88,6 +88,25 @@ export class IdentityRotationError extends ShadeError {
   }
 }
 
+/**
+ * Thrown when a fingerprint gate (V3.3) blocks an operation because the
+ * peer's safety number has not been verified, or the registered handler
+ * returned `false`.
+ */
+export class FingerprintNotVerifiedError extends ShadeError {
+  constructor(
+    public readonly peerAddress: string,
+    public readonly gate: 'first-large-file' | 'backup-import' | 'new-device-trust' | 'inbox-fanout',
+    message?: string,
+  ) {
+    super(
+      'SHADE_FINGERPRINT_NOT_VERIFIED',
+      message ?? `Fingerprint not verified for ${peerAddress} (gate: ${gate})`,
+    );
+    this.name = 'FingerprintNotVerifiedError';
+  }
+}
+
 // ─── Infrastructure Errors ───────────────────────────────────
 
 export class NetworkError extends ShadeError {
@@ -152,6 +171,7 @@ export function errorToHttpStatus(error: unknown): number {
     case 'SHADE_UNAUTHORIZED':
       return 401;
     case 'SHADE_UNTRUSTED_IDENTITY':
+    case 'SHADE_FINGERPRINT_NOT_VERIFIED':
       return 403;
     case 'SHADE_NO_SESSION':
     case 'SHADE_PREKEY_NOT_FOUND':

packages/shade-core/src/ratchet.ts

@@ -71,7 +71,11 @@ export async function initSenderSession(
  * Initialize a session as the receiver (Bob, after X3DH).
  *
  * Bob knows the root key and his own signed prekey (which was used as
- * the initial DH ratchet keypair).
+ * the initial DH ratchet keypair). The keypair is COPIED into the
+ * session — the receiving side's DH ratchet will eventually rotate
+ * `dhSend` and zeroize the previous private key, and that scratch
+ * buffer must NOT be the same memory as the persisted signed prekey
+ * (which is shared with future X3DH establishments from other senders).
  */
 export function initReceiverSession(
   rootKey: Uint8Array,
@@ -83,7 +87,10 @@ export function initReceiverSession(
     rootKey,
     sendChain: { chainKey: new Uint8Array(32), counter: 0 },
     receiveChain: null,
-    dhSend: localDHKeyPair,
+    dhSend: {
+      publicKey: new Uint8Array(localDHKeyPair.publicKey),
+      privateKey: new Uint8Array(localDHKeyPair.privateKey),
+    },
     dhReceive: null,
     previousSendCounter: 0,
     skippedKeys: new Map(),

packages/shade-core/src/session.ts

@@ -26,6 +26,16 @@ import {
 import { NoSessionError } from './errors.js';
 import { computeFingerprint, shortFingerprint } from './fingerprint.js';
 import { ShadeEventEmitter, shortHash } from './events.js';
+import {
+  ATTR_ERROR_CODE,
+  ATTR_OP,
+  ATTR_PEER_HASH,
+  ATTR_RESULT,
+  NOOP_HOOK,
+  peerHash,
+  type ObservabilityHook,
+  type Span,
+} from '@shade/observability';
 
 const enc = new TextEncoder();
 const dec = new TextDecoder();
@@ -60,6 +70,7 @@ export class ShadeSessionManager {
   private registrationId: number = 0;
   private currentSignedPreKeyId: number = 0;
   private readonly events?: ShadeEventEmitter;
+  private readonly observability: ObservabilityHook;
   /**
    * Per-address operation chain. Both encrypt and decrypt mutate ratchet
    * state in place (counter, DH key, skipped-keys cache); concurrent
@@ -72,11 +83,46 @@ export class ShadeSessionManager {
   constructor(
     private readonly crypto: CryptoProvider,
     private readonly storage: StorageProvider,
-    options: { events?: ShadeEventEmitter } = {},
+    options: { events?: ShadeEventEmitter; observability?: ObservabilityHook } = {},
   ) {
     if (options.events !== undefined) {
       this.events = options.events;
     }
+    this.observability = options.observability ?? NOOP_HOOK;
+  }
+
+  /**
+   * Wrap a per-peer crypto op in a PII-safe span. The span captures the
+   * mutex-acquire latency separately from the inner crypto work so a
+   * "ratchet contention" pathology shows up clearly in traces.
+   */
+  private async withSpan<T>(
+    op: 'encrypt' | 'decrypt',
+    address: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    const span: Span = this.observability.startSpan(`shade.session.${op}`, {
+      [ATTR_OP]: op,
+      [ATTR_PEER_HASH]: peerHash(address),
+    });
+    const lockStart = nowMs();
+    try {
+      return await this.runUnderPeerLock(address, async () => {
+        span.setAttribute('shade.lock.wait_ms', Math.round(nowMs() - lockStart));
+        const result = await fn();
+        span.setAttribute(ATTR_RESULT, 'ok');
+        span.setStatus('ok');
+        return result;
+      });
+    } catch (err) {
+      span.setAttribute(ATTR_RESULT, 'error');
+      span.setAttribute(ATTR_ERROR_CODE, sessionErrorCodeOf(err));
+      span.recordException(err);
+      span.setStatus('error');
+      throw err;
+    } finally {
+      span.end();
+    }
   }
 
   /**
@@ -396,7 +442,7 @@ export class ShadeSessionManager {
    * Subsequent messages are standard RatchetMessages.
    */
   async encrypt(address: string, plaintext: string): Promise<ShadeEnvelope> {
-    return this.runUnderPeerLock(address, async () => {
+    return this.withSpan('encrypt', address, async () => {
       const session = await this.storage.getSession(address);
       if (!session) throw new NoSessionError(address);
 
@@ -444,7 +490,7 @@ export class ShadeSessionManager {
    * Decrypt a message from a peer. Handles both PreKeyMessage and RatchetMessage.
    */
   async decrypt(address: string, envelope: ShadeEnvelope): Promise<string> {
-    return this.runUnderPeerLock(address, async () => {
+    return this.withSpan('decrypt', address, async () => {
       if (envelope.type === 'prekey') {
         return this.decryptPreKeyMessage(address, envelope.content as PreKeyMessage);
       }
@@ -522,3 +568,18 @@ function arraysEqual(a: Uint8Array, b: Uint8Array): boolean {
   }
   return true;
 }
+
+function nowMs(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function sessionErrorCodeOf(err: unknown): string {
+  if (err === null || err === undefined) return 'SHADE_UNKNOWN';
+  if (typeof err === 'object') {
+    const code = (err as { code?: unknown }).code;
+    if (typeof code === 'string' && code.length > 0) return code;
+    const name = (err as { name?: unknown }).name;
+    if (typeof name === 'string' && name.length > 0) return name;
+  }
+  return 'SHADE_UNKNOWN';
+}

packages/shade-core/src/storage.ts

@@ -38,6 +38,29 @@ export interface PersistedStreamState {
   updatedAt: number;
 }
 
+/**
+ * Why a peer's fingerprint was deemed verified.
+ *  - `user`: human did the side-channel comparison and confirmed.
+ *  - `transitive`: trust derived from another verified party (reserved for V3.10).
+ *  - `tofu-after-warning`: caller bypassed gate after seeing a warning.
+ */
+export type PeerVerificationSource = 'user' | 'transitive' | 'tofu-after-warning';
+
+/**
+ * Persistent record that a peer's safety number was verified at a point
+ * in time. `identityVersion` is the local counter for that peer's identity:
+ * incrementing it (e.g. via `bumpPeerIdentityVersion` on `acceptIdentityChange`)
+ * invalidates the saved verification because `isPeerVerified` requires the
+ * stored version to equal the current version.
+ */
+export interface PeerVerification {
+  peerAddress: string;
+  fingerprint: string;
+  verifiedAt: number;
+  verifiedBy: PeerVerificationSource;
+  identityVersion: number;
+}
+
 /**
  * StorageProvider — abstract interface for persisting cryptographic state.
  *
@@ -115,6 +138,34 @@ export interface StorageProvider {
   /** Remove retired identities older than the given timestamp */
   pruneRetiredIdentities(olderThan: number): Promise<void>;
 
+  // ─── Peer verifications (V3.3) ────────────────────────────
+
+  /**
+   * Persist or replace the verification record for a peer. Idempotent
+   * upsert on `peerAddress`.
+   */
+  savePeerVerification(verification: PeerVerification): Promise<void>;
+
+  /** Look up the saved verification for a peer (null if never verified). */
+  getPeerVerification(address: string): Promise<PeerVerification | null>;
+
+  /** Remove a peer's verification record (e.g. user revoked trust). */
+  removePeerVerification(address: string): Promise<void>;
+
+  /**
+   * Returns the current local identity-version counter for a peer.
+   * Defaults to 1 when the peer has never been seen. Bumped by
+   * `bumpPeerIdentityVersion` whenever the peer rotates identity.
+   */
+  getPeerIdentityVersion(address: string): Promise<number>;
+
+  /**
+   * Increment the peer's identity-version counter and return the new value.
+   * Called from `acceptIdentityChange` so previous verification rows (which
+   * carry the old version number) become stale.
+   */
+  bumpPeerIdentityVersion(address: string): Promise<number>;
+
   // ─── Stream-transfer resume state (optional, added in v0.2.0) ──
 
   /**

packages/shade-core/tests/cross-platform-vectors.test.ts

@@ -8,12 +8,23 @@ import {
   kdfChainKey,
   deriveInitialRootKey,
 } from '../src/index.js';
-import { encodeEnvelope, decodeEnvelope } from '@shade/proto';
-import type { RatchetMessage, ShadeEnvelope } from '../src/index.js';
+import { encodeEnvelope, decodeEnvelope, encodeStreamChunk, decodeStreamChunk } from '@shade/proto';
+import type { PreKeyMessage, RatchetMessage, ShadeEnvelope } from '../src/index.js';
+// Imported via relative path: shade-streams depends on shade-core, so adding
+// it to shade-core's dependencies would create a workspace cycle.
+import {
+  deriveStreamKey,
+  deriveLaneKey,
+  buildChunkNonce,
+  buildChunkAad,
+  aesGcmEncryptWithNonce,
+  aesGcmDecryptWithNonce,
+} from '../../shade-streams/src/index.js';
 
 const crypto = new SubtleCryptoProvider();
 
 const VECTORS_DIR = join(import.meta.dir, '..', '..', '..', 'test-vectors');
+const EXPECTED_VECTOR_VERSION = 2;
 
 function hex(bytes: Uint8Array): string {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
@@ -27,8 +38,49 @@ function fromHex(str: string): Uint8Array {
   return bytes;
 }
 
-function loadVectors(name: string): any {
-  return JSON.parse(readFileSync(join(VECTORS_DIR, name), 'utf-8'));
+function loadVectors(name: string): { version: number; vectors: any[] } {
+  const parsed = JSON.parse(readFileSync(join(VECTORS_DIR, name), 'utf-8'));
+  expect(parsed.version).toBe(EXPECTED_VECTOR_VERSION);
+  return parsed;
+}
+
+async function aesGcmEncryptDeterministic(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Promise<Uint8Array> {
+  const subtle = globalThis.crypto.subtle;
+  const aesKey = await subtle.importKey(
+    'raw',
+    key as unknown as ArrayBuffer,
+    'AES-GCM',
+    false,
+    ['encrypt', 'decrypt'],
+  );
+  const out = await subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv: nonce as unknown as ArrayBuffer,
+      additionalData: aad as unknown as ArrayBuffer,
+    },
+    aesKey,
+    plaintext as unknown as ArrayBuffer,
+  );
+  return new Uint8Array(out);
+}
+
+function encodeRatchetHeader(
+  dhPublicKey: Uint8Array,
+  previousCounter: number,
+  counter: number,
+): Uint8Array {
+  const buf = new Uint8Array(40);
+  buf.set(dhPublicKey, 0);
+  const view = new DataView(buf.buffer);
+  view.setUint32(32, previousCounter, false);
+  view.setUint32(36, counter, false);
+  return buf;
 }
 
 describe('Cross-platform test vectors', () => {
@@ -82,9 +134,10 @@ describe('Cross-platform test vectors', () => {
     }
   });
 
-  test('Wire format vectors match', () => {
+  test('Wire format: RatchetMessage encode + decode', () => {
     const { vectors } = loadVectors('wire-format.json');
-    const v = vectors[0];
+    const v = vectors.find((x: any) => x.kind === 'ratchet');
+    expect(v).toBeDefined();
 
     const msg: RatchetMessage = {
       dhPublicKey: fromHex(v.message.dhPublicKey),
@@ -102,11 +155,295 @@ describe('Cross-platform test vectors', () => {
     const encoded = encodeEnvelope(envelope);
     expect(hex(encoded)).toBe(v.encoded);
 
-    // Also verify round-trip decode
     const decoded = decodeEnvelope(encoded);
     expect(decoded.type).toBe('ratchet');
     const rm = decoded.content as RatchetMessage;
     expect(rm.counter).toBe(msg.counter);
     expect(hex(rm.ciphertext)).toBe(hex(msg.ciphertext));
   });
+
+  test('Wire format: PreKeyMessage encode + decode (with and without OTPK)', () => {
+    const { vectors } = loadVectors('wire-format.json');
+    const preKeyVectors = vectors.filter((x: any) => x.kind === 'prekey');
+    expect(preKeyVectors.length).toBeGreaterThanOrEqual(2);
+
+    for (const v of preKeyVectors) {
+      const inner: RatchetMessage = {
+        dhPublicKey: fromHex(v.message.inner.dhPublicKey),
+        previousCounter: v.message.inner.previousCounter,
+        counter: v.message.inner.counter,
+        ciphertext: fromHex(v.message.inner.ciphertext),
+        nonce: fromHex(v.message.inner.nonce),
+      };
+      const pre: PreKeyMessage = {
+        registrationId: v.message.registrationId,
+        preKeyId: v.message.preKeyId === null ? undefined : v.message.preKeyId,
+        signedPreKeyId: v.message.signedPreKeyId,
+        ephemeralKey: fromHex(v.message.ephemeralKey),
+        identityDHKey: fromHex(v.message.identityDHKey),
+        message: inner,
+      };
+      const envelope: ShadeEnvelope = {
+        type: 'prekey',
+        content: pre,
+        timestamp: 0,
+        senderAddress: '',
+      };
+      const encoded = encodeEnvelope(envelope);
+      expect(hex(encoded)).toBe(v.encoded);
+
+      const decoded = decodeEnvelope(encoded);
+      expect(decoded.type).toBe('prekey');
+      const dm = decoded.content as PreKeyMessage;
+      expect(dm.registrationId).toBe(pre.registrationId);
+      expect(dm.preKeyId).toBe(pre.preKeyId);
+      expect(dm.signedPreKeyId).toBe(pre.signedPreKeyId);
+      expect(hex(dm.ephemeralKey)).toBe(hex(pre.ephemeralKey));
+      expect(hex(dm.message.ciphertext)).toBe(hex(inner.ciphertext));
+    }
+  });
+
+  test('Streams 0x11: deriveStreamKey + deriveLaneKey + nonce/AAD + chunk encrypt + wire roundtrip', async () => {
+    const { vectors } = loadVectors('streams.json');
+
+    // 1. deriveStreamKey
+    const sk = vectors.find((v: any) => v.description.startsWith('deriveStreamKey'));
+    expect(sk).toBeDefined();
+    const streamKey = await deriveStreamKey(crypto, fromHex(sk.streamSecret), fromHex(sk.streamId));
+    expect(hex(streamKey)).toBe(sk.streamKey);
+
+    // 2. deriveLaneKey for each laneId
+    const lk = vectors.find((v: any) => v.description.startsWith('deriveLaneKey'));
+    expect(lk).toBeDefined();
+    for (const lane of lk.lanes) {
+      const k = await deriveLaneKey(crypto, fromHex(lk.streamKey), fromHex(lk.streamId), lane.laneId);
+      expect(hex(k)).toBe(lane.laneKey);
+    }
+
+    // 3. buildChunkNonce
+    const nv = vectors.find((v: any) => v.description.startsWith('buildChunkNonce'));
+    expect(nv).toBeDefined();
+    for (const n of nv.nonces) {
+      const seq = BigInt(n.seq);
+      const out = buildChunkNonce(n.laneId, seq);
+      expect(hex(out)).toBe(n.nonce);
+    }
+
+    // 4. buildChunkAad
+    const av = vectors.find((v: any) => v.description.startsWith('buildChunkAad'));
+    expect(av).toBeDefined();
+    for (const c of av.cases) {
+      const seq = BigInt(c.seq);
+      const out = buildChunkAad(fromHex(av.streamId), c.laneId, seq, c.isLast);
+      expect(hex(out)).toBe(c.aad);
+    }
+
+    // 5. End-to-end chunk encrypt + decrypt
+    const ev = vectors.find((v: any) => v.description.startsWith('End-to-end chunk encrypt'));
+    expect(ev).toBeDefined();
+    const ct = await aesGcmEncryptWithNonce(
+      fromHex(ev.laneKey),
+      fromHex(ev.nonce),
+      fromHex(ev.plaintext),
+      fromHex(ev.aad),
+    );
+    expect(hex(ct)).toBe(ev.ciphertext);
+    const pt = await aesGcmDecryptWithNonce(
+      fromHex(ev.laneKey),
+      fromHex(ev.nonce),
+      fromHex(ev.ciphertext),
+      fromHex(ev.aad),
+    );
+    expect(hex(pt)).toBe(ev.plaintext);
+
+    // 6. Wire 0x11 envelope encode/decode
+    const wv = vectors.find((v: any) => v.description.startsWith('Wire 0x11'));
+    expect(wv).toBeDefined();
+    const encoded = encodeStreamChunk({
+      streamId: fromHex(wv.streamId),
+      laneId: wv.laneId,
+      seq: BigInt(wv.seq),
+      isLast: wv.isLast,
+      nonce: fromHex(wv.nonce),
+      aad: fromHex(wv.extraAad),
+      ciphertext: fromHex(wv.ciphertext),
+    });
+    expect(hex(encoded)).toBe(wv.encoded);
+    const decoded = decodeStreamChunk(encoded);
+    expect(hex(decoded.streamId)).toBe(wv.streamId);
+    expect(decoded.laneId).toBe(wv.laneId);
+    expect(decoded.seq.toString()).toBe(wv.seq);
+    expect(decoded.isLast).toBe(wv.isLast);
+    expect(hex(decoded.nonce)).toBe(wv.nonce);
+    expect(hex(decoded.ciphertext)).toBe(wv.ciphertext);
+  });
+
+  test('Backup v1: HKDF backupKey + AES-GCM roundtrip', async () => {
+    const { vectors } = loadVectors('backup.json');
+
+    const kv = vectors.find((v: any) => v.description.startsWith('Backup v1: HKDF'));
+    expect(kv).toBeDefined();
+    const backupKey = await crypto.hkdf(
+      new TextEncoder().encode(kv.passphrase),
+      fromHex(kv.salt),
+      new TextEncoder().encode(kv.info),
+      32,
+    );
+    expect(hex(backupKey)).toBe(kv.backupKey);
+
+    const ev = vectors.find((v: any) => v.description.startsWith('Backup v1: AES-256-GCM'));
+    expect(ev).toBeDefined();
+    const ct = await aesGcmEncryptDeterministic(
+      fromHex(ev.backupKey),
+      fromHex(ev.nonce),
+      fromHex(ev.plaintext),
+      new Uint8Array(0),
+    );
+    expect(hex(ct)).toBe(ev.ciphertext);
+
+    const pt = await crypto.aesGcmDecrypt(
+      fromHex(ev.backupKey),
+      fromHex(ev.ciphertext),
+      fromHex(ev.nonce),
+    );
+    expect(hex(pt)).toBe(ev.plaintext);
+  });
+
+  test('Group sender-keys: header AAD + step + Ed25519 signature', async () => {
+    const { vectors } = loadVectors('group.json');
+
+    // 1. Header AAD encoding
+    const hv = vectors.find((v: any) => v.description.startsWith('Sender header AAD'));
+    expect(hv).toBeDefined();
+    const enc = new TextEncoder();
+    const gBytes = enc.encode(hv.groupId);
+    const sBytes = enc.encode(hv.senderAddress);
+    const aad = new Uint8Array(2 + gBytes.length + 2 + sBytes.length + 4);
+    const view = new DataView(aad.buffer);
+    let off = 0;
+    view.setUint16(off, gBytes.length, false); off += 2;
+    aad.set(gBytes, off); off += gBytes.length;
+    view.setUint16(off, sBytes.length, false); off += 2;
+    aad.set(sBytes, off); off += sBytes.length;
+    view.setUint32(off, hv.iteration, false);
+    expect(hex(aad)).toBe(hv.aad);
+
+    // 2. Sender-key step
+    const sv = vectors.find((v: any) => v.description.startsWith('Sender-key step'));
+    expect(sv).toBeDefined();
+    const chain = await kdfChainKey(crypto, fromHex(sv.chainKey));
+    expect(hex(chain.newChainKey)).toBe(sv.newChainKey);
+    expect(hex(chain.messageKey)).toBe(sv.messageKey);
+
+    const ct = await aesGcmEncryptDeterministic(
+      chain.messageKey,
+      fromHex(sv.nonce),
+      fromHex(sv.plaintext),
+      fromHex(sv.aad),
+    );
+    expect(hex(ct)).toBe(sv.ciphertext);
+
+    // Ed25519 sign(aad || ct) — verify signature is valid for the recorded keys
+    const signed = new Uint8Array(fromHex(sv.aad).length + ct.length);
+    signed.set(fromHex(sv.aad), 0);
+    signed.set(ct, fromHex(sv.aad).length);
+    const ok = await crypto.verify(
+      fromHex(sv.signingPublicKey),
+      signed,
+      fromHex(sv.signature),
+    );
+    expect(ok).toBe(true);
+
+    // Decrypt roundtrip
+    const pt = await crypto.aesGcmDecrypt(
+      chain.messageKey,
+      fromHex(sv.ciphertext),
+      fromHex(sv.nonce),
+      fromHex(sv.aad),
+    );
+    expect(hex(pt)).toBe(sv.plaintext);
+  });
+
+  test('Storage encryption HKDF subset: storageKey + fieldKey + rowNonce', async () => {
+    const { vectors } = loadVectors('storage-hkdf.json');
+
+    const sv = vectors.find((v: any) => v.description.startsWith('Storage HKDF: storageKey'));
+    expect(sv).toBeDefined();
+    const storageKey = await crypto.hkdf(
+      fromHex(sv.masterKey),
+      new Uint8Array(0),
+      new TextEncoder().encode('shade-storage-v1'),
+      32,
+    );
+    expect(hex(storageKey)).toBe(sv.storageKey);
+
+    const fv = vectors.find((v: any) => v.description.startsWith('Storage HKDF: fieldKey'));
+    expect(fv).toBeDefined();
+    for (const f of fv.fields) {
+      const k = await crypto.hkdf(
+        fromHex(fv.storageKey),
+        new Uint8Array(0),
+        new TextEncoder().encode(`shade-field-v1:${f.table}:${f.column}`),
+        32,
+      );
+      expect(hex(k)).toBe(f.fieldKey);
+    }
+
+    const nv = vectors.find((v: any) => v.description.startsWith('Storage HKDF: rowNonce'));
+    expect(nv).toBeDefined();
+    for (const n of nv.nonces) {
+      const out = await crypto.hkdf(
+        fromHex(nv.rowKey),
+        new Uint8Array(0),
+        new TextEncoder().encode(`shade-row-nonce-v1:${n.table}:${n.pk}`),
+        12,
+      );
+      expect(hex(out)).toBe(n.nonce);
+    }
+  });
+
+  test('Ratchet step: deterministic encrypt + decrypt roundtrip', async () => {
+    const { vectors } = loadVectors('ratchet-step.json');
+    for (const v of vectors) {
+      const rootKey = fromHex(v.inputs.rootKey);
+      const dhSendPriv = fromHex(v.inputs.dhSendPrivateKey);
+      const dhSendPub = fromHex(v.inputs.dhSendPublicKey);
+      const dhRemotePub = fromHex(v.inputs.dhRemotePublicKey);
+      const plaintext = fromHex(v.inputs.plaintext);
+      const nonce = fromHex(v.inputs.nonce);
+      const previousCounter: number = v.inputs.previousCounter;
+      const counter: number = v.inputs.counter;
+
+      // 1. DH
+      const dhOutput = await crypto.x25519(dhSendPriv, dhRemotePub);
+      expect(hex(dhOutput)).toBe(v.derived.dhOutput);
+
+      // 2. kdfRootKey
+      const root = await kdfRootKey(crypto, rootKey, dhOutput);
+      expect(hex(root.newRootKey)).toBe(v.derived.newRootKey);
+      expect(hex(root.chainKey)).toBe(v.derived.chainKey);
+
+      // 3. kdfChainKey
+      const chain = await kdfChainKey(crypto, root.chainKey);
+      expect(hex(chain.newChainKey)).toBe(v.derived.newChainKey);
+      expect(hex(chain.messageKey)).toBe(v.derived.messageKey);
+
+      // 4. Header AAD
+      const aad = encodeRatchetHeader(dhSendPub, previousCounter, counter);
+      expect(hex(aad)).toBe(v.derived.aad);
+
+      // 5. AES-GCM encrypt with fixed nonce
+      const ciphertext = await aesGcmEncryptDeterministic(chain.messageKey, nonce, plaintext, aad);
+      expect(hex(ciphertext)).toBe(v.ciphertext);
+
+      // 6. Roundtrip decrypt — verify the recorded ciphertext recovers the plaintext
+      const recovered = await crypto.aesGcmDecrypt(
+        chain.messageKey,
+        fromHex(v.ciphertext),
+        nonce,
+        aad,
+      );
+      expect(hex(recovered)).toBe(v.inputs.plaintext);
+    }
+  });
 });

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

@@ -31,6 +31,51 @@ async function setupPair(): Promise<{ alice: SessionState; bob: SessionState }>
 describe('Double Ratchet', () => {
   // ─── Basic Send/Receive ──────────────────────────────────
 
+  describe('initReceiverSession isolation', () => {
+    /**
+     * Regression — the V3.10 multi-sender recovery flow surfaced a
+     * bug where `initReceiverSession` shared a reference to the
+     * receiver's signed-prekey keypair with the new session. The
+     * first DH ratchet step zeroed the session's stale send-key
+     * private bytes — which were the SAME backing buffer as the
+     * persisted signed prekey. A subsequent X3DH from a different
+     * sender then derived a divergent root key and decryption
+     * failed.
+     *
+     * Fix: `initReceiverSession` copies the keypair into the
+     * session. Verify here.
+     */
+    test('does not mutate the caller-provided keypair after a DH ratchet step', async () => {
+      const rootKey = crypto.randomBytes(32);
+      const remoteIdentityKey = crypto.randomBytes(32);
+      const bobDH = await crypto.generateX25519KeyPair();
+      const originalPrivate = new Uint8Array(bobDH.privateKey);
+      const originalPublic = new Uint8Array(bobDH.publicKey);
+
+      const bob = initReceiverSession(rootKey, remoteIdentityKey, bobDH);
+
+      // Drive a full receive that triggers `performDHRatchetStep`
+      // via a message with a fresh dhPublicKey.
+      const aliceFirst = await initSenderSession(crypto, rootKey, remoteIdentityKey, bobDH.publicKey);
+      const msg = await ratchetEncrypt(crypto, aliceFirst, enc.encode('hi'));
+      await ratchetDecrypt(crypto, bob, msg);
+
+      // The ORIGINAL keypair must not have been touched, so a
+      // second X3DH-style establishment using the same prekey
+      // material still succeeds.
+      expect(Array.from(bobDH.privateKey)).toEqual(Array.from(originalPrivate));
+      expect(Array.from(bobDH.publicKey)).toEqual(Array.from(originalPublic));
+
+      // Sanity-check: a second receiver session built from the
+      // same keypair should still decrypt fresh sender traffic.
+      const bob2 = initReceiverSession(rootKey, remoteIdentityKey, bobDH);
+      const aliceSecond = await initSenderSession(crypto, rootKey, remoteIdentityKey, bobDH.publicKey);
+      const msg2 = await ratchetEncrypt(crypto, aliceSecond, enc.encode('hi again'));
+      const plain2 = await ratchetDecrypt(crypto, bob2, msg2);
+      expect(dec.decode(plain2)).toBe('hi again');
+    });
+  });
+
   describe('basic send/receive', () => {
     test('Alice encrypts, Bob decrypts', async () => {
       const { alice, bob } = await setupPair();