feat(observer): M-Obs 1-3 — event bus, server hooks, observer backend

M-Obs 1: Event bus in @shade/core
- ShadeEventEmitter with typed event union, ring buffer for replay
- 12 event types covering session lifecycle, ratchet operations,
  prekey changes, identity rotation, trust changes
- Wired into ShadeSessionManager (zero overhead when not enabled)
- shortHash helper for safe display of public keys
- Security test: regex-checks event payloads contain no key material

M-Obs 2: Prekey server event hooks
- PrekeyServerEvents emitter mirroring core's pattern
- 5 server event types: registered, fetched, replenished, deleted, rate_limited
- Wired into all routes including the rate-limit error handler
- shortHash helper using crypto.subtle directly (no provider dep)

M-Obs 3: @shade/observer package
- StateAggregator subscribes to client + server events, builds rolling snapshot
- Hono routes: GET /api/state (snapshot), GET /api/events (SSE stream)
- Bearer token auth via SHADE_OBSERVER_TOKEN, query string for SSE
- Refuses to start with token < 16 chars (ConfigurationError)
- Static file serving for bundled dashboard at /dashboard/
- Placeholder dashboard renders when no built SPA present

220 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shade-core/src/events.ts

@@ -0,0 +1,130 @@
+import type { CryptoProvider } from './crypto.js';
+
+/**
+ * Shade event bus.
+ *
+ * Emits structural events for observability — NEVER plaintext, private keys,
+ * nonces, or other secret material. Identity references are SHA-256 truncated
+ * to 8 bytes (16 hex chars) for display only.
+ *
+ * Optional: pass a ShadeEventEmitter to ShadeSessionManager to enable.
+ * If not passed, all emits are no-ops with zero overhead.
+ */
+
+// ─── Event payload types ──────────────────────────────────────
+
+export interface ShadeEventBase {
+  /** Monotonic sequence number assigned at emit time */
+  seq: number;
+  /** Wall-clock timestamp in milliseconds */
+  timestamp: number;
+}
+
+/** Map of event names to their payload shape (without seq/timestamp) */
+export interface ShadeEventMap {
+  'identity.initialized': { fingerprint: string; registrationId: number };
+  'identity.rotated': { newFingerprint: string };
+  'session.created': { address: string; remoteIdentityKeyHash: string };
+  'session.removed': { address: string };
+  'message.encrypted': { address: string; counter: number; ciphertextSize: number };
+  'message.decrypted': { address: string; counter: number; plaintextSize: number };
+  'ratchet.dh_step': { address: string };
+  'prekey.generated': { count: number; totalAfter: number };
+  'prekey.consumed': { keyId: number };
+  'signed_prekey.rotated': { oldKeyId: number; newKeyId: number };
+  'trust.pinned': { address: string; identityKeyHash: string };
+  'trust.changed': { address: string; oldKeyHash: string; newKeyHash: string };
+}
+
+export type ShadeEventName = keyof ShadeEventMap;
+
+export type ShadeEvent = {
+  [K in ShadeEventName]: ShadeEventBase & { name: K; data: ShadeEventMap[K] };
+}[ShadeEventName];
+
+export type ShadeEventListener = (event: ShadeEvent) => void;
+
+// ─── EventEmitter implementation ─────────────────────────────
+
+/**
+ * Minimal typed event emitter for Shade observability.
+ *
+ * Supports subscribe (`on`), unsubscribe (`off`), and replay buffer
+ * for late subscribers.
+ */
+export class ShadeEventEmitter {
+  private listeners = new Set<ShadeEventListener>();
+  private nextSeq = 1;
+  private buffer: ShadeEvent[] = [];
+  private readonly maxBuffer: number;
+
+  constructor(options: { bufferSize?: number } = {}) {
+    this.maxBuffer = options.bufferSize ?? 1000;
+  }
+
+  /** Subscribe to all events. Returns an unsubscribe function. */
+  on(listener: ShadeEventListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  off(listener: ShadeEventListener): void {
+    this.listeners.delete(listener);
+  }
+
+  /** Emit a typed event. Adds seq + timestamp automatically. */
+  emit<K extends ShadeEventName>(name: K, data: ShadeEventMap[K]): void {
+    const event = {
+      seq: this.nextSeq++,
+      timestamp: Date.now(),
+      name,
+      data,
+    } as ShadeEvent;
+
+    // Add to ring buffer
+    this.buffer.push(event);
+    if (this.buffer.length > this.maxBuffer) {
+      this.buffer.shift();
+    }
+
+    // Notify listeners (catching throws so one bad listener doesn't break others)
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error('[Shade] Event listener threw:', err);
+      }
+    }
+  }
+
+  /** Get all buffered events with seq > since (for SSE replay/reconnect) */
+  getBufferedSince(since: number): ShadeEvent[] {
+    return this.buffer.filter((e) => e.seq > since);
+  }
+
+  /** Get the most recent N events */
+  getRecent(n: number): ShadeEvent[] {
+    return this.buffer.slice(-n);
+  }
+
+  /** Current sequence number (next event will use this + 1) */
+  get currentSeq(): number {
+    return this.nextSeq - 1;
+  }
+}
+
+// ─── Hash helper for safe display ────────────────────────────
+
+/**
+ * Compute a short, display-safe hash of a public key.
+ * Uses HKDF-SHA256 (since CryptoProvider has it) to produce 8 bytes,
+ * then formats as 16 hex characters.
+ *
+ * NEVER use this for security decisions — it's lossy and only for UI display.
+ */
+export async function shortHash(crypto: CryptoProvider, key: Uint8Array): Promise<string> {
+  const salt = new Uint8Array(32);
+  const info = new TextEncoder().encode('ShadeShortHash');
+  const hash = await crypto.hkdf(key, salt, info, 8);
+  return Array.from(hash, (b) => b.toString(16).padStart(2, '0')).join('');
+}