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/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) ──
 
   /**