# 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

```ts
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

```text
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.