Shade/docs/transport.md

Shade Transport — Bridge Layer (V3.7)

Looking for V3.11 (peer-to-peer chunk transport via RTCDataChannel)? See docs/webrtc.md. This page covers the V3.7 bridge layer that ships ciphertext envelopes (control plane) over WS / SSE / long-poll. The two are orthogonal: the bridge handles store-and-forward control envelopes; WebRTC handles direct chunk data.

The bridge layer is the answer to: "my client is a browser extension / strict-corp-proxy / edge-runtime / iOS app — I cannot keep a WebSocket open. How do I receive ciphertext envelopes?"

It is built on top of the V3.6 inbox: every transport delivers the same inbox blobs, with the same authentication semantics. Application code sees a single IncomingMessage shape and never branches on transport.

┌─────────────────────────────────────────────────────────────────┐
│                       application code                          │
│                                                                 │
│   bridge.connect({ onMessage: (m) => decrypt(m.bytes) })        │
└────────────────────────────────┬────────────────────────────────┘
                                 │
       ┌─────────────────────────┴──────────────────────────┐
       │              FallbackBridgeTransport               │
       │             (sticky-after-first-success)           │
       └──┬──────────────────┬─────────────────────────┬────┘
          │                  │                         │
   ┌──────▼─────┐     ┌──────▼─────┐            ┌──────▼─────┐
   │  WsBridge  │     │  SseBridge │            │ LongPoll   │
   │  /v1/      │     │  /v1/      │            │ Bridge     │
   │  bridge/ws │     │  bridge/   │            │ /v1/bridge │
   │            │     │  stream    │            │ /poll      │
   └──────┬─────┘     └──────┬─────┘            └──────┬─────┘
          │                  │                         │
          └──────────────────┼─────────────────────────┘
                             │
                       ┌─────▼──────┐
                       │  inbox     │  ← the same V3.6 store
                       │  blobs     │     and events
                       └────────────┘

When to reach for which

Transport	Latency	Proxy resilience	Browser	Server cost
WebSocket	ms	breaks under strict CONNECT-blocking proxies	✓	one socket per client
SSE	ms	passes most HTTP proxies (text/event-stream)	✓	one streamed response per client
long-poll	≤ 25 s	passes anything that allows GET	✓	one held request per client

The recommended composition:

import {
  FallbackBridgeTransport,
  WsBridge,
  SseBridge,
  LongPollBridge,
} from '@shade/transport-bridge';

const auth = {
  crypto,                   // CryptoProvider
  signingPrivateKey,        // recipient's Ed25519 private key
  address: 'bob',
};

const bridge = new FallbackBridgeTransport([
  new WsBridge({       baseUrl: 'https://relay.example.com', auth }),
  new SseBridge({      baseUrl: 'https://relay.example.com', auth }),
  new LongPollBridge({ baseUrl: 'https://relay.example.com', auth }),
]);

await bridge.connect({
  onMessage: async (msg) => {
    // msg.bytes is a Uint8Array — pass it to your decrypt path.
    // msg.from is the relay-known sender hint (may be empty); the
    // authoritative sender comes from the decrypted envelope.
    // msg.msgId is the relay's deterministic message id (sha256(ciphertext)).
    const envelope = decodeEnvelope(msg.bytes);
    await shade.receive(senderAddress, envelope);
  },
});

// Read which transport the fallback chain settled on:
console.log(bridge.activeKind); // "ws" | "sse" | "long-poll"

The IncomingMessage shape

interface IncomingMessage {
  from: string;          // relay-side sender hint (may be "")
  bytes: Uint8Array;     // the ciphertext envelope, exactly as PUT
  receivedAt: number;    // relay-monotonic cursor — NOT wall-clock arrival
  msgId?: string;        // sha256(bytes) — useful for ack/dedup
}

from is intentionally a hint — sender provenance lives inside the encrypted envelope and is recovered post-decrypt. The bridge layer is plaintext-blind by design.

Auth — signed query parameters

Every bridge request signs the canonical {address, kind, since, signedAt} payload with the recipient's Ed25519 signing private key. The server looks up the address-owner key registered via /v1/inbox/register and verifies the signature.

kind is bound into the canonical payload so a signature for /poll cannot be replayed against /stream or /ws.

The browser EventSource API does not let callers attach custom headers; query parameters are the only portable carrier and so the bridge protocol uses them uniformly across all three transports.

Server-side — createBridgeRoutes

import { createBridgeRoutes } from '@shade/inbox-server';
import { Hono } from 'hono';

const inbox = new MemoryInboxStore();
const events = new InboxServerEvents();

const bridge = createBridgeRoutes({
  store: inbox,
  crypto,
  events,
  longPollTimeoutMs: 25_000,        // default — under typical proxy idle limits
  heartbeatIntervalMs: 15_000,      // SSE keepalive comments
  fallbackPollIntervalMs: 1_000,    // when no `events` emitter is wired
});

const app = new Hono();
app.route('/', bridge.app);

Bun.serve({
  port: 3900,
  fetch: (req, srv) => app.fetch(req, srv),
  websocket: bridge.websocket as any,
});

The bridge subscribes to InboxServerEvents (inbox.blob_stored) for push-style delivery — when an event fires for a connected address, the server fetches new blobs and forwards them. If no events emitter is wired, the server falls back to a small in-process polling timer at fallbackPollIntervalMs cadence.

Cursor & resume

Every IncomingMessage.receivedAt is the relay's monotonic cursor for the address. Bridges expose getCursor() so applications can persist the high-water mark and pass it as startCursor on the next connect():

const sse = new SseBridge({
  baseUrl,
  auth,
  startCursor: await persistedCursor.load(),
});

await sse.connect({
  onMessage: async (msg) => {
    await persistedCursor.save(msg.receivedAt);
    // …
  },
});

For SSE specifically, the server emits an id: field per event; the bridge sends it back as Last-Event-ID plus the since= query parameter on reconnect, so a flapping connection picks up exactly where it left off without duplicates.

Reconnect & backoff

Bridge	Auto-reconnect	Backoff
WS	yes (default)	250 ms → 10 s exponential
SSE	yes (default)	250 ms → 10 s exponential
long-poll	always on (the loop is the reconnect)	2 s on hard error

Pass disableAutoReconnect: true (WS / SSE) for tests where you want a single attempt and immediate surfaced error.

Long-poll concurrency

The LongPollBridge issues exactly one request at a time. The next request fires after the previous one resolves. This guarantees a client never holds more than one TCP connection on the server, which matches the V3.7 acceptance criterion and keeps capacity planning simple: max in-flight long-poll requests = number of connected clients.

Failure modes

• WS handshake rejected (4xxx code). WsBridge.connect rejects. Caller (or FallbackBridgeTransport) moves on.
• SSE returns non-200. SseBridge.connect throws a BridgeError with httpStatus.
• Long-poll returns non-200. Same — BridgeError with httpStatus.
• Mid-stream error after connect. WS/SSE auto-reconnect; long-poll swallows transient errors and continues looping. Errors flow to the caller's onError handler.

Acceptance test coverage (V3.7)

packages/shade-transport-bridge/tests/bridge.test.ts covers:

• "Send 100 small messages" — one test per transport, all pass.
• "WS blocked by proxy → SSE → long-poll" — fallback test boots a server where the WS endpoint is unreachable and the SSE endpoint returns 502, verifies the chain falls all the way through to long-poll without message loss.
• "Long-poll uses ≤ 1 outstanding request" — wraps fetch to count in-flight requests over 1.5 s of steady-state operation.
• Cursor resume — tears down an SSE connection mid-stream, pushes more blobs, reconnects with the persisted cursor, asserts exactly the new blobs are delivered (no overlap with the pre-disconnect set).
• Auth rejection — wrong signing key and unregistered address both produce hard connect rejections so the fallback chain advances.