5.0 KiB
OpenSpec Change: enterprise-browser-network-discovery-trystero
- Change ID: enterprise-browser-network-discovery-trystero
- Package:
@suaveplan/network-discovery-trystero - Category: browser
- Target path:
browser/network/network-discovery-trystero - Status: SUPERSEDED-BY-GENESIS-WAVE
- Date: 2026-04-24
- Reference spec:
/mnt/s/web/suaveplan/enterprise/network-discovery-trystero.md
Summary
Deliver @suaveplan/network-discovery-trystero on the genesis branch at enterprise quality. The package wraps Trystero to provide serverless WebRTC peer discovery over four transports: BitTorrent, Nostr, MQTT, and IPFS. Ships TrysteroDiscovery with strict-mode, Zod-validated messages, per-strategy OTel metrics, curated relay-pool bundles, and optional encrypted/signed announcements.
Current-state audit (genesis)
Fresh build — does not exist on genesis yet.
Available workspace deps on genesis
| Package | Role |
|---|---|
@suaveplan/network (workspace:^) |
DiscoveryStrategy interface |
@suaveplan/error (workspace:^) |
Typed Trystero errors |
@suaveplan/types (workspace:^) |
LoggerLike |
@suaveplan/crypto (workspace:^) |
Optional encrypted rooms + signed announcements |
@suaveplan/schema-registry (workspace:^) |
Message schema registration |
zod (catalog:forms) |
TrysteroMessage Zod schemas |
@opentelemetry/api (catalog:observability) |
Per-strategy health metrics |
tslib (catalog:build) |
Runtime helpers |
External: trystero (Bun catalog). React in devDeps for story.
Preserved public API surface
class TrysteroDiscovery implements DiscoveryStrategy {
constructor(config: TrysteroDiscoveryConfig)
start(): Promise<void>
stop(): Promise<void>
getPeers(): PeerInfo[]
on(event: string, handler: Function): void
}
interface TrysteroDiscoveryConfig {
strategy: TrysteroStrategy
roomId: string
torrent?: TorrentConfig
nostr?: NostrRelayConfig
mqtt?: MqttConfig
ipfs?: IpfsConfig
encrypt?: { password: string } // AES-GCM via @suaveplan/crypto
sign?: boolean // ed25519 signed announcements
strict?: boolean // Default true; rejects public defaults
}
type TrysteroStrategy = 'torrent' | 'nostr' | 'mqtt' | 'ipfs'
interface TorrentConfig { trackerUrls: string[] }
interface NostrRelayConfig { relayUrls: string[] }
interface MqttConfig { brokerUrl: string; topic?: string }
interface IpfsConfig { swarmAddrs?: string[] }
// + TrysteroConnectionStatus, TrysteroMessage, TrysteroMessageType, TrysteroPeerMetadata
New additions for genesis
1. Strict-mode relay gate
Requires explicit relay/tracker/broker per strategy; rejects known public defaults without explicit strict: false.
2. Zod-validated messages
TrysteroMessageSchema variants; validated in message-handlers.ts; malformed dropped with metric.
3. Encrypted rooms
config.encrypt.password → AES-GCM wrap via @suaveplan/crypto; messages unreadable without password.
4. Signed announcements
config.sign: true → ed25519 signatures on peer metadata via @suaveplan/crypto.
5. Curated relay-pool bundles (src/presets/)
TORRENT_TRACKERS, NOSTR_RELAYS exported with freshness metadata; no public defaults used unless opted in via presets import.
6. Fallback via @suaveplan/retry
Replace ad-hoc fallback.ts with @suaveplan/retry exponential backoff for strategy transitions.
7. Error codes
TRYSTERO_RELAY_UNREACHABLE, TRYSTERO_ROOM_JOIN_FAILED.
8. OTel metrics
Counter discovery.trystero.peers_seen_total{strategy}, counter discovery.trystero.fallback_total{from,to}, histogram discovery.trystero.join_ms{strategy}.
File layout
browser/network/network-discovery-trystero/
package.json
tsconfig.json
vitest.config.ts
src/
index.ts
error-codes.ts
trystero-discovery/
trystero-discovery.ts
trystero-discovery.md
trystero-discovery.types.ts
trystero-discovery.test.ts
index.ts
message-handlers/
message-handlers.ts
message-handlers.md
message-handlers.test.ts
index.ts
room-config/
room-config.ts
room-config.md
room-config.test.ts
index.ts
trystero-room-manager/
trystero-room-manager.ts
trystero-room-manager.md
trystero-room-manager.test.ts
index.ts
intervals/
intervals.ts
intervals.md
intervals.test.ts
index.ts
event-emitter/
event-emitter.ts
event-emitter.md
event-emitter.test.ts
index.ts
presets/
presets.ts (TORRENT_TRACKERS, NOSTR_RELAYS with freshness metadata)
presets.md
index.ts
schema/
trystero-schema/
trystero-schema.ts
trystero-schema.md
index.ts
tests/
core.test.ts
messaging.test.ts
messaging-advanced.test.ts
Impact
Downstream: @suaveplan/network-discovery-hybrid.
Prerequisites: @suaveplan/network, @suaveplan/error, @suaveplan/crypto, @suaveplan/retry on Verdaccio.