@fieldnotes/sync-server 0.17.1 → 0.19.0

package/README.md

@@ -97,9 +97,11 @@ await server.close();
 ## Resource limits
 
 The reference server bounds work and memory per connection by default. Oversized WebSocket messages
-close with code `1009`; message-rate and pending-auth queue violations close with code `4408`.
-Messages with excessive JSON nesting are dropped. Presence sends immediately, then coalesces rapid
-updates so the latest state is forwarded at most once per throttle interval.
+close with code `1009`; message-rate, byte-rate and pending-auth queue violations close with code
+`4408`; a socket over the per-address or per-room connection cap closes with `4429`. Messages with
+excessive JSON nesting, and presence payloads over `maxPresenceBytes`, are dropped. Presence sends
+immediately, then coalesces rapid updates so the latest state is forwarded at most once per throttle
+interval.
 
 ```ts
 createSyncServer({
@@ -110,15 +112,27 @@ createSyncServer({
   maxPendingAuthBytes: 2 * 1024 * 1024,
   messagesPerSecond: 120,
   messageBurst: 240,
+  bytesPerSecond: 4 * 1024 * 1024,
+  byteBurst: 8 * 1024 * 1024,
   presenceThrottleMs: 50,
+  maxPresenceBytes: 4 * 1024,
+  maxConnectionsPerIp: 64,
+  maxConnectionsPerRoom: 256,
+  clientAddress: (req) => req.socket.remoteAddress,
 });
 ```
 
 These values are the defaults. Tune them to the largest legitimate board operation and expected
 client update rate. `maxMessageBytes` is enforced by the WebSocket parser before a complete message
 is allocated, including fragmented messages. The pending-auth limits bound messages held while an
-asynchronous `authenticate` hook is unresolved. Rate limits are per connection and use a token
-bucket: `messageBurst` is the short spike allowance and `messagesPerSecond` is the refill rate.
+asynchronous `authenticate` hook is unresolved. Rate limits are per connection and use token
+buckets: `messageBurst` / `byteBurst` are the short spike allowances and `messagesPerSecond` /
+`bytesPerSecond` the refill rates, so relay amplification is bounded in bytes, not just frames.
+Connection caps are taken at the upgrade, before `authenticate` runs, and count pending-auth
+sockets; behind a trusted proxy supply `clientAddress` to read the forwarded address, and return
+`undefined` to exempt a connection from the per-address cap. Rate and burst values must be positive
+finite numbers; connection caps must be positive safe integers, or `Infinity` to disable a cap.
+Invalid values throw during `createSyncServer` construction.
 
 ## Authentication
 
@@ -161,11 +175,42 @@ continues to use the authenticated `userId` and `role`, not this transport ident
 
 ### Passing a token
 
-A browser `WebSocket` can't set request headers, so pass the token as a URL query
-param (`ws://relay?room=R&token=…`) and read it from `req.url` in `authenticate`. URLs
-land in access/proxy logs, so prefer **short-lived / single-use** tokens. Non-browser
-clients can instead put the token in `req.headers` (e.g. `Authorization`), which
-`authenticate` reads directly.
+`authenticate` receives `token`, resolved by the exported `readBearerToken(req)` in this order:
+
+1. A `Sec-WebSocket-Protocol` entry `fieldnotes-bearer.<token>` — the browser-safe channel. A
+   browser `WebSocket` can't set request headers, but it can offer subprotocols; the relay reads
+   the token, selects the `fieldnotes-sync` subprotocol and never echoes the bearer entry. On the
+   client, `bearerSubprotocols(token)` from `@fieldnotes/sync` builds the offer:
+
+   ```ts
+   import {
+     WebSocketTransport,
+     bearerSubprotocols,
+     createManagedSyncConnection,
+   } from '@fieldnotes/sync';
+
+   new WebSocketTransport('wss://relay?room=R', { protocols: bearerSubprotocols(token) });
+   // or, managed:
+   createManagedSyncConnection({
+     store,
+     clientId,
+     resolveUrl: async () => ({
+       url: 'wss://relay?room=R',
+       protocols: bearerSubprotocols(await mint()),
+     }),
+   });
+   ```
+
+   The token must be a valid subprotocol token (JWT and base64url alphabets qualify; base64 `=`
+   padding does not).
+
+2. An `Authorization: Bearer <token>` header, for non-browser clients.
+3. The `token` URL query parameter (`ws://relay?room=R&token=…`). Still supported so existing
+   clients keep working, but URLs land in access/proxy logs: prefer the channels above, and use
+   **short-lived / single-use** tokens if you must stay on the URL.
+
+`req` is still passed, so an `authenticate` hook that reads `req.url` or `req.headers` itself
+keeps working unchanged.
 
 ## Authorization
 
@@ -184,13 +229,13 @@ authorize(ctx) => boolean | Promise<boolean>
   userId?: string;          // the connection's authenticated user (from authenticate)
   role?: string;            // the connection's role (from authenticate)
   room: string;
-  op: SyncOp;               // the incoming upsert / remove / clear
+  op: WireSyncOp;           // the incoming upsert / remove / clear
   currentElement?: OwnedElement; // the STORED element, if this id already exists
 }
 ```
 
 `currentElement` is the element currently in room state for an `upsert`/`remove` of an
-**existing** id (typed `OwnedElement = CanvasElement & { ownerId?: string }`), and
+**existing** id (typed `OwnedElement = WireSyncElement`), and
 `undefined` for a new/absent id.
 
 **Ownership is server-stamped and un-forgeable.** A new element's `ownerId` is set to the
@@ -198,8 +243,17 @@ authenticated creator; on edit the stored owner is **preserved**; a client-suppl
 `ownerId` is always **discarded**. A policy can therefore trust `currentElement.ownerId`
 to enforce "own elements only".
 
+**`ownerId` stays on the server.** It is stripped from every outbound frame (live ops,
+snapshots, corrections, legacy translations) so a viewer's save file never records who
+created what. Pass `canReadOwnerId({ userId, role, room }) => boolean` to reveal it to
+privileged viewers, e.g. `canReadOwnerId: ({ role }) => role === 'dm'`.
+
 With **no hook**, rooms are OPEN (allow-all — every op is accepted).
 
+When `canRead` filtering is in use, `op.element.audience` is what the sender asserted unless a
+`resolveAudience` hook is configured (see [Read filtering](#read-filtering)); an `authorize` policy
+without that hook must validate the audience itself.
+
 A copy-paste DM / player / display policy:
 
 ```ts
@@ -224,7 +278,8 @@ createSyncServer({
 
 - Ownership-based authz **requires `authenticate` to supply a STABLE `userId`**. The
   no-hook anonymous default is `userId = connId`, which changes on every reconnect — a
-  user would lose access to their own elements after reconnecting.
+  user would lose access to their own elements after reconnecting. `createSyncServer`
+  therefore **throws** when `authorize` is configured without `authenticate`.
 - The authz path adds one `backend.get` (a Redis `HGET`) per data op — negligible for
   low-write use.
 - Reads / visibility (a player not **receiving** hidden content) are a separate, upcoming
@@ -276,9 +331,17 @@ gets a synthetic **remove**, one who gains it gets an **add**.
   instance only), `canRead` runs on **every** instance — each re-filters fanned-out ops for its own
   local members — so all relay instances must inject the **same** `canRead`, alongside the existing
   shared-backend + shared-fanout requirement.
-- **Labeling integrity.** `audience` is client-asserted, so read secrecy is only as trustworthy as
-  the `authorize` (write) policy that stops a player from stamping `dm` on content they shouldn't
-  control.
+- **Labeling integrity.** `audience` arrives client-asserted. Without a `resolveAudience` hook a
+  player can tag an upsert `dm` to hide it from the table, or retag a hidden element `shared` to
+  reveal it, so **one of the two following hooks is required** for read secrecy:
+  - `resolveAudience({ userId, role, room, element, currentElement }) => string | undefined`
+    (recommended) makes the hub the authority: its return value replaces the client's tag
+    (`undefined` clears it) before `authorize`, storage and relay. A policy such as
+    `({ role, currentElement }) => currentElement?.audience ?? (role === 'dm' ? 'dm' : 'shared')`
+    keeps an element's audience stable and lets only a DM create hidden content.
+  - Otherwise `authorize` **must** enforce the audience contract itself: reject an `upsert` whose
+    `op.element.audience` the sender may not write to, and reject one whose audience differs from
+    `currentElement.audience` unless the sender may move it.
 
 A Redis `HubBackend` and cross-instance fan-out ship in [`@fieldnotes/sync-redis`](../sync-redis).