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-key-transparency/src/sth.ts

@@ -0,0 +1,120 @@
+/**
+ * Signed Tree Head (STH) — server's commitment to a tree state.
+ *
+ * canonical layout for signing:
+ *   0x02 (DOMAIN_STH) ||
+ *   uint64_be tree_size ||
+ *   uint64_be timestamp_ms ||
+ *   root_hash  (32 bytes) ||
+ *   index_root (32 bytes) ||
+ *   log_id     (32 bytes)
+ *
+ * `log_id` is `SHA-256(log_public_key)` — a stable identifier that
+ * doesn't change unless the operator rotates the signing key.
+ */
+
+import type { CryptoProvider } from '@shade/core';
+import { DOMAIN_STH } from './hashes.js';
+import { sha256Sync } from './sha256.js';
+import { constantTimeEqual } from './util.js';
+
+export interface SignedTreeHead {
+  treeSize: number;
+  timestampMs: number;
+  rootHash: Uint8Array;
+  indexRoot: Uint8Array;
+  logId: Uint8Array;
+  signature: Uint8Array;
+}
+
+/** Compute log_id = SHA-256(public_key). */
+export function computeLogId(logPublicKey: Uint8Array): Uint8Array {
+  return sha256Sync(logPublicKey);
+}
+
+/** Canonical bytes covered by the STH signature. */
+export function canonicalSthBytes(sth: Omit<SignedTreeHead, 'signature'>): Uint8Array {
+  if (sth.rootHash.length !== 32) throw new Error('rootHash must be 32 bytes');
+  if (sth.indexRoot.length !== 32) throw new Error('indexRoot must be 32 bytes');
+  if (sth.logId.length !== 32) throw new Error('logId must be 32 bytes');
+  if (sth.treeSize < 0 || !Number.isFinite(sth.treeSize)) {
+    throw new Error('treeSize must be a non-negative integer');
+  }
+
+  const buf = new Uint8Array(1 + 8 + 8 + 32 + 32 + 32);
+  const view = new DataView(buf.buffer);
+  let off = 0;
+  buf[off++] = DOMAIN_STH;
+  view.setUint32(off, Math.floor(sth.treeSize / 0x100000000));
+  view.setUint32(off + 4, sth.treeSize >>> 0);
+  off += 8;
+  view.setUint32(off, Math.floor(sth.timestampMs / 0x100000000));
+  view.setUint32(off + 4, sth.timestampMs >>> 0);
+  off += 8;
+  buf.set(sth.rootHash, off);
+  off += 32;
+  buf.set(sth.indexRoot, off);
+  off += 32;
+  buf.set(sth.logId, off);
+  return buf;
+}
+
+/** Sign an STH with the operator's Ed25519 signing key. */
+export async function signSth(
+  crypto: CryptoProvider,
+  signingPrivateKey: Uint8Array,
+  sth: Omit<SignedTreeHead, 'signature'>,
+): Promise<SignedTreeHead> {
+  const message = canonicalSthBytes(sth);
+  const signature = await crypto.sign(signingPrivateKey, message);
+  return { ...sth, signature };
+}
+
+/**
+ * Verify the STH signature against a pinned `logPublicKey`.
+ *
+ * Also checks `logId === SHA-256(logPublicKey)` so a forged STH that
+ * claims a different log_id is rejected.
+ */
+export async function verifySthSignature(
+  crypto: CryptoProvider,
+  sth: SignedTreeHead,
+  logPublicKey: Uint8Array,
+): Promise<boolean> {
+  const expectedLogId = computeLogId(logPublicKey);
+  if (!constantTimeEqual(expectedLogId, sth.logId)) return false;
+  const message = canonicalSthBytes(sth);
+  return crypto.verify(logPublicKey, message, sth.signature);
+}
+
+/** JSON-friendly STH for the wire (base64-encoded byte fields). */
+export interface STHWire {
+  treeSize: number;
+  timestampMs: number;
+  rootHash: string;
+  indexRoot: string;
+  logId: string;
+  signature: string;
+}
+
+export function sthToWire(sth: SignedTreeHead, b64: (b: Uint8Array) => string): STHWire {
+  return {
+    treeSize: sth.treeSize,
+    timestampMs: sth.timestampMs,
+    rootHash: b64(sth.rootHash),
+    indexRoot: b64(sth.indexRoot),
+    logId: b64(sth.logId),
+    signature: b64(sth.signature),
+  };
+}
+
+export function sthFromWire(wire: STHWire, fromB64: (s: string) => Uint8Array): SignedTreeHead {
+  return {
+    treeSize: wire.treeSize,
+    timestampMs: wire.timestampMs,
+    rootHash: fromB64(wire.rootHash),
+    indexRoot: fromB64(wire.indexRoot),
+    logId: fromB64(wire.logId),
+    signature: fromB64(wire.signature),
+  };
+}