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-observability/tests/attributes.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  bytesBin,
+  laneCountBin,
+  peerHash,
+  safeAttribute,
+  UnsafeAttributeError,
+} from '../src/index.ts';
+
+describe('peerHash', () => {
+  test('produces stable 8-char hex', () => {
+    const a = peerHash('alice@example.com');
+    const b = peerHash('alice@example.com');
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  test('different addresses produce different hashes', () => {
+    expect(peerHash('alice@example.com')).not.toBe(peerHash('bob@example.com'));
+  });
+
+  test('never echoes the address', () => {
+    const addr = 'alice@example.com';
+    expect(peerHash(addr).includes('alice')).toBe(false);
+    expect(peerHash(addr).includes('@')).toBe(false);
+  });
+});
+
+describe('bytesBin', () => {
+  test('bins by order of magnitude', () => {
+    expect(bytesBin(0)).toBe('≤4KB');
+    expect(bytesBin(4096)).toBe('≤4KB');
+    expect(bytesBin(4097)).toBe('4–64KB');
+    expect(bytesBin(64 * 1024)).toBe('4–64KB');
+    expect(bytesBin(64 * 1024 + 1)).toBe('64KB–1MB');
+    expect(bytesBin(1024 * 1024)).toBe('64KB–1MB');
+    expect(bytesBin(10 * 1024 * 1024)).toBe('1–10MB');
+    expect(bytesBin(100 * 1024 * 1024)).toBe('10–100MB');
+    expect(bytesBin(1024 * 1024 * 1024)).toBe('100MB–1GB');
+    expect(bytesBin(2 * 1024 * 1024 * 1024)).toBe('≥1GB');
+  });
+
+  test('handles invalid input', () => {
+    expect(bytesBin(-1)).toBe('unknown');
+    expect(bytesBin(NaN)).toBe('unknown');
+    expect(bytesBin(Infinity)).toBe('unknown');
+  });
+});
+
+describe('laneCountBin', () => {
+  test('snaps to {1, 4, 16, 64}', () => {
+    expect(laneCountBin(1)).toBe(1);
+    expect(laneCountBin(2)).toBe(4);
+    expect(laneCountBin(4)).toBe(4);
+    expect(laneCountBin(5)).toBe(16);
+    expect(laneCountBin(16)).toBe(16);
+    expect(laneCountBin(32)).toBe(64);
+    expect(laneCountBin(128)).toBe(64);
+  });
+});
+
+describe('safeAttribute', () => {
+  test('rejects PII-flavoured keys', () => {
+    expect(() => safeAttribute('shade.peer.address', 'x')).toThrow(UnsafeAttributeError);
+    expect(() => safeAttribute('shade.bytes.exact', 1)).toThrow(UnsafeAttributeError);
+    expect(() => safeAttribute('shade.plaintext', 'x')).toThrow(UnsafeAttributeError);
+  });
+
+  test('rejects address-like values', () => {
+    expect(() => safeAttribute('custom.tag', 'alice@example.com')).toThrow(UnsafeAttributeError);
+    expect(() => safeAttribute('custom.tag', 'device:abc-123')).toThrow(UnsafeAttributeError);
+    expect(() => safeAttribute('custom.tag', 'did:web:example.com')).toThrow(UnsafeAttributeError);
+  });
+
+  test('rejects oversized strings', () => {
+    expect(() => safeAttribute('ok', 'x'.repeat(257))).toThrow(UnsafeAttributeError);
+  });
+
+  test('accepts safe values', () => {
+    expect(safeAttribute('shade.bytes.bin', '4–64KB')).toEqual({
+      key: 'shade.bytes.bin',
+      value: '4–64KB',
+    });
+    expect(safeAttribute('shade.lane.count', 4)).toEqual({ key: 'shade.lane.count', value: 4 });
+    expect(safeAttribute('shade.retry.count', 0)).toEqual({ key: 'shade.retry.count', value: 0 });
+    expect(safeAttribute('shade.error.code', 'SHADE_TIMEOUT')).toEqual({
+      key: 'shade.error.code',
+      value: 'SHADE_TIMEOUT',
+    });
+    // hashes pass through
+    expect(safeAttribute('shade.peer.hash', 'abcdef01')).toEqual({
+      key: 'shade.peer.hash',
+      value: 'abcdef01',
+    });
+  });
+});

packages/shade-observability/tests/integration-pii.test.ts

@@ -0,0 +1,104 @@
+/**
+ * End-to-end PII guard test.
+ *
+ * Exercises real Shade entry points (session encrypt/decrypt, transfer
+ * upload + receive, prekey HTTP routes, files RPC) with a recorder hook
+ * and asserts that NONE of the recorded span attributes echo the
+ * sensitive plaintext we deliberately fed in (peer address, message
+ * content, exact byte counts).
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { ShadeSessionManager, type StorageProvider } from '@shade/core';
+import { MemoryStorage, SubtleCryptoProvider } from '@shade/crypto-web';
+import { createRecorder } from '../src/index.ts';
+import { createPrekeyRoutes, MemoryPrekeyStore } from '@shade/server';
+
+const DANGER_FRAGMENTS = [
+  // Peer addresses we feed into APIs:
+  'alice@danger.test',
+  'bob@danger.test',
+  'device:hot-secret-12345',
+  // Plaintext message bodies:
+  'sekret-payload-XYZ',
+  'CLASSIFIED-7777',
+  // Exact byte counts that we'd never want leaked:
+  '1048577',
+];
+
+describe('observability — PII guard for ShadeSessionManager', () => {
+  test('encrypt/decrypt spans never echo address or plaintext', async () => {
+    const rec = createRecorder();
+    const crypto = new SubtleCryptoProvider();
+
+    const aliceStorage: StorageProvider = new MemoryStorage();
+    const bobStorage: StorageProvider = new MemoryStorage();
+    const alice = new ShadeSessionManager(crypto, aliceStorage, { observability: rec });
+    const bob = new ShadeSessionManager(crypto, bobStorage, { observability: rec });
+    await alice.initialize();
+    await bob.initialize();
+
+    // Alice -> Bob handshake (X3DH)
+    const bobBundle = await bob.createPreKeyBundle();
+    await alice.initSessionFromBundle('bob@danger.test', bobBundle);
+
+    const env1 = await alice.encrypt('bob@danger.test', 'sekret-payload-XYZ');
+    await bob.decrypt('alice@danger.test', env1);
+
+    // Round-trip a second time so a steady-state ratchet step also runs.
+    const env2 = await bob.encrypt('alice@danger.test', 'CLASSIFIED-7777');
+    await alice.decrypt('bob@danger.test', env2);
+
+    expect(rec.spans.length).toBeGreaterThan(0);
+    const hits = rec.scanForPII(DANGER_FRAGMENTS);
+    if (hits.length > 0) {
+      throw new Error(`PII leak in spans: ${JSON.stringify(hits, null, 2)}`);
+    }
+  });
+});
+
+describe('observability — PII guard for prekey routes', () => {
+  let port: number;
+  let server: ReturnType<typeof Bun.serve>;
+  let rec: ReturnType<typeof createRecorder>;
+
+  beforeAll(async () => {
+    rec = createRecorder();
+    const crypto = new SubtleCryptoProvider();
+    const store = new MemoryPrekeyStore();
+    const app = createPrekeyRoutes(store, crypto, {
+      observability: rec,
+      disableRateLimit: true,
+    });
+    server = Bun.serve({
+      fetch: app.fetch,
+      port: 0,
+    });
+    port = (server as unknown as { port: number }).port;
+  });
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  test('GET /v1/keys/bundle/<address> never logs the address verbatim', async () => {
+    const addr = 'device:hot-secret-12345';
+    // Anonymous fetch — bundle endpoint will 404 since we never registered,
+    // but the route still emits a span with the route template (not the
+    // raw address path).
+    await fetch(`http://localhost:${port}/v1/keys/bundle/${encodeURIComponent(addr)}`);
+    expect(rec.spans.length).toBeGreaterThan(0);
+    const hits = rec.scanForPII([addr, 'hot-secret']);
+    if (hits.length > 0) {
+      throw new Error(`PII leak in prekey-route spans: ${JSON.stringify(hits, null, 2)}`);
+    }
+    // The span name should reference the route TEMPLATE, not the raw path.
+    const seenRoutes = rec.spans.flatMap((s) => {
+      const r = s.attributes['shade.route'];
+      return typeof r === 'string' ? [r] : [];
+    });
+    // Route should be `/v1/keys/bundle/:address` (or empty if Hono didn't
+    // resolve it; what we MUST NOT see is the literal device:... value).
+    for (const r of seenRoutes) {
+      expect(r.includes('hot-secret')).toBe(false);
+    }
+  });
+});

packages/shade-observability/tests/recorder.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { createRecorder } from '../src/index.ts';
+
+describe('createRecorder', () => {
+  test('captures attributes and end-state', () => {
+    const rec = createRecorder();
+    const span = rec.startSpan('shade.test', { initial: 'on' });
+    span.setAttribute('extra', 1);
+    span.setAttributes({ batch1: 'a', batch2: 'b' });
+    span.setStatus('ok');
+    span.end();
+    expect(rec.spans).toHaveLength(1);
+    const s = rec.spans[0]!;
+    expect(s.name).toBe('shade.test');
+    expect(s.attributes).toEqual({ initial: 'on', extra: 1, batch1: 'a', batch2: 'b' });
+    expect(s.status).toBe('ok');
+    expect(s.ended).toBe(true);
+  });
+
+  test('records exceptions', () => {
+    const rec = createRecorder();
+    const span = rec.startSpan('shade.test');
+    const err = new Error('boom');
+    span.recordException(err);
+    span.setStatus('error', 'boom');
+    span.end();
+    expect(rec.spans[0]?.exceptions).toEqual([err]);
+    expect(rec.spans[0]?.status).toBe('error');
+    expect(rec.spans[0]?.statusMessage).toBe('boom');
+  });
+
+  test('scanForPII catches forbidden substrings', () => {
+    const rec = createRecorder();
+    const safe = rec.startSpan('shade.upload', { 'shade.peer.hash': 'abc12345' });
+    safe.end();
+    const leaky = rec.startSpan('shade.upload', { 'shade.peer.address': 'alice@example.com' });
+    leaky.end();
+    const hits = rec.scanForPII(['@', 'alice', 'peer.address']);
+    expect(hits.length).toBeGreaterThan(0);
+    // The safe span should not be in the hits.
+    const safeHit = hits.find((h) => h.spanName === 'shade.upload' && h.value === 'abc12345');
+    expect(safeHit).toBeUndefined();
+  });
+
+  test('clear() drops the buffer', () => {
+    const rec = createRecorder();
+    rec.startSpan('a').end();
+    expect(rec.spans).toHaveLength(1);
+    rec.clear();
+    expect(rec.spans).toHaveLength(0);
+  });
+});

packages/shade-observability/tests/with-tracer.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { NOOP_HOOK, withTracer, type OtelTracerLike } from '../src/index.ts';
+
+interface RecordedSpan {
+  name: string;
+  attrs: Record<string, unknown>;
+  ended: boolean;
+}
+
+function makeFakeTracer(): { tracer: OtelTracerLike; spans: RecordedSpan[] } {
+  const spans: RecordedSpan[] = [];
+  const tracer: OtelTracerLike = {
+    startSpan(name, options) {
+      const rec: RecordedSpan = {
+        name,
+        attrs: { ...(options?.attributes ?? {}) },
+        ended: false,
+      };
+      spans.push(rec);
+      return {
+        setAttribute(k, v) {
+          rec.attrs[k] = v;
+          return undefined;
+        },
+        end() {
+          rec.ended = true;
+          return undefined;
+        },
+      };
+    },
+  };
+  return { tracer, spans };
+}
+
+describe('withTracer (off-by-default)', () => {
+  beforeEach(() => {
+    delete (globalThis as unknown as { process?: { env?: Record<string, string | undefined> } }).process?.env?.SHADE_OTEL_ENABLED;
+  });
+
+  test('returns NOOP_HOOK when tracer is undefined', () => {
+    const hook = withTracer(undefined);
+    expect(hook).toBe(NOOP_HOOK);
+  });
+
+  test('returns NOOP_HOOK when env-var is not set (default)', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer);
+    const span = hook.startSpan('shade.test');
+    span.setAttribute('foo', 'bar');
+    span.end();
+    expect(spans.length).toBe(0); // never reached the OTel tracer
+  });
+
+  test('force=true bypasses the env gate', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer, { force: true });
+    hook.startSpan('shade.test', { foo: 'bar' }).end();
+    expect(spans.length).toBe(1);
+    expect(spans[0]?.name).toBe('shade.test');
+    expect(spans[0]?.attrs.foo).toBe('bar');
+    expect(spans[0]?.ended).toBe(true);
+  });
+});
+
+describe('withTracer (env-enabled)', () => {
+  beforeEach(() => {
+    process.env.SHADE_OTEL_ENABLED = '1';
+  });
+  afterEach(() => {
+    delete process.env.SHADE_OTEL_ENABLED;
+  });
+
+  test('emits spans through the tracer when env is set', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer);
+    const span = hook.startSpan('shade.upload', { 'shade.bytes.bin': '1–10MB' });
+    span.setAttribute('shade.result', 'ok');
+    span.setStatus('ok');
+    span.end();
+    expect(spans.length).toBe(1);
+    expect(spans[0]?.name).toBe('shade.upload');
+    expect(spans[0]?.attrs['shade.bytes.bin']).toBe('1–10MB');
+    expect(spans[0]?.attrs['shade.result']).toBe('ok');
+    expect(spans[0]?.ended).toBe(true);
+  });
+
+  test('respects per-span sampling', () => {
+    const { tracer, spans } = makeFakeTracer();
+    let n = 0;
+    const random = () => {
+      // Alternates: 0.1 (sampled in), 0.9 (sampled out)
+      const v = n % 2 === 0 ? 0.1 : 0.9;
+      n++;
+      return v;
+    };
+    const hook = withTracer(tracer, { sample: 0.5, random });
+    for (let i = 0; i < 10; i++) hook.startSpan(`s${i}`).end();
+    // Half (5 of 10) should reach the OTel tracer.
+    expect(spans.length).toBe(5);
+  });
+
+  test('sample=0 means no spans even when env is on', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer, { sample: 0 });
+    hook.startSpan('shade.test').end();
+    expect(spans.length).toBe(0);
+  });
+
+  test('end() is idempotent', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer);
+    const span = hook.startSpan('shade.test');
+    span.end();
+    span.end();
+    expect(spans.length).toBe(1);
+    expect(spans[0]?.ended).toBe(true);
+  });
+
+  test('attribute mutations after end() are no-op', () => {
+    const { tracer, spans } = makeFakeTracer();
+    const hook = withTracer(tracer);
+    const span = hook.startSpan('shade.test', { a: 1 });
+    span.end();
+    span.setAttribute('after_end', 'oops');
+    expect(spans[0]?.attrs.after_end).toBeUndefined();
+  });
+});