@vgai/p2p-colyseus 0.5.2 → 0.5.3

package/src/cloudflare/coordinator.ts

@@ -18,51 +18,62 @@ interface RateWindow {
   count: number;
 }
 
-interface IpHashQuotaRecord {
+interface PrincipalQuotaRecord {
   hostedRoomIds: Set<string>;
   relayRoomIds: Set<string>;
   relayBytesByDay: Map<string, number>;
 }
 
+/**
+ * Quota store keyed by a neutral `principal` (an account id, or — as dormant
+ * scaffolding — an ip hash). The relay's durable per-account byte allotment
+ * lives in Durable Object storage (see `durable-room.ts`); this in-memory store
+ * backs the coordinator's per-principal concurrent-room and per-day byte caps.
+ */
 export interface RelayQuotaStore {
-  reserveHostedRoom(ipHash: string, roomId: string, maxRooms: number): boolean;
-  reserveRelayRoom(ipHash: string, roomId: string, maxRooms: number): boolean;
-  consumeRelayBytes(ipHash: string, dayKey: string, bytes: number, maxBytesPerDay: number): boolean;
+  reserveHostedRoom(principal: string, roomId: string, maxRooms: number): boolean;
+  reserveRelayRoom(principal: string, roomId: string, maxRooms: number): boolean;
+  consumeRelayBytes(
+    principal: string,
+    dayKey: string,
+    bytes: number,
+    maxBytesPerDay: number,
+  ): boolean;
 }
 
 export class InMemoryRelayQuotaStore implements RelayQuotaStore {
-  private readonly records = new Map<string, IpHashQuotaRecord>();
+  private readonly records = new Map<string, PrincipalQuotaRecord>();
 
-  reserveHostedRoom(ipHash: string, roomId: string, maxRooms: number): boolean {
-    const record = this.recordFor(ipHash);
+  reserveHostedRoom(principal: string, roomId: string, maxRooms: number): boolean {
+    const record = this.recordFor(principal);
     record.hostedRoomIds.add(roomId);
     return record.hostedRoomIds.size <= maxRooms;
   }
 
-  reserveRelayRoom(ipHash: string, roomId: string, maxRooms: number): boolean {
-    const record = this.recordFor(ipHash);
+  reserveRelayRoom(principal: string, roomId: string, maxRooms: number): boolean {
+    const record = this.recordFor(principal);
     record.relayRoomIds.add(roomId);
     return record.relayRoomIds.size <= maxRooms;
   }
 
   consumeRelayBytes(
-    ipHash: string,
+    principal: string,
     dayKey: string,
     bytes: number,
     maxBytesPerDay: number,
   ): boolean {
-    const record = this.recordFor(ipHash);
+    const record = this.recordFor(principal);
     const next = (record.relayBytesByDay.get(dayKey) ?? 0) + bytes;
     if (next > maxBytesPerDay) return false;
     record.relayBytesByDay.set(dayKey, next);
     return true;
   }
 
-  private recordFor(ipHash: string): IpHashQuotaRecord {
-    let record = this.records.get(ipHash);
+  private recordFor(principal: string): PrincipalQuotaRecord {
+    let record = this.records.get(principal);
     if (!record) {
       record = { hostedRoomIds: new Set(), relayRoomIds: new Set(), relayBytesByDay: new Map() };
-      this.records.set(ipHash, record);
+      this.records.set(principal, record);
     }
     return record;
   }
@@ -94,15 +105,24 @@ export class SignalingRelayCoordinator {
     private readonly logger?: RelayLogger | undefined,
   ) {}
 
-  registerHost(roomName: string, hostSignalId = 'host', ipHash?: string): SignalEnvelope {
+  /**
+   * The room name bound at host-register (empty until a host registers). The
+   * POST relay-data biller verifies each managed access token against it, so a
+   * token minted for a different room can never meter bytes here.
+   */
+  get boundRoomName(): string {
+    return this.roomName;
+  }
+
+  registerHost(roomName: string, hostSignalId = 'host', principal?: string): SignalEnvelope {
     const rateLimit = this.consumeSignal(hostSignalId);
     if (rateLimit) return rateLimit;
     const now = this.now();
     this.roomId = crypto.randomUUID?.() ?? `room-${Date.now()}`;
     if (
-      ipHash &&
+      principal &&
       !this.quotaStore.reserveHostedRoom(
-        ipHash,
+        principal,
         this.roomId,
         this.limits.maxConcurrentHostedRoomsPerIpHash,
       )

package/src/cloudflare/durable-room.ts

@@ -1,6 +1,7 @@
-import { verifyP2PAccessToken } from '../access-token';
+import { readP2PAccessToken } from '../access-token';
 import { isEnvelope, P2P_CLOSE_CODES } from '../protocol';
 import { SignalingRelayCoordinator } from './coordinator';
+import { DEFAULT_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY } from './limits';
 import type { SignalEnvelope } from './protocol';
 
 interface CloudflareWebSocket extends WebSocket {
@@ -25,11 +26,25 @@ interface DurableRoomEnv {
   P2P_COLYSEUS_MAX_GLOBAL_WEBSOCKET_MESSAGES_PER_DAY?: string | undefined;
   P2P_COLYSEUS_MAX_ACTIVE_RELAY_SOCKETS?: string | undefined;
   P2P_COLYSEUS_ACCESS_TOKEN_SECRET?: string | undefined;
+  P2P_COLYSEUS_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY?: string | undefined;
+  P2P_COLYSEUS_REQUIRE_ACCOUNT?: string | undefined;
 }
 
 export class P2PColyseusDurableRoom {
   private readonly coordinator = new SignalingRelayCoordinator();
   private readonly sockets = new Map<string, CloudflareWebSocket>();
+  /**
+   * peerId → metering principal, learned when a peer authenticates at
+   * host-register / join. The WebSocket relay-data path binds this principal
+   * ONCE at accept time — and under enforcement `acceptWebSocket` REFUSES a
+   * peerId absent from this map, so the bind is always a verified userId, never
+   * an ip-hash fallback. The POST relay-data path uses it only when
+   * account enforcement is OFF (self-host / BYOK); under enforcement that path
+   * ignores this map entirely and meters against the `userId` carried on the
+   * frame's own verified `accessToken` (see `meterPostRelayData`), so a
+   * spoofable per-message `from` is never authoritative for billing.
+   */
+  private readonly peerPrincipals = new Map<string, string>();
 
   constructor(
     private readonly state?: DurableObjectStateLike,
@@ -84,27 +99,29 @@ export class P2PColyseusDurableRoom {
     envelope: SignalEnvelope & { from?: string | undefined; ipHash?: string | undefined },
   ): Promise<unknown> {
     if (envelope.kind === 'host-register') {
-      const authError = await this.verifyAccess(
+      const auth = await this.authorize(
         envelope.accessToken,
         envelope.roomName,
         envelope.from,
-      );
-      if (authError) return authError;
-      return this.coordinator.registerHost(
-        envelope.roomName,
-        envelope.from ?? 'host',
         envelope.ipHash,
       );
+      if (auth.error) return auth.error;
+      const hostId = envelope.from ?? 'host';
+      this.rememberPrincipal(hostId, auth.principal);
+      return this.coordinator.registerHost(envelope.roomName, hostId, envelope.ipHash);
     }
 
     if (envelope.kind === 'join-request') {
-      const authError = await this.verifyAccess(
+      const auth = await this.authorize(
         envelope.accessToken,
         envelope.roomName,
         envelope.from,
+        envelope.ipHash,
       );
-      if (authError) return authError;
-      return this.coordinator.join(envelope.roomName, envelope.from ?? 'client');
+      if (auth.error) return auth.error;
+      const clientId = envelope.from ?? 'client';
+      this.rememberPrincipal(clientId, auth.principal);
+      return this.coordinator.join(envelope.roomName, clientId);
     }
 
     if (
@@ -114,11 +131,7 @@ export class P2PColyseusDurableRoom {
       envelope.kind === 'relay-open' ||
       envelope.kind === 'relay-data'
     ) {
-      if (envelope.kind === 'relay-data') {
-        const budgetResult = await this.consumeGlobalRelayBudget(byteLength(envelope));
-        if (budgetResult) return budgetResult;
-      }
-      return this.coordinator.forward(envelope) ?? { kind: 'ok' };
+      return this.forwardSignal(envelope);
     }
 
     if (envelope.kind === 'relay-drain') {
@@ -147,6 +160,23 @@ export class P2PColyseusDurableRoom {
       return json({ kind: 'error', message: 'Missing peerId, targetPeerId, or roomId' }, 400);
     }
 
+    // Under account enforcement the relay-data WebSocket is reachable ONLY by a peer that
+    // already authenticated at host-register/join (both token-gated by authorize()). That
+    // handshake is what binds peerId → verified userId in peerPrincipals. An unauthenticated
+    // peerId has no userId to meter against, so principalForPeer would fall back to ip-hash —
+    // the exact tokenless bypass the POST relay-data path forbids (meterPostRelayData →
+    // authenticatedRelayPrincipal). Refuse the upgrade so both relay-data transports gate
+    // identically. Self-host (REQUIRE_ACCOUNT off) is unchanged: no principal is required.
+    const remembered = this.peerPrincipals.get(peerId);
+    if (getRequireAccount(this.env) && remembered === undefined) {
+      return json({ kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) }, 401);
+    }
+
+    const principal = this.principalForPeer(
+      peerId,
+      request.headers.get('x-p2p-ip-hash') ?? undefined,
+    );
+
     const pair = newWebSocketPair();
     const client = pair[0];
     const server = pair[1];
@@ -156,40 +186,133 @@ export class P2PColyseusDurableRoom {
     this.sockets.set(peerId, server);
     server.addEventListener('message', async (event) => {
       if (typeof event.data !== 'string') return;
-      const messageBudgetResult = await this.consumeDailyCounter(
-        'relay-global-websocket-messages',
-        1,
-        getMaxGlobalWebSocketMessagesPerDay(this.env),
-      );
-      if (messageBudgetResult) {
-        server.send(JSON.stringify(messageBudgetResult));
-        server.close(Number(messageBudgetResult.message), messageBudgetResult.message);
-        return;
-      }
-      const envelope = JSON.parse(event.data) as unknown;
-      const signalEnvelope: SignalEnvelope & { target: string; from: string } = {
-        kind: 'relay-data',
+      const outcome = await this.meterRelaySocketMessage(
+        principal,
         roomId,
-        target: targetPeerId,
-        from: peerId,
-        envelope: envelope as never,
-      };
-      const budgetResult = await this.consumeGlobalRelayBudget(byteLength(signalEnvelope));
-      const result = budgetResult ?? this.coordinator.forward(signalEnvelope);
-      if (result?.kind === 'error') {
-        server.send(JSON.stringify(result));
-        server.close(Number(result.message), result.message);
+        peerId,
+        targetPeerId,
+        event.data,
+      );
+      if (outcome.kind === 'error') {
+        server.send(JSON.stringify(outcome.error));
+        server.close(Number(outcome.error.message), outcome.error.message);
         return;
       }
-      this.sockets.get(targetPeerId)?.send(JSON.stringify(envelope));
+      this.sockets.get(targetPeerId)?.send(JSON.stringify(outcome.payload));
     });
     server.addEventListener('close', () => {
       this.sockets.delete(peerId);
+      this.peerPrincipals.delete(peerId);
     });
 
     return new Response(null, { status: 101, webSocket: client } as ResponseInit);
   }
 
+  /**
+   * Meter a single WebSocket relay-data frame: global WS-message count, global
+   * relay bytes, then the SAME per-account daily byte counter the POST relay
+   * path uses. This is the exact body the accepted socket's `message` listener
+   * runs; it is a named method so the WebSocket byte path is unit-testable
+   * without constructing a status-101 `Response` (which the test runtime
+   * rejects).
+   */
+  private async meterRelaySocketMessage(
+    principal: string | undefined,
+    roomId: string,
+    peerId: string,
+    targetPeerId: string,
+    rawData: string,
+  ): Promise<
+    { kind: 'error'; error: ErrorSignalEnvelope } | { kind: 'forward'; payload: unknown }
+  > {
+    const messageBudget = await this.consumeDailyCounter(
+      'relay-global-websocket-messages',
+      1,
+      getMaxGlobalWebSocketMessagesPerDay(this.env),
+    );
+    if (messageBudget) return { kind: 'error', error: messageBudget };
+    const inner = JSON.parse(rawData) as unknown;
+    const signalEnvelope: SignalEnvelope & { target: string; from: string } = {
+      kind: 'relay-data',
+      roomId,
+      target: targetPeerId,
+      from: peerId,
+      envelope: inner as never,
+    };
+    const bytes = byteLength(signalEnvelope);
+    const globalBudget = await this.consumeGlobalRelayBudget(bytes);
+    if (globalBudget) return { kind: 'error', error: globalBudget };
+    const accountBudget = await this.consumeAccountRelayBytes(principal, bytes);
+    if (accountBudget) return { kind: 'error', error: accountBudget };
+    const forwardResult = this.coordinator.forward(signalEnvelope);
+    if (forwardResult?.kind === 'error') return { kind: 'error', error: forwardResult };
+    return { kind: 'forward', payload: inner };
+  }
+
+  private async forwardSignal(
+    envelope: SignalEnvelope & { from?: string | undefined; ipHash?: string | undefined },
+  ): Promise<unknown> {
+    if (envelope.kind === 'relay-data') {
+      const budgetResult = await this.meterPostRelayData(envelope);
+      if (budgetResult) return budgetResult;
+    }
+    return this.coordinator.forward(envelope) ?? { kind: 'ok' };
+  }
+
+  /**
+   * Meter a POST relay-data frame: global relay bytes, then the per-account
+   * daily allotment (the same counter the WebSocket path decrements).
+   *
+   * Under `P2P_COLYSEUS_REQUIRE_ACCOUNT`, the metering principal is the
+   * `userId` recovered from the frame's own verified `accessToken` — NEVER the
+   * client-supplied `envelope.from`, which is spoofable. Because a peer cannot
+   * mint a token bearing another account's `userId`, this makes it IMPOSSIBLE
+   * for peer A's traffic to drain peer B's allotment: `from` is never
+   * authoritative for billing, so spoofing it changes nothing. A missing or
+   * invalid token, or one carrying no `userId`, is refused (`unauthorized`).
+   *
+   * With enforcement OFF (self-host / BYOK) today's allow-when-unset metering
+   * is preserved byte-for-byte: no token is required, and the principal falls
+   * back to the join-time remembered principal (or ip hash) via
+   * {@link principalForPeer}.
+   */
+  private async meterPostRelayData(
+    envelope: Extract<SignalEnvelope, { kind: 'relay-data' }> & { ipHash?: string | undefined },
+  ): Promise<ErrorSignalEnvelope | null> {
+    let principal: string | undefined;
+    if (getRequireAccount(this.env)) {
+      const auth = await this.authenticatedRelayPrincipal(envelope.accessToken);
+      if (auth.error) return auth.error;
+      principal = auth.principal;
+    } else {
+      principal = this.principalForPeer(envelope.from, envelope.ipHash);
+    }
+    const bytes = byteLength(envelope);
+    const globalBudget = await this.consumeGlobalRelayBudget(bytes);
+    if (globalBudget) return globalBudget;
+    return this.consumeAccountRelayBytes(principal, bytes);
+  }
+
+  /**
+   * Resolve the billing principal for a POST relay-data frame under account
+   * enforcement from the frame's OWN token. The token is verified against this
+   * room's bound name and must carry a `userId`; the principal is that `userId`
+   * and nothing else. `envelope.from` is deliberately not consulted — the token
+   * is the only trustworthy sender identity, and binding to it (rather than to
+   * a per-request `from`) is what makes cross-account draining impossible.
+   */
+  private async authenticatedRelayPrincipal(
+    token: string | undefined,
+  ): Promise<{ error?: ErrorSignalEnvelope; principal?: string }> {
+    const secret = this.env.P2P_COLYSEUS_ACCESS_TOKEN_SECRET;
+    if (!secret || !token) return { error: unauthorized() };
+    const claims = await readP2PAccessToken(secret, token, {
+      roomName: this.coordinator.boundRoomName,
+    });
+    if (!claims?.userId) return { error: unauthorized() };
+    return { principal: claims.userId };
+  }
+
   private async consumeGlobalRelayBudget(bytes: number): Promise<ErrorSignalEnvelope | null> {
     return this.consumeDailyCounter(
       'relay-global-bytes',
@@ -261,19 +384,80 @@ export class P2PColyseusDurableRoom {
     };
   }
 
-  private async verifyAccess(
+  /**
+   * Verify a peer's access token when one is PRESENT and resolve its metering
+   * principal. This mirrors {@link meterPostRelayData}'s soft-mode model so that
+   * merely SETTING `P2P_COLYSEUS_ACCESS_TOKEN_SECRET` is non-breaking: a missing
+   * token is ALLOWED while `P2P_COLYSEUS_REQUIRE_ACCOUNT` is off, even with the
+   * secret set (the principal falls back to the ip hash — self-host / BYOK). A
+   * token that IS supplied is still verified against the secret and rejected if
+   * invalid. Only flipping `REQUIRE_ACCOUNT` on makes a token-carried `userId`
+   * mandatory — so setting the secret alone changes nothing until that flip.
+   */
+  private async authorize(
     token: string | undefined,
     roomName: string,
     peerId: string | undefined,
-  ): Promise<ErrorSignalEnvelope | null> {
+    ipHash: string | undefined,
+  ): Promise<{ error?: ErrorSignalEnvelope; principal?: string | undefined }> {
     const secret = this.env.P2P_COLYSEUS_ACCESS_TOKEN_SECRET;
-    if (!secret) return null;
-    if (!token) return { kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) };
-    const verified = await verifyP2PAccessToken(secret, token, { roomName, peerId });
-    return verified ? null : { kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) };
+    let userId: string | undefined;
+    if (secret && token) {
+      const claims = await readP2PAccessToken(secret, token, { roomName, peerId });
+      if (!claims) return { error: unauthorized() };
+      userId = claims.userId;
+    }
+    if (getRequireAccount(this.env) && !userId) return { error: unauthorized() };
+    return { principal: userId ?? ipHash };
+  }
+
+  private rememberPrincipal(peerId: string, principal: string | undefined): void {
+    if (principal !== undefined) this.peerPrincipals.set(peerId, principal);
+  }
+
+  private principalForPeer(
+    peerId: string | undefined,
+    ipHash: string | undefined,
+  ): string | undefined {
+    const remembered = peerId ? this.peerPrincipals.get(peerId) : undefined;
+    return remembered ?? ipHash;
+  }
+
+  private async consumeAccountRelayBytes(
+    principal: string | undefined,
+    bytes: number,
+  ): Promise<ErrorSignalEnvelope | null> {
+    if (!principal) return null;
+    return this.consumeDailyCounter(
+      `relay-account-bytes:${principal}`,
+      bytes,
+      getFreeRelayBytesPerAccountPerDay(this.env),
+    );
   }
 }
 
+function unauthorized(): ErrorSignalEnvelope {
+  return { kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) };
+}
+
+export function getFreeRelayBytesPerAccountPerDay(env: DurableRoomEnv = {}): number {
+  return Math.floor(
+    parsePositiveNumber(env.P2P_COLYSEUS_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY) ??
+      DEFAULT_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY,
+  );
+}
+
+// Accept every plausible truthy spelling (case-insensitive), not just '1'/'true'. This is a
+// ONE-WAY security flip: if an operator sets it to a value the reader silently ignored (e.g.
+// `on`, `yes`), enforcement would stay OFF while they believed the room was closed — the worst
+// possible failure for an access gate. Erring toward "enabled" for any clear affirmative
+// removes that footgun. Only an explicit falsy/absent value leaves enforcement off.
+const REQUIRE_ACCOUNT_TRUTHY = new Set(['1', 'true', 'on', 'yes', 'enabled']);
+export function getRequireAccount(env: DurableRoomEnv = {}): boolean {
+  const value = env.P2P_COLYSEUS_REQUIRE_ACCOUNT;
+  return typeof value === 'string' && REQUIRE_ACCOUNT_TRUTHY.has(value.trim().toLowerCase());
+}
+
 export function getDailyGlobalRelayBytes(env: DurableRoomEnv = {}): number {
   const explicit = parsePositiveNumber(env.P2P_COLYSEUS_RELAY_MAX_GLOBAL_BYTES_PER_DAY);
   if (explicit !== undefined) return Math.floor(explicit);

package/src/cloudflare/limits.ts

@@ -20,3 +20,10 @@ export const DEFAULT_RELAY_LIMITS = {
 export type RelayLimits = {
   readonly [K in keyof typeof DEFAULT_RELAY_LIMITS]: number;
 };
+
+/**
+ * Free relay bytes an account may spend per day on the managed lane. Same
+ * 500 MiB shape as `maxRelayBytesPerIpHashPerDay`; overridable at deploy time
+ * via `P2P_COLYSEUS_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY`.
+ */
+export const DEFAULT_FREE_RELAY_BYTES_PER_ACCOUNT_PER_DAY = 500 * 1024 * 1024;

package/src/cloudflare/protocol.ts

@@ -67,6 +67,12 @@ export type SignalEnvelope =
       readonly target: string;
       readonly from?: string | undefined;
       readonly ipHash?: string | undefined;
+      // The session's managed access token, attached by the forced-relay client
+      // transports (`HttpRelayPacketChannel`/`HostRelayPacketChannel`). It is the
+      // ONLY trustworthy sender identity a POST relay-data frame carries, so
+      // under account enforcement the relay meters bytes against its verified
+      // `userId` — never the spoofable `from`. Absent for self-host / BYOK.
+      readonly accessToken?: string | undefined;
       readonly envelope: Envelope;
     }
   | { readonly kind: 'relay-drain'; readonly peerId: string }

package/src/engine.ts

@@ -4,7 +4,7 @@ import type { SignalEnvelope } from './cloudflare/protocol';
 import { createLoopbackPair } from './loopback';
 import type { Envelope } from './protocol';
 import { type RoomClass, UniversalRoomRuntime } from './runtime';
-import { WebRTCDataChannelPacketChannel } from './webrtc';
+import { WEBRTC_UNRELIABLE_CHANNEL_LABEL, WebRTCDataChannelPacketChannel } from './webrtc';
 
 const HOST_LOSS_CLOSE_DELAY_MS = 1_000;
 
@@ -134,6 +134,7 @@ export async function connectP2PHostRoom(
     iceServers: mode.iceServers,
     forceRelay: mode.forceRelay === true,
     heartbeatIntervalMs: mode.heartbeatIntervalMs,
+    accessToken: mode.accessToken,
   });
   const originalLeave = localRoom.leave.bind(localRoom);
   localRoom.leave = async (consented = true) => {
@@ -166,6 +167,15 @@ export async function connectP2PJoinRoom(
 
   const peer = new RTCPeerConnection({ iceServers: mode.iceServers });
   const dataChannel = peer.createDataChannel('p2p-colyseus');
+  // Second channel for `sendUnreliable`: unordered, no retransmits. Created
+  // alongside the reliable one so both are negotiated in the single
+  // offer/answer round-trip; we only WAIT on the reliable channel to open
+  // (below), and `WebRTCDataChannelPacketChannel` falls back to it if this one
+  // is not open yet.
+  const unreliableChannel = peer.createDataChannel(WEBRTC_UNRELIABLE_CHANNEL_LABEL, {
+    ordered: false,
+    maxRetransmits: 0,
+  });
   const pendingCandidates: RTCIceCandidateInit[] = [];
   peer.onicecandidate = (event) => {
     if (!event.candidate) return;
@@ -212,7 +222,7 @@ export async function connectP2PJoinRoom(
   }
 
   const room = await connectRoomOverChannel(
-    new WebRTCDataChannelPacketChannel(joined.hostSignalId, dataChannel),
+    new WebRTCDataChannelPacketChannel(joined.hostSignalId, dataChannel, unreliableChannel),
     opts.room,
     opts.joinOptions,
   );
@@ -234,6 +244,7 @@ async function connectP2PJoinRelayRoom(
       peerId: clientSignalId,
       signalPeerId: clientSignalId,
       targetPeerId: joined.hostSignalId,
+      accessToken: mode.accessToken,
     }),
     opts.room,
     opts.joinOptions,
@@ -251,6 +262,7 @@ function startHostSignalLoop(options: {
   iceServers: RTCIceServer[];
   forceRelay: boolean;
   heartbeatIntervalMs?: number | undefined;
+  accessToken?: string | undefined;
 }): () => void {
   let stopped = false;
   const heartbeatInterval = setInterval(() => {
@@ -263,6 +275,12 @@ function startHostSignalLoop(options: {
   }, options.heartbeatIntervalMs ?? 5_000);
   const peers = new Map<string, RTCPeerConnection>();
   const pending = new Map<string, RTCIceCandidateInit[]>();
+  // Per-peer reliable WebRTC channel, plus any unreliable sub-channel whose
+  // `ondatachannel` arrived before its reliable sibling. The two channels a
+  // client offers surface as TWO `ondatachannel` events; we fold them into one
+  // `WebRTCDataChannelPacketChannel`, tolerant of either arrival order.
+  const webrtcChannels = new Map<string, WebRTCDataChannelPacketChannel>();
+  const pendingUnreliable = new Map<string, RTCDataChannel>();
   const attachedChannels = new Set<{
     send(envelope: Envelope): void;
     close(reason?: string): void;
@@ -277,6 +295,7 @@ function startHostSignalLoop(options: {
         peerId: target,
         signalPeerId: options.hostSignalId,
         targetPeerId: target,
+        accessToken: options.accessToken,
       });
       relayChannels.set(target, channel);
       attachedChannels.add(channel);
@@ -303,7 +322,19 @@ function startHostSignalLoop(options: {
           const peer = new RTCPeerConnection({ iceServers: options.iceServers });
           peers.set(target, peer);
           peer.ondatachannel = (event) => {
+            if (event.channel.label === WEBRTC_UNRELIABLE_CHANNEL_LABEL) {
+              const existing = webrtcChannels.get(target);
+              if (existing) existing.attachUnreliableChannel(event.channel);
+              else pendingUnreliable.set(target, event.channel);
+              return;
+            }
             const channel = new WebRTCDataChannelPacketChannel(target, event.channel);
+            const unreliable = pendingUnreliable.get(target);
+            if (unreliable) {
+              channel.attachUnreliableChannel(unreliable);
+              pendingUnreliable.delete(target);
+            }
+            webrtcChannels.set(target, channel);
             attachedChannels.add(channel);
             options.runtime.attach(channel);
           };
@@ -382,7 +413,12 @@ function closePeerAfterHostLoss(peer: RTCPeerConnection): void {
 }
 
 function adaptCompatRoom(room: CompatRoom, roomId?: string): EngineNetTransport {
-  const sourceReplication = Callbacks.get(room);
+  // The engine transport is string-keyed and STABLE; bridge the real
+  // `@colyseus/schema` string-keyed callbacks strategy (over the client's real
+  // decoder) to it. `onStateChange` is not a callbacks-strategy method — it is
+  // the room's own signal, emitted after each decode.
+  // biome-ignore lint/suspicious/noExplicitAny: bridging the generic Callbacks strategy to the string-keyed engine interface.
+  const $ = room.decoder ? (Callbacks.get(room.decoder) as any) : undefined;
   const transport: EngineNetTransport = {
     get sessionId() {
       return room.sessionId;
@@ -390,16 +426,23 @@ function adaptCompatRoom(room: CompatRoom, roomId?: string): EngineNetTransport
     roomId,
     replication: {
       onAdd(collection, handler) {
-        return sourceReplication.onAdd(collection, (item, key) => handler(item as never, key));
+        if (!$) return () => undefined;
+        return $.onAdd(collection, (item: unknown, key: unknown) =>
+          handler(item as never, String(key)),
+        );
       },
       onRemove(collection, handler) {
-        return sourceReplication.onRemove(collection, (item, key) => handler(item as never, key));
+        if (!$) return () => undefined;
+        return $.onRemove(collection, (item: unknown, key: unknown) =>
+          handler(item as never, String(key)),
+        );
       },
       onChange(item, handler) {
-        return sourceReplication.onChange(item, handler);
+        if (!$) return () => undefined;
+        return $.onChange(item, handler);
       },
       onStateChange(handler) {
-        return sourceReplication.onStateChange((state) => handler(state as never));
+        return room.onStateChange.add((state) => handler(state as never));
       },
     },
     send(type, payload) {
@@ -433,6 +476,7 @@ class HttpRelayPacketChannel {
       peerId: string;
       signalPeerId: string;
       targetPeerId: string;
+      accessToken?: string | undefined;
     },
   ) {
     void this.poll();
@@ -467,6 +511,9 @@ class HttpRelayPacketChannel {
       roomId: this.options.roomId,
       target: this.options.targetPeerId,
       from: this.options.signalPeerId,
+      // Attach the managed token so the relay can meter these bytes against the
+      // authenticated account under enforcement; omitted for self-host / BYOK.
+      ...(this.options.accessToken ? { accessToken: this.options.accessToken } : {}),
       envelope,
     });
     if (result.kind === 'error') throw new Error(result.message);
@@ -516,6 +563,7 @@ class HostRelayPacketChannel {
       peerId: string;
       signalPeerId: string;
       targetPeerId: string;
+      accessToken?: string | undefined;
     },
   ) {}
 
@@ -553,6 +601,9 @@ class HostRelayPacketChannel {
       roomId: this.options.roomId,
       target: this.options.targetPeerId,
       from: this.options.signalPeerId,
+      // Attach the managed token so the relay can meter these bytes against the
+      // authenticated account under enforcement; omitted for self-host / BYOK.
+      ...(this.options.accessToken ? { accessToken: this.options.accessToken } : {}),
       envelope,
     });
     if (result.kind === 'error') throw new Error(result.message);