@fieldnotes/sync-server 0.17.1 → 0.19.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { CanvasElement, ServiceKey } from '@fieldnotes/core';
-import { SyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
+import { ServiceKey, ElementRegistry } from '@fieldnotes/core';
+import { WireSyncElement, WireSyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
 export { PluginSnapshot } from '@fieldnotes/sync';
 import { WebSocketServer } from 'ws';
 import { IncomingMessage, Server } from 'http';
@@ -18,24 +18,21 @@ declare class InMemoryHubFanout implements HubFanout {
 interface HubBackend {
     /** True when every hub instance addresses the same atomic backing state (for example Redis). */
     readonly sharedAcrossInstances?: boolean;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords?(room: string): Promise<LayerRecord[]>;
     getLayerRecord?(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord?(room: string, record: LayerRecord): Promise<void>;
     getService?<T>(key: ServiceKey<T>): T | undefined;
 }
 
-type OwnedElement = CanvasElement & {
-    ownerId?: string;
-    audience?: string;
-};
+type OwnedElement = WireSyncElement;
 interface AuthorizeContext {
     userId?: string;
     role?: string;
     room: string;
-    op: SyncOp;
+    op: WireSyncOp;
     currentElement?: OwnedElement;
 }
 type Authorize = (ctx: AuthorizeContext) => boolean | Promise<boolean>;
@@ -43,7 +40,7 @@ interface AuthorizeLayerContext {
     userId?: string;
     role?: string;
     room: string;
-    op: Extract<SyncOp, {
+    op: Extract<WireSyncOp, {
         kind: 'layer-upsert' | 'layer-remove';
     }>;
     /** The hub's current record for the target layer, tombstones included. */
@@ -63,11 +60,39 @@ interface ReadContext {
     audience: string | undefined;
 }
 type CanRead = (ctx: ReadContext) => boolean;
+interface OwnerReadContext {
+    userId?: string;
+    role?: string;
+    room: string;
+}
+/**
+ * Decides whether a viewer may see the server-stamped `ownerId` on elements it
+ * receives (live ops, snapshots and corrections). Without a hook `ownerId` is
+ * stripped from every outbound frame; it stays in the backend for `authorize`.
+ */
+type CanReadOwnerId = (ctx: OwnerReadContext) => boolean;
+interface ResolveAudienceContext {
+    userId?: string;
+    role?: string;
+    room: string;
+    /** The incoming element as the client sent it, client-asserted `audience` included. */
+    element: WireSyncElement;
+    /** The hub's stored element for the same id, if any. */
+    currentElement?: OwnedElement;
+}
+/**
+ * Decides the authoritative `audience` of an upserted element. The returned
+ * value replaces whatever the client asserted (`undefined` clears the field)
+ * before `authorize`, storage and relay, so a client can neither hide content
+ * by tagging it nor reveal content by retagging it. Without a hook the
+ * client's tag passes through and `authorize` must check it.
+ */
+type ResolveAudience = (ctx: ResolveAudienceContext) => string | undefined;
 
 interface ApplyResult {
-    readonly accepted: SyncOp | null;
-    readonly corrections: SyncOp[];
-    readonly broadcast?: SyncOp[];
+    readonly accepted: WireSyncOp | null;
+    readonly corrections: WireSyncOp[];
+    readonly broadcast?: WireSyncOp[];
     readonly locality?: 'shared' | 'local';
 }
 interface ServerOpContext {
@@ -78,7 +103,7 @@ interface ServerOpContext {
     readonly backend: HubBackend;
     backendPlugin<T>(key: ServiceKey<T>): T | undefined;
 }
-type ServerNext = (op: SyncOp, context: ServerOpContext) => Promise<ApplyResult>;
+type ServerNext = (op: WireSyncOp, context: ServerOpContext) => Promise<ApplyResult>;
 interface ServerExtensionRegistry {
     register<TPayload>(kind: ExtensionKind<TPayload>, handler: (op: TypedExtensionOp<TPayload>, context: ServerOpContext) => Promise<ApplyResult>): void;
 }
@@ -86,8 +111,8 @@ interface ServerSyncPlugin {
     readonly name: string;
     readonly ownedLegacyKinds?: readonly string[];
     readonly legacySnapshotKey?: string;
-    process?(op: SyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
-    applyFanout?(op: SyncOp, context: ServerOpContext): Promise<SyncOp | null>;
+    process?(op: WireSyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
+    applyFanout?(op: WireSyncOp, context: ServerOpContext): Promise<WireSyncOp | null>;
     registerExtensionKinds?(registry: ServerExtensionRegistry): void;
     snapshot?(room: string, backend: HubBackend): Promise<PluginSnapshot | undefined>;
     filterSnapshot?(snapshot: PluginSnapshot, viewer: {
@@ -111,9 +136,15 @@ interface SyncHubOptions {
     authorizeLayer?: AuthorizeLayer;
     plugins?: readonly ServerSyncPlugin[];
     canRead?: CanRead;
+    canReadOwnerId?: CanReadOwnerId;
+    resolveAudience?: ResolveAudience;
     maxJsonDepth?: number;
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
+    /** Largest `presence.data` payload relayed, in UTF-8 bytes of its JSON encoding. */
+    maxPresenceBytes?: number;
+    /** Registry used to translate extension elements for legacy peers. */
+    elementRegistry?: ElementRegistry;
 }
 declare class SyncHub {
     private readonly backend;
@@ -127,11 +158,16 @@ declare class SyncHub {
     private readonly authorize?;
     private readonly authorizeLayer?;
     private readonly pluginRegistry;
+    private readonly elementRegistry;
+    private readonly peerCapabilities;
     private readonly canRead?;
+    private readonly canReadOwnerId?;
+    private readonly resolveAudience?;
     private readonly memoryLayers;
     private readonly maxJsonDepth;
     private readonly presenceThrottleMs;
     private readonly maxPresenceLanes;
+    private readonly maxPresenceBytes;
     /**
      * Presence throttle state keyed by connection, then by lane. A lane is the
      * payload's `kind` (a non-empty string of at most 64 chars) or the reserved
@@ -170,9 +206,32 @@ declare class SyncHub {
     private getLayerRecords;
     private getLayerRecord;
     private applyLayerRecord;
+    private mayReadOwnerId;
     private mayRead;
     private safePublish;
     private relayToRoom;
+    /**
+     * Translates `op` for the peer and sends it. Returns false when the op is
+     * lossy for this peer (no legacy encoding) or the socket throws; neither
+     * may reject the room operation that produced it.
+     */
+    private sendToConnection;
+    /**
+     * Returns the wire frame for `op` translated for `capabilities`, or null
+     * when lossy. The server-stamped `ownerId` is a server-side authorization
+     * fact: it leaves the hub only for peers `canReadOwnerId` admits.
+     */
+    private encodeForPeer;
+    /**
+     * Normalize registered legacy wire elements before authorization, storage,
+     * and relay. A legacy type this hub has no adapter for is forwarded and
+     * stored verbatim — the hub is a relay, and the peers decide whether they
+     * understand it — so a hub deployed without domain adapters never erases
+     * the room's existing elements. Only a malformed registered element is dropped.
+     */
+    private normalizeElement;
+    private normalizeElements;
+    private relayOpToRoom;
     private broadcastClientPresence;
     private clearPresenceLanes;
     private schedulePresence;
@@ -181,6 +240,7 @@ declare class SyncHub {
     private deliverToRoom;
     private sendCorrection;
     private onFanout;
+    private isPresenceWithinLimit;
     private applyFanoutLayerOp;
     close(): void;
 }
@@ -190,9 +250,9 @@ declare class MemoryHubBackend implements HubBackend {
     private roomLayers;
     private room;
     private layers;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords(room: string): Promise<LayerRecord[]>;
     getLayerRecord(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord(room: string, record: LayerRecord): Promise<void>;
@@ -201,12 +261,25 @@ declare class MemoryHubBackend implements HubBackend {
 interface AuthInfo {
     req: IncomingMessage;
     room: string;
+    /**
+     * Bearer token resolved by `readBearerToken(req)`: a `fieldnotes-bearer.<token>`
+     * `Sec-WebSocket-Protocol` entry, else an `Authorization: Bearer` header, else the
+     * `token` URL query parameter (legacy; URLs land in proxy logs). `undefined` when
+     * none is present.
+     */
+    token?: string;
 }
 interface AuthResult {
     userId: string;
     role?: string;
 }
 type Authenticate = (info: AuthInfo) => AuthResult | null | Promise<AuthResult | null>;
+/**
+ * Resolves the bearer token of an upgrade request, preferring channels that stay
+ * out of access logs: `Sec-WebSocket-Protocol` bearer entry, then
+ * `Authorization: Bearer`, then the `token` query parameter.
+ */
+declare function readBearerToken(req: IncomingMessage): string | undefined;
 
 interface CreateSyncServerOptions {
     port?: number;
@@ -219,6 +292,8 @@ interface CreateSyncServerOptions {
     authorizeLayer?: AuthorizeLayer;
     plugins?: readonly ServerSyncPlugin[];
     canRead?: CanRead;
+    canReadOwnerId?: CanReadOwnerId;
+    resolveAudience?: ResolveAudience;
     heartbeatIntervalMs?: number;
     maxMessageBytes?: number;
     maxJsonDepth?: number;
@@ -226,9 +301,30 @@ interface CreateSyncServerOptions {
     maxPendingAuthBytes?: number;
     messagesPerSecond?: number;
     messageBurst?: number;
+    /** Sustained inbound bytes per second per connection (token bucket). */
+    bytesPerSecond?: number;
+    /** Inbound byte spike allowance per connection; a frame larger than this is never admitted. */
+    byteBurst?: number;
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
+    maxPresenceBytes?: number;
+    /** Concurrent sockets per client address; `Infinity` disables the cap. */
+    maxConnectionsPerIp?: number;
+    /** Concurrent sockets per room, pending-auth sockets included; `Infinity` disables the cap. */
+    maxConnectionsPerRoom?: number;
+    /**
+     * Resolves the client address the per-IP cap keys on. Defaults to the socket's
+     * remote address; behind a trusted proxy read the forwarded header here.
+     * Returning `undefined` or `''` exempts the connection from the per-IP cap.
+     */
+    clientAddress?: (req: IncomingMessage) => string | undefined;
     shutdownGraceMs?: number;
+    /**
+     * Registry used to translate extension envelopes for legacy peers. Without
+     * it the hub relays unknown legacy element types verbatim and cannot encode
+     * envelopes for pre-envelope clients.
+     */
+    elementRegistry?: ElementRegistry;
 }
 declare function createSyncServer(options?: CreateSyncServerOptions): {
     hub: SyncHub;
@@ -236,6 +332,15 @@ declare function createSyncServer(options?: CreateSyncServerOptions): {
     close: () => Promise<void>;
 };
 
+/**
+ * Room names the relay admits. Backends derive storage keys from the room
+ * name (`<prefix><room>:layers`, `<prefix><room>:fog:meta`, ...), so the
+ * alphabet excludes every separator a key builder uses and bounds the length
+ * before `authenticate` runs.
+ */
+declare const ROOM_NAME_PATTERN: RegExp;
+declare function isValidRoomName(room: unknown): room is string;
+
 interface HeartbeatSocket {
     ping(): void;
     terminate(): void;
@@ -250,4 +355,4 @@ interface Heartbeat {
 }
 declare function startHeartbeat(wss: HeartbeatServer, intervalMs: number): Heartbeat;
 
-export { type ApplyResult, type AuthInfo, type AuthResult, type Authenticate, type Authorize, type AuthorizeContext, type AuthorizeLayer, type AuthorizeLayerContext, type CanRead, type Connection, type CreateSyncServerOptions, type Heartbeat, type HeartbeatServer, type HeartbeatSocket, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, type OwnedElement, type ReadContext, type ServerExtensionRegistry, type ServerNext, type ServerOpContext, type ServerSyncPlugin, SyncHub, type SyncHubOptions, createSyncServer, startHeartbeat };
+export { type ApplyResult, type AuthInfo, type AuthResult, type Authenticate, type Authorize, type AuthorizeContext, type AuthorizeLayer, type AuthorizeLayerContext, type CanRead, type CanReadOwnerId, type Connection, type CreateSyncServerOptions, type Heartbeat, type HeartbeatServer, type HeartbeatSocket, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, type OwnedElement, type OwnerReadContext, ROOM_NAME_PATTERN, type ReadContext, type ResolveAudience, type ResolveAudienceContext, type ServerExtensionRegistry, type ServerNext, type ServerOpContext, type ServerSyncPlugin, SyncHub, type SyncHubOptions, createSyncServer, isValidRoomName, readBearerToken, startHeartbeat };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { CanvasElement, ServiceKey } from '@fieldnotes/core';
-import { SyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
+import { ServiceKey, ElementRegistry } from '@fieldnotes/core';
+import { WireSyncElement, WireSyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
 export { PluginSnapshot } from '@fieldnotes/sync';
 import { WebSocketServer } from 'ws';
 import { IncomingMessage, Server } from 'http';
@@ -18,24 +18,21 @@ declare class InMemoryHubFanout implements HubFanout {
 interface HubBackend {
     /** True when every hub instance addresses the same atomic backing state (for example Redis). */
     readonly sharedAcrossInstances?: boolean;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords?(room: string): Promise<LayerRecord[]>;
     getLayerRecord?(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord?(room: string, record: LayerRecord): Promise<void>;
     getService?<T>(key: ServiceKey<T>): T | undefined;
 }
 
-type OwnedElement = CanvasElement & {
-    ownerId?: string;
-    audience?: string;
-};
+type OwnedElement = WireSyncElement;
 interface AuthorizeContext {
     userId?: string;
     role?: string;
     room: string;
-    op: SyncOp;
+    op: WireSyncOp;
     currentElement?: OwnedElement;
 }
 type Authorize = (ctx: AuthorizeContext) => boolean | Promise<boolean>;
@@ -43,7 +40,7 @@ interface AuthorizeLayerContext {
     userId?: string;
     role?: string;
     room: string;
-    op: Extract<SyncOp, {
+    op: Extract<WireSyncOp, {
         kind: 'layer-upsert' | 'layer-remove';
     }>;
     /** The hub's current record for the target layer, tombstones included. */
@@ -63,11 +60,39 @@ interface ReadContext {
     audience: string | undefined;
 }
 type CanRead = (ctx: ReadContext) => boolean;
+interface OwnerReadContext {
+    userId?: string;
+    role?: string;
+    room: string;
+}
+/**
+ * Decides whether a viewer may see the server-stamped `ownerId` on elements it
+ * receives (live ops, snapshots and corrections). Without a hook `ownerId` is
+ * stripped from every outbound frame; it stays in the backend for `authorize`.
+ */
+type CanReadOwnerId = (ctx: OwnerReadContext) => boolean;
+interface ResolveAudienceContext {
+    userId?: string;
+    role?: string;
+    room: string;
+    /** The incoming element as the client sent it, client-asserted `audience` included. */
+    element: WireSyncElement;
+    /** The hub's stored element for the same id, if any. */
+    currentElement?: OwnedElement;
+}
+/**
+ * Decides the authoritative `audience` of an upserted element. The returned
+ * value replaces whatever the client asserted (`undefined` clears the field)
+ * before `authorize`, storage and relay, so a client can neither hide content
+ * by tagging it nor reveal content by retagging it. Without a hook the
+ * client's tag passes through and `authorize` must check it.
+ */
+type ResolveAudience = (ctx: ResolveAudienceContext) => string | undefined;
 
 interface ApplyResult {
-    readonly accepted: SyncOp | null;
-    readonly corrections: SyncOp[];
-    readonly broadcast?: SyncOp[];
+    readonly accepted: WireSyncOp | null;
+    readonly corrections: WireSyncOp[];
+    readonly broadcast?: WireSyncOp[];
     readonly locality?: 'shared' | 'local';
 }
 interface ServerOpContext {
@@ -78,7 +103,7 @@ interface ServerOpContext {
     readonly backend: HubBackend;
     backendPlugin<T>(key: ServiceKey<T>): T | undefined;
 }
-type ServerNext = (op: SyncOp, context: ServerOpContext) => Promise<ApplyResult>;
+type ServerNext = (op: WireSyncOp, context: ServerOpContext) => Promise<ApplyResult>;
 interface ServerExtensionRegistry {
     register<TPayload>(kind: ExtensionKind<TPayload>, handler: (op: TypedExtensionOp<TPayload>, context: ServerOpContext) => Promise<ApplyResult>): void;
 }
@@ -86,8 +111,8 @@ interface ServerSyncPlugin {
     readonly name: string;
     readonly ownedLegacyKinds?: readonly string[];
     readonly legacySnapshotKey?: string;
-    process?(op: SyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
-    applyFanout?(op: SyncOp, context: ServerOpContext): Promise<SyncOp | null>;
+    process?(op: WireSyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
+    applyFanout?(op: WireSyncOp, context: ServerOpContext): Promise<WireSyncOp | null>;
     registerExtensionKinds?(registry: ServerExtensionRegistry): void;
     snapshot?(room: string, backend: HubBackend): Promise<PluginSnapshot | undefined>;
     filterSnapshot?(snapshot: PluginSnapshot, viewer: {
@@ -111,9 +136,15 @@ interface SyncHubOptions {
     authorizeLayer?: AuthorizeLayer;
     plugins?: readonly ServerSyncPlugin[];
     canRead?: CanRead;
+    canReadOwnerId?: CanReadOwnerId;
+    resolveAudience?: ResolveAudience;
     maxJsonDepth?: number;
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
+    /** Largest `presence.data` payload relayed, in UTF-8 bytes of its JSON encoding. */
+    maxPresenceBytes?: number;
+    /** Registry used to translate extension elements for legacy peers. */
+    elementRegistry?: ElementRegistry;
 }
 declare class SyncHub {
     private readonly backend;
@@ -127,11 +158,16 @@ declare class SyncHub {
     private readonly authorize?;
     private readonly authorizeLayer?;
     private readonly pluginRegistry;
+    private readonly elementRegistry;
+    private readonly peerCapabilities;
     private readonly canRead?;
+    private readonly canReadOwnerId?;
+    private readonly resolveAudience?;
     private readonly memoryLayers;
     private readonly maxJsonDepth;
     private readonly presenceThrottleMs;
     private readonly maxPresenceLanes;
+    private readonly maxPresenceBytes;
     /**
      * Presence throttle state keyed by connection, then by lane. A lane is the
      * payload's `kind` (a non-empty string of at most 64 chars) or the reserved
@@ -170,9 +206,32 @@ declare class SyncHub {
     private getLayerRecords;
     private getLayerRecord;
     private applyLayerRecord;
+    private mayReadOwnerId;
     private mayRead;
     private safePublish;
     private relayToRoom;
+    /**
+     * Translates `op` for the peer and sends it. Returns false when the op is
+     * lossy for this peer (no legacy encoding) or the socket throws; neither
+     * may reject the room operation that produced it.
+     */
+    private sendToConnection;
+    /**
+     * Returns the wire frame for `op` translated for `capabilities`, or null
+     * when lossy. The server-stamped `ownerId` is a server-side authorization
+     * fact: it leaves the hub only for peers `canReadOwnerId` admits.
+     */
+    private encodeForPeer;
+    /**
+     * Normalize registered legacy wire elements before authorization, storage,
+     * and relay. A legacy type this hub has no adapter for is forwarded and
+     * stored verbatim — the hub is a relay, and the peers decide whether they
+     * understand it — so a hub deployed without domain adapters never erases
+     * the room's existing elements. Only a malformed registered element is dropped.
+     */
+    private normalizeElement;
+    private normalizeElements;
+    private relayOpToRoom;
     private broadcastClientPresence;
     private clearPresenceLanes;
     private schedulePresence;
@@ -181,6 +240,7 @@ declare class SyncHub {
     private deliverToRoom;
     private sendCorrection;
     private onFanout;
+    private isPresenceWithinLimit;
     private applyFanoutLayerOp;
     close(): void;
 }
@@ -190,9 +250,9 @@ declare class MemoryHubBackend implements HubBackend {
     private roomLayers;
     private room;
     private layers;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords(room: string): Promise<LayerRecord[]>;
     getLayerRecord(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord(room: string, record: LayerRecord): Promise<void>;
@@ -201,12 +261,25 @@ declare class MemoryHubBackend implements HubBackend {
 interface AuthInfo {
     req: IncomingMessage;
     room: string;
+    /**
+     * Bearer token resolved by `readBearerToken(req)`: a `fieldnotes-bearer.<token>`
+     * `Sec-WebSocket-Protocol` entry, else an `Authorization: Bearer` header, else the
+     * `token` URL query parameter (legacy; URLs land in proxy logs). `undefined` when
+     * none is present.
+     */
+    token?: string;
 }
 interface AuthResult {
     userId: string;
     role?: string;
 }
 type Authenticate = (info: AuthInfo) => AuthResult | null | Promise<AuthResult | null>;
+/**
+ * Resolves the bearer token of an upgrade request, preferring channels that stay
+ * out of access logs: `Sec-WebSocket-Protocol` bearer entry, then
+ * `Authorization: Bearer`, then the `token` query parameter.
+ */
+declare function readBearerToken(req: IncomingMessage): string | undefined;
 
 interface CreateSyncServerOptions {
     port?: number;
@@ -219,6 +292,8 @@ interface CreateSyncServerOptions {
     authorizeLayer?: AuthorizeLayer;
     plugins?: readonly ServerSyncPlugin[];
     canRead?: CanRead;
+    canReadOwnerId?: CanReadOwnerId;
+    resolveAudience?: ResolveAudience;
     heartbeatIntervalMs?: number;
     maxMessageBytes?: number;
     maxJsonDepth?: number;
@@ -226,9 +301,30 @@ interface CreateSyncServerOptions {
     maxPendingAuthBytes?: number;
     messagesPerSecond?: number;
     messageBurst?: number;
+    /** Sustained inbound bytes per second per connection (token bucket). */
+    bytesPerSecond?: number;
+    /** Inbound byte spike allowance per connection; a frame larger than this is never admitted. */
+    byteBurst?: number;
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
+    maxPresenceBytes?: number;
+    /** Concurrent sockets per client address; `Infinity` disables the cap. */
+    maxConnectionsPerIp?: number;
+    /** Concurrent sockets per room, pending-auth sockets included; `Infinity` disables the cap. */
+    maxConnectionsPerRoom?: number;
+    /**
+     * Resolves the client address the per-IP cap keys on. Defaults to the socket's
+     * remote address; behind a trusted proxy read the forwarded header here.
+     * Returning `undefined` or `''` exempts the connection from the per-IP cap.
+     */
+    clientAddress?: (req: IncomingMessage) => string | undefined;
     shutdownGraceMs?: number;
+    /**
+     * Registry used to translate extension envelopes for legacy peers. Without
+     * it the hub relays unknown legacy element types verbatim and cannot encode
+     * envelopes for pre-envelope clients.
+     */
+    elementRegistry?: ElementRegistry;
 }
 declare function createSyncServer(options?: CreateSyncServerOptions): {
     hub: SyncHub;
@@ -236,6 +332,15 @@ declare function createSyncServer(options?: CreateSyncServerOptions): {
     close: () => Promise<void>;
 };
 
+/**
+ * Room names the relay admits. Backends derive storage keys from the room
+ * name (`<prefix><room>:layers`, `<prefix><room>:fog:meta`, ...), so the
+ * alphabet excludes every separator a key builder uses and bounds the length
+ * before `authenticate` runs.
+ */
+declare const ROOM_NAME_PATTERN: RegExp;
+declare function isValidRoomName(room: unknown): room is string;
+
 interface HeartbeatSocket {
     ping(): void;
     terminate(): void;
@@ -250,4 +355,4 @@ interface Heartbeat {
 }
 declare function startHeartbeat(wss: HeartbeatServer, intervalMs: number): Heartbeat;
 
-export { type ApplyResult, type AuthInfo, type AuthResult, type Authenticate, type Authorize, type AuthorizeContext, type AuthorizeLayer, type AuthorizeLayerContext, type CanRead, type Connection, type CreateSyncServerOptions, type Heartbeat, type HeartbeatServer, type HeartbeatSocket, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, type OwnedElement, type ReadContext, type ServerExtensionRegistry, type ServerNext, type ServerOpContext, type ServerSyncPlugin, SyncHub, type SyncHubOptions, createSyncServer, startHeartbeat };
+export { type ApplyResult, type AuthInfo, type AuthResult, type Authenticate, type Authorize, type AuthorizeContext, type AuthorizeLayer, type AuthorizeLayerContext, type CanRead, type CanReadOwnerId, type Connection, type CreateSyncServerOptions, type Heartbeat, type HeartbeatServer, type HeartbeatSocket, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, type OwnedElement, type OwnerReadContext, ROOM_NAME_PATTERN, type ReadContext, type ResolveAudience, type ResolveAudienceContext, type ServerExtensionRegistry, type ServerNext, type ServerOpContext, type ServerSyncPlugin, SyncHub, type SyncHubOptions, createSyncServer, isValidRoomName, readBearerToken, startHeartbeat };