# OpenSpec Change: enterprise-browser-drive-webrtc - **Change ID**: enterprise-browser-drive-webrtc - **Package**: `@suaveplan/drive-webrtc` - **Category**: browser - **Target path**: `packages/drive/drive-webrtc` - **Status**: IN PROGRESS - **Date**: 2026-04-24 - **Reference spec**: `/mnt/s/web/suaveplan/enterprise/drive-webrtc.md` --- ## Summary Deliver `@suaveplan/drive-webrtc` on the genesis branch from scratch at enterprise quality. The package provides a WebRTC peer-to-peer mesh plugin for `@suaveplan/drive`, shipping the full pipeline to distribute content chunks browser-to-browser: `WebRTCClient` (signalling + RTC lifecycle), `SignalingClient` (WebSocket transport), `PeerManager` + `PeerBandwidthTracker`, `DataChannelManager`, `ChunkDiscoveryManager` + `WebRTCChunkSource`, `SubChunkSplitter` / `SubChunkReassembler`, `ChunkIntegrityManager` (hash verify + **real** signature verification via `@suaveplan/crypto`), `LRUCache`, `RateLimiter`, and `WebRTCDrivePlugin`. No `vi.stubGlobal` — WebSocket/RTC paths exercised via Playwright. --- ## Current-state audit (genesis) The package does not exist on genesis yet — fresh build. --- ## Available workspace deps on genesis | Package | Role | |---|---| | `@suaveplan/drive` (`workspace:^`) | `DrivePlugin` interface, `ChunkSource` contract | | `@suaveplan/crypto` (`workspace:^`) | `crypto.subtle`-based chunk signature verification | | `@suaveplan/events` (`workspace:^`) | `TypedEventEmitter` for peer/chunk events | | `@suaveplan/error` (`workspace:^`) | Typed errors for signalling, peer handshake, chunk integrity | | `@suaveplan/types` (`workspace:^`) | `LoggerLike` | | `@suaveplan/packer` (`workspace:^`) | Chunk format / packing helpers | | `@suaveplan/schema-registry` (`workspace:^`) | Register signalling Zod schemas | | `zod` (`catalog:forms`) | Schemas for `SignalingMessage` family, `WebRTCPluginConfig` | | `@opentelemetry/api` (`catalog:observability`) | Peer/chunk metrics | | `tslib` (`catalog:build`) | Runtime helpers | No external runtime deps — uses only native Web APIs. Dev deps: `vitest`, `@vitest/coverage-istanbul`, `@playwright/test` (`catalog:testing`), `@suaveplan/testing workspace:^`. --- ## Preserved public API surface (from main branch) All eleven subpath exports preserved: - `WebRTCChunkSource` + `ChunkSourceOptions` - `WebRTCClient` + `WebRTCClientOptions` + `resolveConfig` - `DataChannelManager` - `ChunkDiscoveryManager` - `TypedEventEmitter` - `ChunkIntegrityManager` + `computeChunkHash` + `verifyChunkIntegrity` + `ChunkMetadata` - `LRUCache` + `LRUCacheOptions` - `PeerBandwidthTracker` + config/metrics types - `PeerManager` - `WebRTCDrivePlugin` - `RateLimiter` + `RateLimiterOptions` - Plus: `generateSecurePeerId`, `generateSecureRequestId`, `validatePeerSecurity`, `validateSignalingUrl`, `SignalingClient`, `SubChunkReassembler`, `sendSubChunks`, `splitIntoSubChunks`, `encodeToBase64`, `decodeFromBase64`, all config/event/message/peer/stats types --- ## New additions for genesis ### 1. Real chunk signature verification `ChunkIntegrityManager.verifySignature(chunk, key)` implemented using `crypto.subtle.verify` + `@suaveplan/crypto` — no "forward-looking placeholder" wording anywhere. ### 2. Structured errors via `@suaveplan/error` Error codes: `SIGNALING_UNREACHABLE`, `PEER_HANDSHAKE_FAILED`, `CHUNK_INTEGRITY_FAILED`, `ICE_FAILED`, `PEER_BANDWIDTH_EXCEEDED`, `RATE_LIMIT_EXCEEDED`. ### 3. ICE-restart policy `WebRTCClient` detects `iceConnectionState === 'failed'` and triggers ICE restart; surfaces via typed `'ice:restart'` event. ### 4. TURN / STUN configuration First-class `iceServers` config in `WebRTCClientOptions` with Zod validation; documented ops guide for `turn://user:cred@host:port?transport=udp|tcp`. ### 5. OTel metrics Counters `drive.webrtc.peers_connected_total`, `drive.webrtc.chunks_served_total`, `drive.webrtc.chunks_rejected_total{reason}`; histograms `drive.webrtc.peer_rtt_ms`, `drive.webrtc.chunk_transfer_ms`, `drive.webrtc.signaling_reconnect_ms`. ### 6. Signalling Zod schemas `SignalingMessageSchema` family (offer/answer/ICE/chunk-request/chunk-response) registered in `@suaveplan/schema-registry`. ### 7. Topology strategies `TopologyStrategy` interface with `FullMesh`, `SuperPeer`, and `HubAndSpoke` implementations in `src/peer-manager/topology/`. ### 8. Per-subpath bundle-size snapshots Eleven snapshot tests asserting tree-shake isolation across all entry points. --- ## File layout ```text packages/drive/drive-webrtc/ package.json tsconfig.json vitest.config.ts src/ index.ts error-codes.ts client/ client/ client.ts client.md client.test.ts index.ts offer-answer/ offer-answer.ts offer-answer.md offer-answer.test.ts index.ts ice/ ice.ts ice.md ice.test.ts index.ts reconnect/ reconnect.ts reconnect.md reconnect.test.ts index.ts signaling/ signaling-client/ signaling-client.ts signaling-client.md signaling-client.test.ts index.ts data-channel/ data-channel-manager/ data-channel-manager.ts data-channel-manager.md data-channel-manager.test.ts index.ts discovery/ chunk-discovery-manager/ chunk-discovery-manager.ts chunk-discovery-manager.md chunk-discovery-manager.test.ts index.ts chunk-source/ chunk-source/ chunk-source.ts chunk-source.md chunk-source.test.ts index.ts integrity/ chunk-integrity/ chunk-integrity.ts (includes real signature verification) chunk-integrity.md chunk-integrity.types.ts chunk-integrity.test.ts index.ts peer-manager/ peer-manager/ peer-manager.ts peer-manager.md peer-manager.test.ts index.ts peer-bandwidth-tracker/ peer-bandwidth-tracker.ts peer-bandwidth-tracker.md peer-bandwidth-tracker.test.ts index.ts topology/ topology-strategy.ts full-mesh.ts super-peer.ts hub-and-spoke.ts plugin/ webrtc-plugin/ webrtc-plugin.ts webrtc-plugin.md webrtc-plugin.test.ts index.ts sub-chunk/ sub-chunk/ sub-chunk-splitter.ts sub-chunk-reassembler.ts sub-chunk.md sub-chunk.test.ts index.ts lru-cache/ lru-cache/ lru-cache.ts lru-cache.md lru-cache.test.ts index.ts rate-limiter/ rate-limiter/ rate-limiter.ts rate-limiter.md rate-limiter.test.ts index.ts security/ security-validator/ security-validator.ts security-validator.md security-validator.test.ts index.ts events/ typed-event-emitter/ typed-event-emitter.ts typed-event-emitter.md typed-event-emitter.test.ts index.ts types/ (config, events, messages, peer, stats, drive type modules) tests/ integration.test.ts bundle-size/ (eleven snapshot tests) e2e/ drive-webrtc.spec.ts (two browsers, signalling, ICE, data-channel, chunk exchange) ``` --- ## Impact **Downstream**: `@suaveplan/drive`, real-time P2P content distribution. **Prerequisites**: `@suaveplan/drive`, `@suaveplan/crypto`, `@suaveplan/events`, `@suaveplan/packer`, `@suaveplan/error` on Verdaccio.