@woosh/meep-engine 2.163.11 → 2.165.0

package/src/engine/network/adapters/TransformReplicationAdapter.js

@@ -1,5 +1,5 @@
-import { quat_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat_decode_from_uint32.js";
-import { quat_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat_encode_to_uint32.js";
+import { quat3_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat3_decode_from_uint32.js";
+import { quat3_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat3_encode_to_uint32.js";
 import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization/v3_binary_equality_decode.js";
 import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
 import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
@@ -52,7 +52,7 @@ export class TransformReplicationAdapter extends BinaryClassSerializationAdapter
         buffer.writeFloat32(position.y);
         buffer.writeFloat32(position.z);
 
-        buffer.writeUint32(quat_encode_to_uint32(
+        buffer.writeUint32(quat3_encode_to_uint32(
             rotation.x,
             rotation.y,
             rotation.z,
@@ -79,7 +79,7 @@ export class TransformReplicationAdapter extends BinaryClassSerializationAdapter
         v3_binary_equality_decode(buffer, s, 0);
         value.scale.set(s[0], s[1], s[2]);
 
-        quat_decode_from_uint32(s, 0, encoded_rotation);
+        quat3_decode_from_uint32(s, 0, encoded_rotation);
         value.rotation.set(s[0], s[1], s[2], s[3]);
 
         value.position.set(positionX, positionY, positionZ);

package/src/engine/network/core/MalformedPacketError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thrown when a parser detects that an inbound packet is structurally
+ * malformed — a declared length, count, or field that does not fit within
+ * the bytes actually received.
+ *
+ * This is an EXPECTED failure mode on an untrusted wire (a truncated
+ * datagram, a spoofed/corrupted packet, or a peer running a mismatched
+ * build), not a programming error. The dispatch boundary
+ * ({@link NetworkPeer}) catches it — together with the `RangeError` a
+ * {@link BinaryBuffer} throws on a read past its backing store — and drops
+ * the offending packet (the "discard the bad record, keep the connection"
+ * posture) rather than letting it tear down the receive loop.
+ *
+ * Throwing a dedicated type, rather than a bare `Error`, lets the boundary
+ * distinguish "bad bytes on the wire" (drop + count) from a genuine bug in
+ * a packet handler (which must still propagate so it is not silenced).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MalformedPacketError extends Error {
+    constructor(message: any);
+}
+//# sourceMappingURL=MalformedPacketError.d.ts.map

package/src/engine/network/core/MalformedPacketError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MalformedPacketError.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/core/MalformedPacketError.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI,0BAGC;CACJ"}

package/src/engine/network/core/MalformedPacketError.js

@@ -0,0 +1,26 @@
+/**
+ * Thrown when a parser detects that an inbound packet is structurally
+ * malformed — a declared length, count, or field that does not fit within
+ * the bytes actually received.
+ *
+ * This is an EXPECTED failure mode on an untrusted wire (a truncated
+ * datagram, a spoofed/corrupted packet, or a peer running a mismatched
+ * build), not a programming error. The dispatch boundary
+ * ({@link NetworkPeer}) catches it — together with the `RangeError` a
+ * {@link BinaryBuffer} throws on a read past its backing store — and drops
+ * the offending packet (the "discard the bad record, keep the connection"
+ * posture) rather than letting it tear down the receive loop.
+ *
+ * Throwing a dedicated type, rather than a bare `Error`, lets the boundary
+ * distinguish "bad bytes on the wire" (drop + count) from a genuine bug in
+ * a packet handler (which must still propagate so it is not silenced).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MalformedPacketError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MalformedPacketError';
+    }
+}

package/src/engine/network/ecs/owner_authorization.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Default inbound-action authorization policy for server-authoritative
+ * sessions: a remote-originated action may mutate an entity only if the
+ * sending peer owns it.
+ *
+ * Wire into {@link SimActionExecutor#authorize}. The executor calls the
+ * returned predicate once per local entity an inbound action reports via
+ * `affected_components`; if any entity fails, the whole action is rejected
+ * (not applied, not logged). Server-local actions (`SENDER_LOCAL`) bypass
+ * the gate entirely and are not passed here.
+ *
+ * Policy:
+ *   - sender is the authoritative server itself (`sender_id === server_peer_id`)
+ *     → allow. The server has authority over every entity, and its own
+ *     mutations ride the action stream tagged with its real peer id (not the
+ *     {@link SENDER_LOCAL} sentinel), so they reach this gate and must pass.
+ *   - otherwise: entity has the identity component AND `owner_peer_id ===
+ *     sender` → allow.
+ *   - entity owned by a different peer, or by the server (`owner_peer_id < 0`),
+ *     or not a replicated entity at all (no identity component) → deny.
+ *
+ * Denying the no-identity case is deliberate: a legitimate client only ever
+ * acts on entities it owns; an inbound action targeting an unknown / server-
+ * owned entity is exactly the spoofing case this gate exists to stop.
+ * Structural creation/destruction flows through INITIAL_SYNC / STATE_BURST and
+ * the entity lifecycle, not through client SimActions, so this never blocks a
+ * legitimate spawn.
+ *
+ * `identity_class` is injected (rather than imported) so this helper stays in
+ * the transport-agnostic layer — pass `NetworkIdentity`. `server_peer_id` is
+ * the authoritative peer's id (the host's `local_peer_id`); pass `-1` (the
+ * default) in a context with no privileged peer.
+ *
+ * @param {{
+ *   world: EntityComponentDataset,
+ *   identity_class: Function,
+ *   server_peer_id?: number,
+ * }} options
+ * @returns {(sender_id: number, entity_id: number) => boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function make_owner_authorization({ world, identity_class, server_peer_id }: {
+    world: EntityComponentDataset;
+    identity_class: Function;
+    server_peer_id?: number;
+}): (sender_id: number, entity_id: number) => boolean;
+//# sourceMappingURL=owner_authorization.d.ts.map

package/src/engine/network/ecs/owner_authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner_authorization.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/ecs/owner_authorization.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,oFAVW;IACV,KAAS,yBAAyB;IAClC,cAAkB,WAAW;IAC7B,cAAkB,CAAC,EAAE,MAAM,CAAC;CACzB,eACqB,MAAM,aAAa,MAAM,KAAK,OAAO,CAgB7D"}

package/src/engine/network/ecs/owner_authorization.js

@@ -0,0 +1,55 @@
+/**
+ * Default inbound-action authorization policy for server-authoritative
+ * sessions: a remote-originated action may mutate an entity only if the
+ * sending peer owns it.
+ *
+ * Wire into {@link SimActionExecutor#authorize}. The executor calls the
+ * returned predicate once per local entity an inbound action reports via
+ * `affected_components`; if any entity fails, the whole action is rejected
+ * (not applied, not logged). Server-local actions (`SENDER_LOCAL`) bypass
+ * the gate entirely and are not passed here.
+ *
+ * Policy:
+ *   - sender is the authoritative server itself (`sender_id === server_peer_id`)
+ *     → allow. The server has authority over every entity, and its own
+ *     mutations ride the action stream tagged with its real peer id (not the
+ *     {@link SENDER_LOCAL} sentinel), so they reach this gate and must pass.
+ *   - otherwise: entity has the identity component AND `owner_peer_id ===
+ *     sender` → allow.
+ *   - entity owned by a different peer, or by the server (`owner_peer_id < 0`),
+ *     or not a replicated entity at all (no identity component) → deny.
+ *
+ * Denying the no-identity case is deliberate: a legitimate client only ever
+ * acts on entities it owns; an inbound action targeting an unknown / server-
+ * owned entity is exactly the spoofing case this gate exists to stop.
+ * Structural creation/destruction flows through INITIAL_SYNC / STATE_BURST and
+ * the entity lifecycle, not through client SimActions, so this never blocks a
+ * legitimate spawn.
+ *
+ * `identity_class` is injected (rather than imported) so this helper stays in
+ * the transport-agnostic layer — pass `NetworkIdentity`. `server_peer_id` is
+ * the authoritative peer's id (the host's `local_peer_id`); pass `-1` (the
+ * default) in a context with no privileged peer.
+ *
+ * @param {{
+ *   world: EntityComponentDataset,
+ *   identity_class: Function,
+ *   server_peer_id?: number,
+ * }} options
+ * @returns {(sender_id: number, entity_id: number) => boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function make_owner_authorization({ world, identity_class, server_peer_id = -1 }) {
+    return (sender_id, entity_id) => {
+        if (sender_id === server_peer_id) {
+            return true;
+        }
+        const identity = world.getComponent(entity_id, identity_class);
+        if (identity === undefined) {
+            return false;
+        }
+        return identity.owner_peer_id === sender_id;
+    };
+}

package/src/engine/network/orchestrator/NetworkPeer.d.ts

@@ -32,6 +32,13 @@ export const ResumeRejectReason: Readonly<{
     GraceExpired: 1;
     TokenMismatch: 2;
     PeerIdCollision: 3;
+    /**
+     * The peer's token validated, but the frame it asks to resume from has
+     * already aged out of the host's action-log ring — the action stream
+     * cannot back-fill the gap. The client must fall through to a full
+     * INITIAL_SYNC re-sync rather than resume into a silent desync.
+     */
+    StaleFrame: 4;
 }>;
 /**
  * Per-tick orchestrator that wires the action infrastructure to one or more
@@ -111,6 +118,14 @@ export class NetworkPeer {
     replicator: Replicator;
     /** @type {Baseline} */
     baseline: Baseline;
+    /**
+     * Fired when an inbound packet is dropped as malformed. Args:
+     * `(peer_id, error)`. Lets callers log / rate-limit / disconnect an
+     * abusive peer. The receive loop continues regardless — a bad packet
+     * never tears down the connection.
+     * @type {Signal}
+     */
+    onMalformedPacket: Signal;
     /**
      * Fired when an inbound packet is a `RECOVERY_REQUEST` (peer is asking
      * which entities mutated in a tick range so it can request their state).
@@ -219,6 +234,22 @@ export class NetworkPeer {
      * @returns {boolean}
      */
     is_connected(peer_id: number): boolean;
+    /**
+     * Number of inbound packets dropped so far because they were malformed
+     * (see {@link onMalformedPacket}). Monotonic for the life of the peer.
+     * @returns {number}
+     */
+    malformed_packets_dropped(): number;
+    /**
+     * Monotonic count of inbound packets delivered for `peer_id` since it
+     * connected — any packet that reached the dispatch boundary, including
+     * empty-ack and malformed ones (all evidence the peer/transport is alive).
+     * Returns 0 for an unknown peer. Idle/liveness detection polls this and
+     * reaps a peer whose count stops advancing.
+     * @param {number} peer_id
+     * @returns {number}
+     */
+    inbound_count(peer_id: number): number;
     /**
      * Direct access to a peer's channel (for sending acks-only packets, raw payloads, etc.).
      * @param {number} peer_id

package/src/engine/network/orchestrator/NetworkPeer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkPeer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/NetworkPeer.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"NetworkPeer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/NetworkPeer.js"],"names":[],"mappings":"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"}

package/src/engine/network/orchestrator/NetworkPeer.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
+import { MalformedPacketError } from "../core/MalformedPacketError.js";
 import { Replicator } from "../replication/Replicator.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
 import { ActionLog } from "../sim/ActionLog.js";
@@ -138,6 +139,13 @@ export const ResumeRejectReason = Object.freeze({
     GraceExpired: 1,
     TokenMismatch: 2,
     PeerIdCollision: 3,
+    /**
+     * The peer's token validated, but the frame it asks to resume from has
+     * already aged out of the host's action-log ring — the action stream
+     * cannot back-fill the gap. The client must fall through to a full
+     * INITIAL_SYNC re-sync rather than resume into a silent desync.
+     */
+    StaleFrame: 4,
 });
 
 /**
@@ -174,6 +182,7 @@ export class NetworkPeer {
     #next_fragment_message_id;
     #tick_open;
     #current_frame;
+    #malformed_packets_dropped;
 
 
     /**
@@ -314,6 +323,25 @@ export class NetworkPeer {
         /** @type {boolean} @private */
         this.#tick_open = false;
 
+        /**
+         * Count of inbound packets dropped because they were structurally
+         * malformed (a declared length/count that didn't fit the bytes
+         * received, or any other parse fault at the untrusted boundary).
+         * Read via {@link malformed_packets_dropped}.
+         * @type {number}
+         * @private
+         */
+        this.#malformed_packets_dropped = 0;
+
+        /**
+         * Fired when an inbound packet is dropped as malformed. Args:
+         * `(peer_id, error)`. Lets callers log / rate-limit / disconnect an
+         * abusive peer. The receive loop continues regardless — a bad packet
+         * never tears down the connection.
+         * @type {Signal}
+         */
+        this.onMalformedPacket = new Signal();
+
         /**
          * Fired when an inbound packet is a `RECOVERY_REQUEST` (peer is asking
          * which entities mutated in a tick range so it can request their state).
@@ -546,6 +574,9 @@ export class NetworkPeer {
                     break;
                 }
                 case NetworkPacketType.INITIAL_SYNC: {
+                    if (this.#recv_buffer.position + 16 > length) {
+                        throw new MalformedPacketError(`NetworkPeer.dispatch: INITIAL_SYNC truncated before 16-byte session token`);
+                    }
                     const session_token = new Uint8Array(16);
                     this.#recv_buffer.readBytes(session_token, 0, 16);
                     const frame_number = this.#recv_buffer.readUintVar();
@@ -555,6 +586,9 @@ export class NetworkPeer {
                 case NetworkPacketType.RESUME_HELLO: {
                     const local_peer_id = this.#recv_buffer.readUintVar();
                     const last_acked_frame = this.#recv_buffer.readUintVar();
+                    if (this.#recv_buffer.position + 16 > length) {
+                        throw new MalformedPacketError(`NetworkPeer.dispatch: RESUME_HELLO truncated before 16-byte session token`);
+                    }
                     const session_token = new Uint8Array(16);
                     this.#recv_buffer.readBytes(session_token, 0, 16);
                     this.onResumeHello.send4(peer_id, local_peer_id, last_acked_frame, session_token);
@@ -573,6 +607,9 @@ export class NetworkPeer {
                     const label_length = this.#recv_buffer.readUint8();
                     let label = '';
                     if (label_length > 0) {
+                        if (this.#recv_buffer.position + label_length > length) {
+                            throw new MalformedPacketError(`NetworkPeer.dispatch: DISCONNECT label_length ${label_length} overruns packet`);
+                        }
                         const label_bytes = new Uint8Array(label_length);
                         this.#recv_buffer.readBytes(label_bytes, 0, label_length);
                         label = DISCONNECT_TEXT_DECODER.decode(label_bytes);
@@ -604,15 +641,42 @@ export class NetworkPeer {
             seq_to_frame_end.delete(seq);
         };
 
-        channel.onPayload.add(dispatch);
+        // Untrusted-input boundary. A structurally-malformed or truncated
+        // packet (truncated datagram, spoofed/corrupt bytes, mismatched peer
+        // build) is dropped and counted — the "discard the bad record, keep the
+        // connection" posture — rather than throwing out of the transport's
+        // receive callback and crashing the process. A RangeError is a
+        // BinaryBuffer read past its backing store, i.e. the same malformed-
+        // input symptom. Any OTHER error is a genuine bug in a packet handler
+        // and is rethrown so it is not silently swallowed.
+        const payload_handler = (bytes, length) => {
+            // Liveness: any packet that reaches dispatch — including empty-ack,
+            // and malformed ones dropped below — is evidence the peer/transport
+            // is alive. Bump the per-peer inbound counter idle-detection polls.
+            const conn = this.#peers.get(peer_id);
+            if (conn !== undefined) conn.inbound_count++;
+            try {
+                dispatch(bytes, length);
+            } catch (e) {
+                if (e instanceof MalformedPacketError || e instanceof RangeError) {
+                    this.#malformed_packets_dropped++;
+                    this.onMalformedPacket.send2(peer_id, e);
+                    return;
+                }
+                throw e;
+            }
+        };
+
+        channel.onPayload.add(payload_handler);
         channel.onPacketAcked.add(on_acked);
         channel.onPacketLost.add(on_lost);
 
         this.#peers.set(peer_id, {
             channel, transport, seq_to_frame_end,
-            on_payload: dispatch, on_acked, on_lost, on_nack,
+            on_payload: payload_handler, on_acked, on_lost, on_nack,
             fragment_assembler, fragment_retention,
             reliable_pipeline,
+            inbound_count: 0,
         });
     }
 
@@ -661,6 +725,29 @@ export class NetworkPeer {
         return this.#peers.has(peer_id);
     }
 
+    /**
+     * Number of inbound packets dropped so far because they were malformed
+     * (see {@link onMalformedPacket}). Monotonic for the life of the peer.
+     * @returns {number}
+     */
+    malformed_packets_dropped() {
+        return this.#malformed_packets_dropped;
+    }
+
+    /**
+     * Monotonic count of inbound packets delivered for `peer_id` since it
+     * connected — any packet that reached the dispatch boundary, including
+     * empty-ack and malformed ones (all evidence the peer/transport is alive).
+     * Returns 0 for an unknown peer. Idle/liveness detection polls this and
+     * reaps a peer whose count stops advancing.
+     * @param {number} peer_id
+     * @returns {number}
+     */
+    inbound_count(peer_id) {
+        const conn = this.#peers.get(peer_id);
+        return conn === undefined ? 0 : conn.inbound_count;
+    }
+
     /**
      * Direct access to a peer's channel (for sending acks-only packets, raw payloads, etc.).
      * @param {number} peer_id

package/src/engine/network/orchestrator/ServerAuthoritativeServer.d.ts

@@ -62,7 +62,7 @@ export class ServerAuthoritativeServer {
      * input-to-feedback latency (client prediction hides it). Default 0
      * reproduces pre-feature behavior.
      */
-    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, simulation_delay_ticks, }: {
+    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, simulation_delay_ticks, max_pending_future_lead, max_pending_total, }: {
         world: EntityComponentDataset;
         binary_registry: BinarySerializationRegistry;
         replicated_components: Function[];
@@ -102,6 +102,28 @@ export class ServerAuthoritativeServer {
      * @type {number}
      */
     simulation_delay_ticks: number;
+    /**
+     * Upper bound on how far ahead of the server's own simulation a peer
+     * may tag an inbound action. `frame_number` is an attacker-controlled
+     * varint; without a ceiling, future-tagged entries accumulate in the
+     * pending log unbounded (only the past side is trimmed in {@link tick}).
+     * A well-behaved client tags at most ~`simulation_delay_ticks` ahead
+     * plus a jitter lead, so the accept window is
+     * `current_sim_frame + simulation_delay_ticks + max_pending_future_lead`.
+     * @type {number}
+     */
+    max_pending_future_lead: number;
+    /**
+     * Absolute backstop on the number of buffered pending entries. Even
+     * within the future window a peer can vary an action's payload to
+     * defeat the per-frame dedup and pile up many distinct entries; this
+     * caps total memory (and the dedup scan cost) regardless. Legitimate
+     * pending depth is tiny (≈ delay × actions/frame × peers), so this only
+     * ever trips under abuse. Raise it for very high concurrent-player
+     * counts.
+     * @type {number}
+     */
+    max_pending_total: number;
     /**
      * Most recently simulated frame. `-1` during warmup
      * (`wall_frame < simulation_delay_ticks`), advances by 1 per
@@ -144,6 +166,15 @@ export class ServerAuthoritativeServer {
      * @type {Signal}
      */
     onRewind: Signal;
+    /**
+     * Fired when an inbound pending action is dropped by the future-lead or
+     * total-capacity bound (i.e. a far-future frame tag or a flood). Args:
+     * `(sender_id, frame_number, reason)` where `reason` is `'future'` or
+     * `'capacity'`. Observable so an abusive peer can be logged / kicked;
+     * the dropped action is simply not buffered.
+     * @type {Signal}
+     */
+    onPendingActionDropped: Signal;
     /**
      * Connect a client peer over a transport. Subsequent action packets from
      * this peer will be buffered in the pending log via the deferral hook
@@ -208,6 +239,12 @@ export class ServerAuthoritativeServer {
      * @returns {number}
      */
     buffer_depth_for_peer(peer_id: number): number;
+    /**
+     * Number of inbound pending actions dropped by the future-lead / total
+     * bounds so far. See {@link onPendingActionDropped}.
+     * @returns {number}
+     */
+    pending_dropped_count(): number;
     #private;
 }
 import { NetworkPeer } from "./NetworkPeer.js";

package/src/engine/network/orchestrator/ServerAuthoritativeServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAYI;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,2JApBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;KACjC,EAwJH;IAlIG,0BAA0B;IAC1B,MADW,WAAW,CASpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;OAKG;IACH,mBAFU,MAAM,CAEW;IAwC3B;;;;;;;;;;;OAWG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAGhC;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,kBACA,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;OAYG;IACH,oBAFW,MAAM,QA2ChB;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;;CA+MJ;4BAxiB2B,kBAAkB;6BADjB,wBAAwB;mBAJlC,uCAAuC;6BAH7B,sCAAsC"}
+{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAaI;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uMApBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;KACjC,EAqMH;IA3KG,0BAA0B;IAC1B,MADW,WAAW,CASpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;;;;;OASG;IACH,yBAFU,MAAM,CAEsC;IAEtD;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;;;OAKG;IACH,mBAFU,MAAM,CAEW;IA+C3B;;;;;;;;;;;OAWG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,wBAFU,MAAM,CAE0B;IAG9C;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,kBACA,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;OAYG;IACH,oBAFW,MAAM,QA2ChB;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;IA2GD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA0HJ;4BAnnB2B,kBAAkB;6BADjB,wBAAwB;mBAJlC,uCAAuC;6BAH7B,sCAAsC"}

package/src/engine/network/orchestrator/ServerAuthoritativeServer.js

@@ -61,6 +61,7 @@ export class ServerAuthoritativeServer {
     #historical_scratch;
     #sort_scratch;
     #payload_buf;
+    #pending_dropped;
 
 
     /**
@@ -93,8 +94,12 @@ export class ServerAuthoritativeServer {
         frame_capacity = 32,
         initial_buffer_size = 1024,
         simulation_delay_ticks = 0,
+        max_pending_future_lead = 256,
+        max_pending_total = 4096,
     }) {
         assert.isNonNegativeInteger(simulation_delay_ticks, 'simulation_delay_ticks');
+        assert.isPositiveInteger(max_pending_future_lead, 'max_pending_future_lead');
+        assert.isPositiveInteger(max_pending_total, 'max_pending_total');
         /** @type {NetworkPeer} */
         this.peer = new NetworkPeer({
             world,
@@ -142,6 +147,30 @@ export class ServerAuthoritativeServer {
          */
         this.simulation_delay_ticks = simulation_delay_ticks;
 
+        /**
+         * Upper bound on how far ahead of the server's own simulation a peer
+         * may tag an inbound action. `frame_number` is an attacker-controlled
+         * varint; without a ceiling, future-tagged entries accumulate in the
+         * pending log unbounded (only the past side is trimmed in {@link tick}).
+         * A well-behaved client tags at most ~`simulation_delay_ticks` ahead
+         * plus a jitter lead, so the accept window is
+         * `current_sim_frame + simulation_delay_ticks + max_pending_future_lead`.
+         * @type {number}
+         */
+        this.max_pending_future_lead = max_pending_future_lead;
+
+        /**
+         * Absolute backstop on the number of buffered pending entries. Even
+         * within the future window a peer can vary an action's payload to
+         * defeat the per-frame dedup and pile up many distinct entries; this
+         * caps total memory (and the dedup scan cost) regardless. Legitimate
+         * pending depth is tiny (≈ delay × actions/frame × peers), so this only
+         * ever trips under abuse. Raise it for very high concurrent-player
+         * counts.
+         * @type {number}
+         */
+        this.max_pending_total = max_pending_total;
+
         /**
          * Most recently simulated frame. `-1` during warmup
          * (`wall_frame < simulation_delay_ticks`), advances by 1 per
@@ -173,6 +202,13 @@ export class ServerAuthoritativeServer {
         this.#payload_buf = new BinaryBuffer();
         this.#payload_buf.setCapacity(64);
 
+        /**
+         * Count of inbound pending entries dropped by the future-lead / total
+         * bounds. See {@link onPendingActionDropped}.
+         * @private @type {number}
+         */
+        this.#pending_dropped = 0;
+
         // Switch the Replicator to deferred-execute mode: incoming actions
         // accumulate in pending until tick() drains them.
         this.peer.replicator.on_pending_action = (peer_id, frame_number, type_id, buf, off, len) => {
@@ -225,6 +261,16 @@ export class ServerAuthoritativeServer {
          * @type {Signal}
          */
         this.onRewind = new Signal();
+
+        /**
+         * Fired when an inbound pending action is dropped by the future-lead or
+         * total-capacity bound (i.e. a far-future frame tag or a flood). Args:
+         * `(sender_id, frame_number, reason)` where `reason` is `'future'` or
+         * `'capacity'`. Observable so an abusive peer can be logged / kicked;
+         * the dropped action is simply not buffered.
+         * @type {Signal}
+         */
+        this.onPendingActionDropped = new Signal();
     }
 
     /**
@@ -459,8 +505,37 @@ export class ServerAuthoritativeServer {
         }
     }
 
+    /**
+     * Number of inbound pending actions dropped by the future-lead / total
+     * bounds so far. See {@link onPendingActionDropped}.
+     * @returns {number}
+     */
+    pending_dropped_count() {
+        return this.#pending_dropped;
+    }
+
     /** @private */
     #pending_add(frame_number, sender_id, type_id, payload) {
+        // Reject far-future frame numbers. `frame_number` is an attacker-
+        // controlled varint; tick() only trims the PAST side of the pending
+        // log, so without this ceiling a peer can pin unbounded memory (and
+        // O(n) per-insert cost) by tagging actions near 2^32. A well-behaved
+        // client tags at most ~simulation_delay_ticks ahead plus jitter lead.
+        // Real runtime check — asserts strip in prod.
+        const future_horizon = this.current_sim_frame + this.simulation_delay_ticks + this.max_pending_future_lead;
+        if (frame_number > future_horizon) {
+            this.#pending_dropped++;
+            this.onPendingActionDropped.send3(sender_id, frame_number, 'future');
+            return;
+        }
+        // Absolute backstop: even within the future window a peer can vary the
+        // payload to defeat the dedup below and pile up distinct entries.
+        if (this.#pending_frames.length >= this.max_pending_total) {
+            this.#pending_dropped++;
+            this.onPendingActionDropped.send3(sender_id, frame_number, 'capacity');
+            return;
+        }
+
         // Dedup against other pending entries for the same frame. Multiple
         // retransmission packets routinely arrive in the same c2s.tick
         // window when ack RTT exceeds tick period; each carries the same

package/src/engine/network/replication/Replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAKI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OAyFpF;IArFG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IA0BhC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE3H;IAGjC;;;;;;;;;;OAUG;IACH,uBALW,MAAM,eACN,MAAM,aACN,MAAM,kCA2ChB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QAqFhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBA5XkB,uCAAuC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAKI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OAyFpF;IArFG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IA0BhC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE3H;IAGjC;;;;;;;;;;OAUG;IACH,uBALW,MAAM,eACN,MAAM,aACN,MAAM,kCA2ChB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QA4GhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBAxZkB,uCAAuC"}