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/thumbnail.ts

@@ -0,0 +1,144 @@
+/**
+ * V3.9 — thumbnail generation helper.
+ *
+ * Browsers expose `OffscreenCanvas` (Workers + main thread) and a Blob /
+ * File API capable of decoding common image formats; we lean on those to
+ * synthesize a 256x256 preview without pulling in `sharp` or `node-canvas`.
+ *
+ * Server-side runtimes (Bun/Node) typically already have an upstream
+ * thumbnail (e.g. computed by an image-processing pipeline) — they should
+ * pass `{ thumbnail: { bytes, mime } }` to `shade.upload()` directly
+ * instead of `{ generateThumbnail: true }`. `generateThumbnail` returns
+ * `null` when no in-process generator is available, which the SDK treats
+ * as "skip the thumbnail" rather than crashing.
+ *
+ * The format-hardening invariants (`THUMBNAIL_MAX_BYTES`,
+ * `THUMBNAIL_MIME_ALLOWLIST`) are enforced *here* so we never produce
+ * something the receiver would reject.
+ */
+
+import {
+  THUMBNAIL_MAX_BYTES,
+  isAllowedThumbnailMime,
+  type ThumbnailMime,
+} from '@shade/streams';
+
+export interface GeneratedThumbnail {
+  bytes: Uint8Array;
+  mime: ThumbnailMime;
+}
+
+export interface ThumbnailGenerationOptions {
+  /** Output longest-edge in pixels (default 256). */
+  maxEdge?: number;
+  /** Preferred output MIME (default `image/webp`, falls back to `image/jpeg`). */
+  preferMime?: ThumbnailMime;
+  /** JPEG/WebP quality in [0, 1]; default 0.78. */
+  quality?: number;
+}
+
+interface BlobLike {
+  size: number;
+  readonly type: string;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+interface OffscreenCanvasCtor {
+  new (width: number, height: number): OffscreenCanvasLike;
+}
+
+interface OffscreenCanvasLike {
+  getContext(kind: '2d'): {
+    drawImage(image: unknown, dx: number, dy: number, dw: number, dh: number): void;
+  } | null;
+  convertToBlob(opts?: { type?: string; quality?: number }): Promise<BlobLike>;
+}
+
+interface CreateImageBitmapFn {
+  (source: BlobLike): Promise<{ width: number; height: number; close(): void }>;
+}
+
+function getOffscreenCanvasCtor(): OffscreenCanvasCtor | null {
+  const g = globalThis as { OffscreenCanvas?: OffscreenCanvasCtor };
+  return g.OffscreenCanvas ?? null;
+}
+
+function getCreateImageBitmap(): CreateImageBitmapFn | null {
+  const g = globalThis as { createImageBitmap?: CreateImageBitmapFn };
+  return g.createImageBitmap ?? null;
+}
+
+function isImageBlob(input: unknown): input is BlobLike {
+  if (typeof input !== 'object' || input === null) return false;
+  const b = input as BlobLike;
+  return (
+    typeof b.size === 'number' &&
+    typeof b.type === 'string' &&
+    typeof b.arrayBuffer === 'function' &&
+    b.type.startsWith('image/')
+  );
+}
+
+/**
+ * Generate a thumbnail from an image input. Returns `null` when:
+ *  - The input is not an image Blob/File.
+ *  - The runtime lacks `OffscreenCanvas` + `createImageBitmap` (Node, Deno
+ *    without polyfills). Server callers should pass `thumbnail` directly.
+ *  - The encoded thumbnail exceeds `THUMBNAIL_MAX_BYTES` even after
+ *    quality back-off (a pathological input — caller should fall back to
+ *    "no thumbnail").
+ */
+export async function generateThumbnail(
+  input: unknown,
+  opts: ThumbnailGenerationOptions = {},
+): Promise<GeneratedThumbnail | null> {
+  if (!isImageBlob(input)) return null;
+  const Ctor = getOffscreenCanvasCtor();
+  const createBitmap = getCreateImageBitmap();
+  if (Ctor === null || createBitmap === null) return null;
+
+  const maxEdge = opts.maxEdge ?? 256;
+  const preferMime = opts.preferMime ?? 'image/webp';
+  const quality = clamp01(opts.quality ?? 0.78);
+
+  const bitmap = await createBitmap(input);
+  try {
+    const scale = Math.min(1, maxEdge / Math.max(bitmap.width, bitmap.height));
+    const w = Math.max(1, Math.round(bitmap.width * scale));
+    const h = Math.max(1, Math.round(bitmap.height * scale));
+    const canvas = new Ctor(w, h);
+    const ctx = canvas.getContext('2d');
+    if (ctx === null) return null;
+    ctx.drawImage(bitmap, 0, 0, w, h);
+
+    const order: ThumbnailMime[] = preferMime === 'image/webp'
+      ? ['image/webp', 'image/jpeg']
+      : preferMime === 'image/jpeg'
+        ? ['image/jpeg', 'image/webp']
+        : ['image/png', 'image/webp', 'image/jpeg'];
+
+    for (const mime of order) {
+      let q = quality;
+      // Try up to 3 quality back-offs before giving up on this format.
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const blob = await canvas.convertToBlob({ type: mime, quality: q });
+        if (blob.size <= THUMBNAIL_MAX_BYTES) {
+          if (!isAllowedThumbnailMime(mime)) continue;
+          const buf = new Uint8Array(await blob.arrayBuffer());
+          return { bytes: buf, mime };
+        }
+        q = Math.max(0.2, q * 0.7);
+      }
+    }
+    return null;
+  } finally {
+    bitmap.close();
+  }
+}
+
+function clamp01(n: number): number {
+  if (!Number.isFinite(n)) return 0.78;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}