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