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-sdk/src/shade.ts

@@ -4,12 +4,28 @@ import {
   ShadeEventEmitter,
   NoSessionError,
 } from '@shade/core';
-import { SubtleCryptoProvider, MemoryStorage } from '@shade/crypto-web';
+import {
+  FingerprintGateRegistry,
+  type FingerprintGateHandler,
+} from './gates.js';
+import {
+  SubtleCryptoProvider,
+  MemoryStorage,
+  createWorkerCryptoProvider,
+  type WorkerCryptoProvider,
+  createEncryptStream,
+  createDecryptStream,
+  type CreateEncryptStreamOptions,
+  type CreateDecryptStreamOptions,
+} from '@shade/crypto-web';
 import { encodeEnvelope, decodeEnvelope, inspectEnvelopeType } from '@shade/proto';
-import { ShadeFetchTransport } from '@shade/transport';
+import { ShadeFetchTransport, type KTVerifierOptions } from '@shade/transport';
+import { LightWitness } from '@shade/key-transparency';
+import type { SignedTreeHead } from '@shade/key-transparency';
 import {
   TransferEngine,
   ShadeTransferHttpTransport,
+  MultiTransportFallback,
   type ITransferTransport,
   type IncomingTransfer,
   type TransferHandle,
@@ -18,7 +34,14 @@ import {
 } from '@shade/transfer';
 import type { Hono } from 'hono';
 import { BackgroundTasks } from './background.js';
-import { exportBackup, importBackup, backupToString, backupFromString } from './backup.js';
+import {
+  exportBackup,
+  applyBackupPayload,
+  decryptBackup,
+  backupToString,
+  backupFromString,
+} from './backup.js';
+import { computeFingerprint, deserializeIdentityKeyPair } from '@shade/core';
 import type { ResolvedConfig } from './config.js';
 import {
   ShadeControlChannel,
@@ -26,6 +49,75 @@ import {
   type ControlEnvelopeTransport,
 } from './streams-bridge.js';
 import { createFilesNamespace, type FilesNamespace } from '@shade/files';
+import type { ObservabilityHook } from '@shade/observability';
+import {
+  isAllowedThumbnailMime,
+  sha256Once,
+  THUMBNAIL_MAX_BYTES,
+  type StreamFileMetadata,
+  type ThumbnailMime,
+} from '@shade/streams';
+import {
+  generateThumbnail as generateThumbnailFromBlob,
+  type ThumbnailGenerationOptions,
+} from './thumbnail.js';
+
+/**
+ * V3.9 — extended upload options. The base `TransferOptions` is forwarded
+ * verbatim to `@shade/transfer`; the extra fields control the thumbnail
+ * companion-stream and never leak past the SDK boundary.
+ */
+/**
+ * V3.11 — opt-in WebRTC P2P transport. Pass to `shade.configureWebRTC()`
+ * before the engine is built. The shape mirrors `WebRtcConnectionManager`'s
+ * options without forcing the SDK to import `@shade/transport-webrtc` at
+ * the value layer (the import happens lazily inside `engine()`).
+ */
+export interface ShadeWebRtcConfig {
+  /**
+   * WebRTC adapter. Use `nativeRtcFactory()` from `@shade/transport-webrtc`
+   * in browsers / Deno / Cloudflare Workers; supply your own
+   * `IRtcFactory` for Node-class environments (`node-datachannel`, `wrtc`).
+   */
+  factory: import('@shade/transport-webrtc').IRtcFactory;
+  iceServers?: import('@shade/transport-webrtc').ShadeRtcConfig['iceServers'];
+  iceTransportPolicy?: import('@shade/transport-webrtc').ShadeRtcConfig['iceTransportPolicy'];
+  bundlePolicy?: import('@shade/transport-webrtc').ShadeRtcConfig['bundlePolicy'];
+  /** Default 30s. */
+  connectTimeoutMs?: number;
+  /** Default 30s. */
+  requestTimeoutMs?: number;
+  /** Default 4 MiB. */
+  backpressureThresholdBytes?: number;
+}
+
+/** Live WebRTC runtime returned by `shade.getWebRtcRuntime()`. */
+export interface ShadeWebRtcRuntime {
+  signaling: import('@shade/transport-webrtc').WebRtcSignalingChannel;
+  manager: import('@shade/transport-webrtc').WebRtcConnectionManager;
+  transport: import('@shade/transport-webrtc').WebRtcTransferTransport;
+  fallback: MultiTransportFallback;
+  /** Internal — wires `engine` into the receiver hooks once it's built. */
+  attachEngine(engine: TransferEngine): void;
+  /** Tear down the manager, the signaling channel, and any open peer connections. */
+  destroy(): void;
+}
+
+export interface ShadeUploadOptions extends TransferOptions {
+  /**
+   * Pre-generated thumbnail bytes + MIME. Use this on server runtimes
+   * where in-process image processing is already part of your pipeline,
+   * or when you have a richer thumbnail than the auto-generator would
+   * produce (e.g. center-cropped, branded watermark, etc.).
+   */
+  thumbnail?: { bytes: Uint8Array; mime: ThumbnailMime };
+  /**
+   * Browser auto-generation. Set to `true` for defaults, or pass a
+   * config object. Returns `null` (silently skips the thumbnail) on
+   * runtimes lacking `OffscreenCanvas` + `createImageBitmap`.
+   */
+  generateThumbnail?: boolean | ThumbnailGenerationOptions;
+}
 
 /**
  * The high-level Shade API.
@@ -63,6 +155,25 @@ export class Shade {
   // `@shade/files` namespace, lazy + memoized.
   private filesNamespace: FilesNamespace | null = null;
 
+  // V3.12 — light-witness for split-view detection.
+  private ktWitness: LightWitness | null = null;
+
+  // V3.11 WebRTC P2P transport. Lazy-built on first engine() if configured.
+  private webrtcConfig: ShadeWebRtcConfig | null = null;
+  private webrtcRuntime: ShadeWebRtcRuntime | null = null;
+
+  // V3.8 Worker-Crypto. Lazy: configured via `configureWorkerCrypto()`,
+  // spawned the first time `encryptStream`/`decryptStream` is used.
+  private workerCryptoConfig: {
+    workerUrl: URL | string;
+    idleTimeoutMs?: number;
+  } | null = null;
+  private workerCrypto: WorkerCryptoProvider | null = null;
+  private workerCryptoBoot: Promise<WorkerCryptoProvider> | null = null;
+
+  // V3.3 fingerprint gates. Created in `initialize()` once storage is up.
+  private gates!: FingerprintGateRegistry;
+
   constructor(private readonly config: ResolvedConfig) {}
 
   /**
@@ -83,6 +194,9 @@ export class Shade {
     // Step 2: Session manager with event bus attached
     this.manager = new ShadeSessionManager(this.crypto, this.storage, {
       events: this.events,
+      ...(this.config.observability !== undefined
+        ? { observability: this.config.observability }
+        : {}),
     });
     await this.manager.initialize();
 
@@ -92,10 +206,49 @@ export class Shade {
     // Step 4: Transport with our signing key
     const identity = await this.storage.getIdentityKeyPair();
     if (!identity) throw new Error('Identity not available after initialize');
+
+    // V3.12 — wire up KT verifier + light-witness if configured.
+    let ktOpts: KTVerifierOptions | undefined;
+    if (this.config.keyTransparency) {
+      const baseUrl = this.config.prekeyServer;
+      this.ktWitness = new LightWitness({
+        crypto: this.crypto,
+        logPublicKey: this.config.keyTransparency.logPublicKey,
+        maxStaleMs: this.config.keyTransparency.maxStaleMs,
+        maxStored: this.config.keyTransparency.witnessMaxStored,
+        fetcher: {
+          async fetchLatestSTH() {
+            const res = await fetch(`${baseUrl}/v1/kt/sth`);
+            if (!res.ok) throw new Error(`KT /sth: ${res.status}`);
+            return res.json();
+          },
+          async fetchConsistencyProof(from, to) {
+            const res = await fetch(`${baseUrl}/v1/kt/consistency?from=${from}&to=${to}`);
+            if (!res.ok) throw new Error(`KT /consistency: ${res.status}`);
+            return res.json();
+          },
+        },
+      });
+      ktOpts = {
+        mode: this.config.keyTransparency.mode,
+        logPublicKey: this.config.keyTransparency.logPublicKey,
+        maxStaleMs: this.config.keyTransparency.maxStaleMs,
+        onObserveSth: async (sth: SignedTreeHead) => {
+          if (this.ktWitness) {
+            // The fetched STH was already verified by the transport; feed
+            // it to the witness for split-view tracking. `observe` may also
+            // throw on split-view — we let it propagate to the caller.
+            await this.ktWitness.observe(sth);
+          }
+        },
+      };
+    }
+
     this.transport = new ShadeFetchTransport({
       baseUrl: this.config.prekeyServer,
       crypto: this.crypto,
       signingPrivateKey: identity.signingPrivateKey,
+      ...(ktOpts ? { keyTransparency: ktOpts } : {}),
     });
 
     // Step 5: Initial prekeys + register
@@ -124,6 +277,9 @@ export class Shade {
     );
     this._background.start();
 
+    // Step 7: V3.3 fingerprint gates
+    this.gates = new FingerprintGateRegistry(this.storage);
+
     this.initialized = true;
   }
 
@@ -183,6 +339,25 @@ export class Shade {
     return this.transport;
   }
 
+  /**
+   * V3.12 — access the configured Key-Transparency light-witness, or
+   * `null` when KT was not configured. Useful for surfacing observed
+   * STHs to UI / dashboards, or for manual gossip checks against
+   * trusted peers.
+   */
+  getKTWitness(): LightWitness | null {
+    return this.ktWitness;
+  }
+
+  /**
+   * Returns the OTel observability hook the SDK was configured with, or
+   * `undefined` if observability is off. Used by `@shade/files` and other
+   * sub-modules to inherit the same tracer the rest of the SDK uses.
+   */
+  getObservability(): ObservabilityHook | undefined {
+    return this.config.observability;
+  }
+
   /**
    * Encrypt a message to a peer. Auto-establishes a session if none exists.
    * Returns the ShadeEnvelope ready to send over any transport.
@@ -251,6 +426,97 @@ export class Shade {
     return normalize(remote) === normalize(fingerprint);
   }
 
+  // ─── V3.3 fingerprint gates ───────────────────────────────
+
+  /**
+   * Register a handler that runs before `upload()` proceeds when the file
+   * is at or above `threshold` bytes and the peer is not yet verified.
+   * Return `true` to allow + persist the verification, `false` to abort.
+   *
+   * Default threshold (when this method is never called): 10 MiB.
+   */
+  beforeFirstLargeFile(threshold: number, handler: FingerprintGateHandler): void {
+    if (!this.initialized) throw new Error('Not initialized');
+    this.gates.registerFirstLargeFile(threshold, handler);
+  }
+
+  /**
+   * Register a handler that runs before `importBackup()` writes to storage.
+   * The handler receives the fingerprint of the identity *embedded in the
+   * backup blob*, so the user can OOB-confirm the backup is theirs.
+   */
+  beforeBackupImport(handler: FingerprintGateHandler): void {
+    if (!this.initialized) throw new Error('Not initialized');
+    this.gates.registerBackupImport(handler);
+  }
+
+  /**
+   * Register a handler that runs the first time a peer's rotated identity
+   * is observed (via `acceptIdentityChange` or X3DH against a new bundle).
+   */
+  beforeNewDeviceTrust(handler: FingerprintGateHandler): void {
+    if (!this.initialized) throw new Error('Not initialized');
+    this.gates.registerNewDeviceTrust(handler);
+  }
+
+  /**
+   * Register a handler that runs per-recipient before an inbox fan-out
+   * delivery (V3.6). Reserved hook — wired here so apps can register it
+   * today and have it active automatically when V3.6 ships.
+   */
+  beforeInboxFanout(handler: FingerprintGateHandler): void {
+    if (!this.initialized) throw new Error('Not initialized');
+    this.gates.registerInboxFanout(handler);
+  }
+
+  /**
+   * Mark a peer as verified at their current fingerprint. Call this from
+   * your own UI (e.g. after the user scans a QR code or reads the safety
+   * number aloud) to satisfy any gate without going through the handler.
+   */
+  async markPeerVerified(address: string): Promise<void> {
+    if (!this.initialized) throw new Error('Not initialized');
+    const fingerprint = await this.manager.getRemoteFingerprint(address);
+    await this.gates.markVerified(address, fingerprint, 'user');
+  }
+
+  /**
+   * Returns whether `address` has a current verification (fingerprint and
+   * identity-version both still match).
+   */
+  async isPeerVerified(address: string): Promise<boolean> {
+    if (!this.initialized) throw new Error('Not initialized');
+    const fingerprint = await this.manager.getRemoteFingerprint(address);
+    return this.gates.isVerified(address, fingerprint);
+  }
+
+  /** Drop any persisted verification for `address`. */
+  async unmarkPeerVerified(address: string): Promise<void> {
+    if (!this.initialized) throw new Error('Not initialized');
+    await this.gates.revoke(address);
+  }
+
+  /**
+   * Accept a peer's rotated identity. Bumps the per-peer identity-version
+   * counter so any earlier verification automatically goes stale, then
+   * runs the `beforeNewDeviceTrust` gate before the new key is pinned.
+   */
+  async acceptIdentityChange(address: string, newIdentityKey: Uint8Array): Promise<void> {
+    if (!this.initialized) throw new Error('Not initialized');
+    await this.storage.bumpPeerIdentityVersion(address);
+    const newFingerprint = await computeFingerprint(
+      this.crypto,
+      // X3DH stores DH-only "trusted identity"; in this SDK the trusted
+      // entry IS the DH public key. We feed it as both args so the
+      // fingerprint binds to the rotated key material the user is asked
+      // to confirm.
+      newIdentityKey,
+      newIdentityKey,
+    );
+    await this.gates.checkNewDeviceTrust(address, newFingerprint);
+    await this.manager.acceptIdentityChange(address, newIdentityKey);
+  }
+
   /** Manually rotate the identity (destructive — see docs) */
   async rotate(): Promise<void> {
     if (!this.initialized) throw new Error('Not initialized');
@@ -311,16 +577,29 @@ export class Shade {
   /**
    * Restore state from a backup string. Overwrites existing state.
    * Call this BEFORE initialize() on a fresh device, or after shutdown() + re-init.
+   *
+   * V3.3: invokes the `beforeBackupImport` gate. The handler receives the
+   * fingerprint of the identity *embedded in the backup* — this lets the
+   * user OOB-confirm that the backup is theirs before sessions and
+   * pinned-trust entries are written to disk.
    */
   async importBackup(backupString: string, passphrase: string): Promise<void> {
     if (!this.initialized) throw new Error('Not initialized');
     const blob = backupFromString(backupString);
-    await importBackup(this.crypto, this.storage, blob, passphrase);
+    const payload = await decryptBackup(this.crypto, blob, passphrase);
+    const backupFingerprint = await fingerprintFromBackupPayload(this.crypto, payload);
+    await this.gates.checkBackupImport(this.address, backupFingerprint);
+    await applyBackupPayload(this.storage, payload);
     // Reload identity after restore
     const restored = await this.storage.getIdentityKeyPair();
     if (restored) {
       // Rebuild the manager and transport with the restored identity
-      this.manager = new ShadeSessionManager(this.crypto, this.storage, { events: this.events });
+      this.manager = new ShadeSessionManager(this.crypto, this.storage, {
+        events: this.events,
+        ...(this.config.observability !== undefined
+          ? { observability: this.config.observability }
+          : {}),
+      });
       await this.manager.initialize();
       this.transport = new ShadeFetchTransport({
         baseUrl: this.config.prekeyServer,
@@ -335,6 +614,14 @@ export class Shade {
     this._background?.stop();
     if (this.transferEngine !== null) this.transferEngine.destroy();
     if (this.controlChannel !== null) this.controlChannel.destroy();
+    if (this.webrtcRuntime !== null) {
+      this.webrtcRuntime.destroy();
+      this.webrtcRuntime = null;
+    }
+    if (this.workerCrypto !== null) {
+      await this.workerCrypto.destroy();
+      this.workerCrypto = null;
+    }
     // Close storage if it has a close method (SQLite)
     const closable = this.storage as unknown as { close?: () => void | Promise<void> };
     if (typeof closable.close === 'function') {
@@ -343,6 +630,110 @@ export class Shade {
     this.initialized = false;
   }
 
+  // ─── Worker-Crypto streams (V3.8) ──────────────────────────
+
+  /**
+   * Opt in to Web Workers crypto: subsequent `encryptStream` /
+   * `decryptStream` calls offload all AEAD work to a dedicated worker so
+   * the main thread stays under the 16 ms-per-frame budget for big
+   * uploads. The worker is spawned on first use and self-terminates
+   * after `idleTimeoutMs` of inactivity (default 30 s).
+   *
+   * Bundlers resolve worker URLs differently — the recommended idiom is:
+   *
+   * ```ts
+   * shade.configureWorkerCrypto({
+   *   workerUrl: new URL('@shade/crypto-web/worker', import.meta.url),
+   * });
+   * ```
+   *
+   * See `docs/web-workers.md` for Vite / Webpack / Rollup recipes and
+   * Safari notes.
+   */
+  configureWorkerCrypto(opts: {
+    workerUrl: URL | string;
+    idleTimeoutMs?: number;
+  }): void {
+    this.workerCryptoConfig = opts;
+  }
+
+  /**
+   * Encrypt a `ReadableStream<Uint8Array>` of plaintext into stream-chunk
+   * wire envelopes via a Web Worker.
+   *
+   * The caller pre-negotiates `streamId` + `streamSecret` with the peer
+   * (typically through `shade.upload()` for HTTP-based delivery, or any
+   * other channel). The returned `stream` is a TransformStream:
+   * pipe plaintext in, get encrypted chunks out.
+   *
+   * `laneSha256` resolves once the stream finishes (final chunk emitted
+   * with `isLast=true`). Compare it against the receiver's lane sha256
+   * for end-to-end integrity proof.
+   *
+   * Requires `configureWorkerCrypto()` to be called first.
+   */
+  encryptStream(
+    opts: Omit<CreateEncryptStreamOptions, 'provider'>,
+  ): Promise<{
+    stream: TransformStream<Uint8Array, Uint8Array>;
+    laneSha256: Promise<Uint8Array>;
+  }> {
+    return this.ensureWorkerCrypto().then((provider) =>
+      createEncryptStream({ provider, ...opts }),
+    );
+  }
+
+  /**
+   * Inverse of {@link Shade.encryptStream} — decrypt incoming wire
+   * envelopes back into plaintext. Each input chunk MUST be a complete
+   * stream-chunk envelope (the wire framing is the caller's job).
+   *
+   * Requires `configureWorkerCrypto()` to be called first.
+   */
+  decryptStream(
+    opts: Omit<CreateDecryptStreamOptions, 'provider'>,
+  ): Promise<{
+    stream: TransformStream<Uint8Array, Uint8Array>;
+    laneSha256: Promise<Uint8Array>;
+  }> {
+    return this.ensureWorkerCrypto().then((provider) =>
+      createDecryptStream({ provider, ...opts }),
+    );
+  }
+
+  /**
+   * Direct access to the worker-backed `CryptoProvider`. Use when you
+   * want to run a one-off heavy crypto op (X25519 batch DH, big HKDF
+   * derivation, etc.) off the main thread without setting up a stream.
+   */
+  async getWorkerCrypto(): Promise<WorkerCryptoProvider> {
+    return this.ensureWorkerCrypto();
+  }
+
+  private async ensureWorkerCrypto(): Promise<WorkerCryptoProvider> {
+    if (this.workerCrypto !== null) return this.workerCrypto;
+    if (this.workerCryptoBoot !== null) return this.workerCryptoBoot;
+    if (this.workerCryptoConfig === null) {
+      throw new Error(
+        'Call shade.configureWorkerCrypto({ workerUrl }) before encryptStream()/decryptStream(). See docs/web-workers.md.',
+      );
+    }
+    const cfg = this.workerCryptoConfig;
+    this.workerCryptoBoot = (async () => {
+      const provider = await createWorkerCryptoProvider({
+        workerUrl: cfg.workerUrl,
+        ...(cfg.idleTimeoutMs !== undefined ? { idleTimeoutMs: cfg.idleTimeoutMs } : {}),
+      });
+      this.workerCrypto = provider;
+      return provider;
+    })();
+    try {
+      return await this.workerCryptoBoot;
+    } finally {
+      this.workerCryptoBoot = null;
+    }
+  }
+
   // ─── Stream transfers (v0.2.0) ─────────────────────────────
 
   /**
@@ -380,9 +771,120 @@ export class Shade {
   /**
    * Upload bytes to a peer. Returns a `TransferHandle` that can be paused/
    * aborted and awaited. Requires `configureTransfers` to be called first.
+   *
+   * V3.3: when the file size is at or above the configured threshold
+   * (default 10 MiB) and the peer is not yet verified, the registered
+   * `beforeFirstLargeFile` handler is invoked. Rejection throws
+   * `FingerprintNotVerifiedError` before any bytes hit the wire.
+   *
+   * V3.9: pass `thumbnail: { bytes, mime }` to attach a pre-generated
+   * preview, or `generateThumbnail: true` to auto-derive a 256x256 preview
+   * from an image input in browser-class runtimes (no-op elsewhere). The
+   * thumbnail is shipped as a *separate* E2EE stream and referenced from
+   * the main stream's `fileMetadata`.
    */
-  async upload(opts: TransferOptions): Promise<TransferHandle> {
-    return (await this.engine()).upload(opts);
+  async upload(opts: ShadeUploadOptions): Promise<TransferHandle> {
+    if (!this.initialized) throw new Error('Not initialized');
+    const size = inferTransferSize(opts);
+    if (size !== null && size >= this.gates.getFirstLargeFileThreshold()) {
+      // Establish the session up-front so we have a fingerprint to gate on.
+      // For peers we've never contacted, this is the TOFU moment where the
+      // gate matters most.
+      if ((await this.storage.getSession(opts.to)) === null) {
+        await this.ensureSession(opts.to);
+      }
+      const fingerprint = await this.manager.getRemoteFingerprint(opts.to);
+      await this.gates.checkFirstLargeFile(opts.to, fingerprint, size);
+    }
+    const engine = await this.engine();
+    const thumbnail = await this.resolveThumbnail(opts);
+    if (thumbnail !== null) {
+      const fileMeta: StreamFileMetadata = {
+        ...(opts.metadata?.fileMetadata ?? {}),
+        thumbnailStreamId: thumbnail.streamId,
+        thumbnailHash: thumbnail.hashB64,
+        thumbnailMime: thumbnail.mime,
+        thumbnailBytes: thumbnail.bytes,
+      };
+      const merged: TransferOptions = {
+        ...opts,
+        metadata: {
+          ...(opts.metadata ?? {}),
+          fileMetadata: fileMeta,
+        },
+      };
+      return engine.upload(merged);
+    }
+    return engine.upload(opts);
+  }
+
+  /**
+   * Coordinate the thumbnail-side of a V3.9 upload. Resolves to either
+   *  - `null` — no thumbnail will be attached (caller passed neither
+   *     `thumbnail` nor a generator that produced bytes), or
+   *  - the streamId + sha256 + mime + bytes of the thumbnail-stream that
+   *    has now been kicked off (it runs to completion in the background;
+   *    the main upload's `done()` is independent).
+   */
+  private async resolveThumbnail(opts: ShadeUploadOptions): Promise<{
+    streamId: string;
+    hashB64: string;
+    mime: ThumbnailMime;
+    bytes: number;
+  } | null> {
+    let bytes: Uint8Array | null = null;
+    let mime: ThumbnailMime | null = null;
+    if (opts.thumbnail !== undefined) {
+      bytes = opts.thumbnail.bytes;
+      mime = opts.thumbnail.mime;
+    } else if (opts.generateThumbnail !== undefined && opts.generateThumbnail !== false) {
+      const genOpts: ThumbnailGenerationOptions =
+        opts.generateThumbnail === true ? {} : opts.generateThumbnail;
+      const gen = await generateThumbnailFromBlob(opts.input, genOpts);
+      if (gen !== null) {
+        bytes = gen.bytes;
+        mime = gen.mime;
+      }
+    }
+    if (bytes === null || mime === null) return null;
+    if (bytes.byteLength > THUMBNAIL_MAX_BYTES) {
+      throw new Error(
+        `thumbnail size ${bytes.byteLength} exceeds THUMBNAIL_MAX_BYTES (${THUMBNAIL_MAX_BYTES})`,
+      );
+    }
+    if (!isAllowedThumbnailMime(mime)) {
+      throw new Error(`thumbnail mime ${mime} not in allowlist`);
+    }
+    const hash = sha256Once(bytes);
+    const hashB64 = bytesToBase64Std(hash);
+    const engine = await this.engine();
+    // Ship the thumbnail FIRST so the receiver can present a preview the
+    // moment the main `stream-init` references it. Single lane, single
+    // chunk — at ≤ 64 KiB the parallelism overhead would dominate.
+    const handle = await engine.upload({
+      to: opts.to,
+      input: bytes,
+      lanes: 1,
+      chunkSize: Math.max(1, bytes.byteLength),
+      metadata: {
+        contentType: mime,
+        userMetadata: {
+          shadeThumbnail: '1',
+        },
+      },
+    });
+    // Don't await `done()` — the main upload should not block on the
+    // thumbnail finishing. Errors on the preview are surfaced via the
+    // returned handle's events (consumer can listen if they care).
+    handle.done().catch((err) => {
+      console.warn('[Shade] thumbnail transfer failed:', err);
+    });
+    return {
+      streamId: handle.streamId,
+      hashB64,
+      mime,
+      bytes: bytes.byteLength,
+    };
   }
 
   /**
@@ -456,6 +958,57 @@ export class Shade {
     await this.controlChannel!.acceptEnvelope(from, env);
   }
 
+  // ─── V3.11 WebRTC P2P transport ────────────────────────────
+
+  /**
+   * Opt in to direct peer-to-peer chunk delivery via WebRTC.
+   *
+   * When configured, `upload()` builds a `[WebRTC, HTTP]`
+   * {@link MultiTransportFallback}: P2P first, HTTP as automatic
+   * fallback. Signaling (SDP offer/answer + trickle-ICE) rides on top
+   * of `Shade.send` / `Shade.onMessage` — no out-of-band server needed.
+   *
+   * Must be called BEFORE the first `upload()` / `onIncomingTransfer()`
+   * (those instantiate the transfer engine, which captures the
+   * transport stack at construction time). Calling later throws.
+   *
+   * The `factory` argument is the WebRTC adapter — `nativeRtcFactory()`
+   * for browsers, a custom one for Node-class environments
+   * (`node-datachannel`, `wrtc`, etc.). Set `iceServers` to override the
+   * default public STUN list, or supply TURN credentials for paranoid
+   * NATs:
+   *
+   * ```ts
+   * import { nativeRtcFactory } from '@shade/transport-webrtc';
+   * shade.configureWebRTC({
+   *   factory: nativeRtcFactory(),
+   *   iceServers: [
+   *     { urls: 'stun:stun.l.google.com:19302' },
+   *     { urls: 'turn:turn.example.com:3478', username: 'u', credential: 'p' },
+   *   ],
+   * });
+   * ```
+   */
+  configureWebRTC(opts: ShadeWebRtcConfig): void {
+    if (this.transferEngine !== null) {
+      throw new Error(
+        'shade.configureWebRTC() must be called before upload()/onIncomingTransfer() builds the engine',
+      );
+    }
+    this.webrtcConfig = opts;
+  }
+
+  /**
+   * Returns the live WebRTC runtime (signaling channel + connection
+   * manager + transport) if `configureWebRTC` was called and `engine()`
+   * has been instantiated. Useful for diagnostics: peek
+   * `runtime.manager.isConnected('alice')` to see whether a P2P link is
+   * live, or wire `runtime.fallback.onSwitch(...)` to log demotions.
+   */
+  getWebRtcRuntime(): ShadeWebRtcRuntime | null {
+    return this.webrtcRuntime;
+  }
+
   // ─── Internals ─────────────────────────────────────────────
 
   private async engine(): Promise<TransferEngine> {
@@ -466,19 +1019,114 @@ export class Shade {
       );
     }
     this.controlChannel = new ShadeControlChannel(this, this.envelopeOutboxes);
-    const transport: ITransferTransport = new ShadeTransferHttpTransport({
+    const httpTransport: ITransferTransport = new ShadeTransferHttpTransport({
       resolveBaseUrl: this.peerBaseUrlResolver,
       authenticator: await this.makeAuthenticator(),
     });
+
+    let transport: ITransferTransport = httpTransport;
+    let webrtcRuntime: ShadeWebRtcRuntime | null = null;
+    if (this.webrtcConfig !== null) {
+      webrtcRuntime = await this.buildWebRtcRuntime(this.webrtcConfig, httpTransport);
+      transport = webrtcRuntime.fallback;
+    }
+
     this.transferEngine = new TransferEngine({
       crypto: this.crypto,
       controlChannel: this.controlChannel,
       transport,
       myAddress: this.address,
+      ...(this.config.observability !== undefined
+        ? { observability: this.config.observability }
+        : {}),
     });
+    if (webrtcRuntime !== null) {
+      // Receiver-hooks need to dispatch into the freshly-built engine.
+      webrtcRuntime.attachEngine(this.transferEngine);
+      this.webrtcRuntime = webrtcRuntime;
+    }
     return this.transferEngine;
   }
 
+  /**
+   * Dynamically import `@shade/transport-webrtc`, wire its signaling
+   * channel onto our `Shade.send`/`Shade.onMessage`, and build a
+   * MultiTransportFallback that prefers WebRTC then falls back to HTTP.
+   */
+  private async buildWebRtcRuntime(
+    cfg: ShadeWebRtcConfig,
+    httpTransport: ITransferTransport,
+  ): Promise<ShadeWebRtcRuntime> {
+    // `@shade/transport-webrtc` is an optional peer dep — keep the
+    // import lazy so consumers that don't use WebRTC don't pay for it.
+    const moduleId = '@shade/transport-webrtc';
+    const mod = (await import(moduleId)) as typeof import('@shade/transport-webrtc');
+    const {
+      WebRtcSignalingChannel,
+      WebRtcConnectionManager,
+      WebRtcTransferTransport,
+      createShadeBridgeFromShade,
+    } = mod;
+
+    const signaling = new WebRtcSignalingChannel(createShadeBridgeFromShade(this));
+    let engineRef: TransferEngine | null = null;
+    const manager = new WebRtcConnectionManager({
+      factory: cfg.factory,
+      signaling,
+      ...(cfg.iceServers !== undefined ||
+      cfg.iceTransportPolicy !== undefined ||
+      cfg.bundlePolicy !== undefined
+        ? {
+            config: {
+              ...(cfg.iceServers !== undefined ? { iceServers: cfg.iceServers } : {}),
+              ...(cfg.iceTransportPolicy !== undefined
+                ? { iceTransportPolicy: cfg.iceTransportPolicy }
+                : {}),
+              ...(cfg.bundlePolicy !== undefined ? { bundlePolicy: cfg.bundlePolicy } : {}),
+            },
+          }
+        : {}),
+      ...(cfg.connectTimeoutMs !== undefined ? { connectTimeoutMs: cfg.connectTimeoutMs } : {}),
+      receiver: {
+        onChunk: async (from, streamId, laneId, seq, envelope) => {
+          if (engineRef === null) {
+            throw new Error('webrtc receiver hook fired before engine attached');
+          }
+          return engineRef.receiveChunk(from, streamId, laneId, seq, envelope);
+        },
+        onResumeQuery: async (from, streamId) => {
+          if (engineRef === null) return null;
+          return engineRef.getResumeState(from, streamId);
+        },
+      },
+    });
+    const webrtcTransport = new WebRtcTransferTransport({
+      manager,
+      ...(cfg.requestTimeoutMs !== undefined ? { requestTimeoutMs: cfg.requestTimeoutMs } : {}),
+      ...(cfg.backpressureThresholdBytes !== undefined
+        ? { backpressureThresholdBytes: cfg.backpressureThresholdBytes }
+        : {}),
+    });
+    const fallback = new MultiTransportFallback([
+      { name: 'webrtc', transport: webrtcTransport },
+      { name: 'http', transport: httpTransport },
+    ]);
+
+    return {
+      signaling,
+      manager,
+      transport: webrtcTransport,
+      fallback,
+      attachEngine(engine) {
+        engineRef = engine;
+      },
+      destroy() {
+        manager.destroy();
+        signaling.destroy();
+      },
+    };
+  }
+
   private async makeAuthenticator(): Promise<ShadeTransferAuthenticator> {
     const identity = await this.storage.getIdentityKeyPair();
     if (identity === null) throw new Error('Identity not initialized');
@@ -503,6 +1151,21 @@ export class Shade {
     }));
   }
 
+  /**
+   * Drop persisted stream-state records whose `updatedAt` is strictly
+   * less than `olderThan` (Unix ms). Idempotent. Returns silently when
+   * the configured storage backend does not implement stream-state
+   * persistence (e.g. memory storage in tests).
+   *
+   * Recommended usage: schedule on a daily cron with a 14-day horizon
+   * — see `docs/streams.md` § Retention. The `bun-server` SDK template
+   * wires this up by default.
+   */
+  async pruneStreamStates(olderThan: number): Promise<void> {
+    if (this.storage.pruneStreamStates === undefined) return;
+    await this.storage.pruneStreamStates(olderThan);
+  }
+
   private async ensureSession(address: string): Promise<void> {
     // Deduplicate concurrent establishment requests
     const existing = this.establishing.get(address);
@@ -525,6 +1188,12 @@ export class Shade {
   }
 }
 
+function bytesToBase64Std(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  return btoa(bin);
+}
+
 function tryParseMetadata(json: string): import('@shade/streams').StreamMetadata | null {
   try {
     return JSON.parse(json) as import('@shade/streams').StreamMetadata;
@@ -533,6 +1202,42 @@ function tryParseMetadata(json: string): import('@shade/streams').StreamMetadata
   }
 }
 
+/**
+ * Best-effort plaintext-size inference for a `TransferOptions.input`.
+ * Returns null when the size is genuinely unknowable (raw `ReadableStream`
+ * without a metadata hint), so the caller can decide whether to gate.
+ */
+function inferTransferSize(opts: TransferOptions): number | null {
+  if (typeof opts.metadata?.sizeBytes === 'number') return opts.metadata.sizeBytes;
+  const input = opts.input;
+  if (input instanceof Uint8Array) return input.byteLength;
+  // Blob and File both expose `.size`. Use a structural check so we don't
+  // depend on lib.dom typings inside the SDK build.
+  if (typeof (input as unknown as { size?: unknown }).size === 'number') {
+    return (input as unknown as { size: number }).size;
+  }
+  return null;
+}
+
+/**
+ * Compute the safety-number fingerprint for the identity embedded in a
+ * decrypted backup payload. Used by `Shade.importBackup` to drive the
+ * `beforeBackupImport` gate before any state is overwritten.
+ */
+async function fingerprintFromBackupPayload(
+  crypto: SubtleCryptoProvider,
+  payload: import('./backup.js').BackupPayload,
+): Promise<string> {
+  if (payload.identity === null) {
+    // No identity in the backup means there's nothing to fingerprint.
+    // Return a stable sentinel so the gate handler can still display
+    // something meaningful instead of throwing here.
+    return 'no-identity-in-backup';
+  }
+  const id = deserializeIdentityKeyPair(payload.identity);
+  return computeFingerprint(crypto, id.signingPublicKey, id.dhPublicKey);
+}
+
 function parseChunkHeader(bytes: Uint8Array): {
   streamId: string;
   laneId: number;