@net-mesh/browser 0.42.0 → 0.43.0

package/dist/store/owner.js

@@ -41,6 +41,15 @@ import { decimalValue, decodeMessage, encodeMessage, utf8Length, HANDLE_HEX_LENG
 export const MAX_PENDING_ACTIONS = 32;
 /** Handles one owner will hold (brief §2). */
 export const MAX_HANDLES = 256;
+/**
+ * Handles one authenticated peer may hold at once. Room for siblings and
+ * for a reconnect that overlaps its predecessor's lease, but never the
+ * whole table: one peer could otherwise take all {@link MAX_HANDLES} and
+ * lock every other player out — the lobby's capacity rule counts distinct
+ * peers, so a seated player's repeat joins bypassed it (SDK audit
+ * 2026-10-11).
+ */
+export const MAX_HANDLES_PER_PEER = 16;
 /** How long a handle lives without an accepted authenticated message. */
 export const HANDLE_LEASE_MS = 60_000;
 /** How many hook runs one drain may perform before it stops (see `drainEvents`). */
@@ -245,7 +254,7 @@ export class StoreOwner {
             // having been checked once at admission. The handle goes with the
             // refusal here because the feed is the grant: leaving it alive would
             // let `alive` renew the lease of a peer the policy now forbids.
-            if (!this.permitsRead(handle.peer, handle.audience)) {
+            if (!this.permitsRead(handle.peer, handle.audience, handle.key)) {
                 this.forget(handle.h, 'refused');
                 // `closed`, the wire's legal unsolicited refusal (§1.12 admits
                 // exactly `closed` and `owner-lost` without a `q`): it closes
@@ -505,7 +514,7 @@ export class StoreOwner {
                 // must not be served because the handle is still warm. The
                 // handle survives the refusal: the request was refused, not
                 // the subscription.
-                if (!this.permitsRead(peer, bound.audience)) {
+                if (!this.permitsRead(peer, bound.audience, bound.key)) {
                     return this.refuse('resync-forbidden', [this.no(peer, bound.h, 'forbidden', message.q)]);
                 }
                 const renewed = { ...bound, lastSeen: now };
@@ -532,7 +541,7 @@ export class StoreOwner {
                 // `audience-too-many` at rung 6 (wire.ts, witnessed in
                 // wire.test.ts), so a frame carrying more than the bound never
                 // reaches dispatch. Re-checking it would be a claim.
-                if (!this.permitsRead(peer, message.aud)) {
+                if (!this.permitsRead(peer, message.aud, bound.key)) {
                     return this.refuse(`${message.k}-forbidden`, [this.no(peer, bound.h, 'forbidden', message.q)]);
                 }
                 // The audience is rebound BEFORE the projection, so the
@@ -1000,7 +1009,7 @@ export class StoreOwner {
     reauthorize() {
         const out = [];
         for (const handle of [...this.handles.values()]) {
-            if (this.permitsRead(handle.peer, handle.audience))
+            if (this.permitsRead(handle.peer, handle.audience, handle.key))
                 continue;
             this.forget(handle.h, 'refused');
             out.push(this.no(handle.peer, handle.h, 'closed', null));
@@ -1152,9 +1161,16 @@ export class StoreOwner {
         if (this.handles.size >= MAX_HANDLES) {
             return this.refuse('join-capacity', [this.no(peer, null, 'capacity', message.q)]);
         }
+        let held = 0;
+        for (const existing of this.handles.values())
+            if (existing.peer === peer)
+                held += 1;
+        if (held >= MAX_HANDLES_PER_PEER) {
+            return this.refuse('join-capacity', [this.no(peer, null, 'capacity', message.q)]);
+        }
         // `authorize` receives the AUTHENTICATED peer and the audience it
         // asked to read. A refusal is `forbidden` and allocates nothing.
-        if (!this.permitsRead(peer, message.aud)) {
+        if (!this.permitsRead(peer, message.aud, message.key)) {
             return this.refuse('join-forbidden', [this.no(peer, null, 'forbidden', message.q)]);
         }
         const h = this.newHandle();
@@ -1166,6 +1182,7 @@ export class StoreOwner {
             inc: this.incarnation,
             peer,
             audience: [...message.aud],
+            key: message.key,
             interest: message.int === undefined ? null : [...message.int],
             generation: 0,
             revision: this.core.revision,
@@ -1233,8 +1250,11 @@ export class StoreOwner {
      *
      * A throwing policy is a refusal, never an admission.
      */
-    permitsRead(peer, audience) {
-        const request = { type: 'read', peer, audience: [...audience] };
+    permitsRead(peer, audience, key) {
+        // `key` is the join's opaque key, which `joinStore({ key })` documents
+        // as read by the host's policy; it was dropped here, so a key-gated
+        // room refused everyone (SDK audit 2026-10-11).
+        const request = (key === undefined ? { type: 'read', peer, audience: [...audience] } : { type: 'read', peer, audience: [...audience], key });
         try {
             return this.deps.authorize(request) === true;
         }

package/dist/store/types.d.ts

@@ -159,6 +159,12 @@ export type AccessRequest<A extends ActionSpec, I extends InputSpec> = {
     readonly type: 'read';
     readonly peer: string;
     readonly audience: readonly string[];
+    /**
+     * The opaque key the replica joined with (`joinStore({ key })`),
+     * carried on every later read decision for that subscription.
+     * Absent for the host's own player, which joins no wire.
+     */
+    readonly key?: string;
 } | {
     [K in keyof A]: {
         readonly type: 'action';

package/dist/stream.d.ts

@@ -97,13 +97,24 @@ export interface OpenStreamOptions {
      */
     lossy?: boolean;
 }
+/** Most frames a {@link LeafStream} buffers before its first consumer. */
+export declare const LEAF_STREAM_PENDING_MAX_FRAMES = 1024;
+/** Most bytes a {@link LeafStream} buffers before its first consumer. */
+export declare const LEAF_STREAM_PENDING_MAX_BYTES: number;
 /**
  * One open stream.
  *
  * Inbound payloads are delivered to `for await` consumers and to
  * {@link LeafStream.onMessage} listeners. Payloads that arrive before
  * anyone consumes them are buffered in arrival order, so a page that
- * opens a stream and awaits it a tick later loses nothing.
+ * opens a stream and awaits it a tick later loses nothing — up to
+ * {@link LEAF_STREAM_PENDING_MAX_FRAMES} frames and
+ * {@link LEAF_STREAM_PENDING_MAX_BYTES} bytes. Past either bound the
+ * OLDEST buffered frame is dropped and counted in
+ * {@link LeafStream.droppedBeforeConsumer} (a single frame larger than the
+ * byte bound is never buffered, and is counted there too): a stream used only to send
+ * (the store, netcode and region-link layers read inbound traffic
+ * elsewhere) must not keep every frame the peer sends for its lifetime.
  */
 export declare class LeafStream implements AsyncIterable<Uint8Array> {
     private readonly inner;
@@ -111,7 +122,11 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
     private readonly queues;
     private readonly listeners;
     private readonly pending;
+    private pendingBytes;
+    private dropped;
     private closed;
+    /** Why the SESSION closed this stream, when it did so for a leader change. */
+    private retiredBy;
     /**
      * This stream's wire id as a number, or `null` when the inner
      * object's `stream_id_hex()` was not hex.
@@ -144,6 +159,11 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
      * either would fail the id comparison too, loudly.
      */
     private readonly peerId;
+    /**
+     * Frames dropped from the pre-consumer buffer because no `for await`
+     * consumer or `onMessage` listener was attached and it was full.
+     */
+    get droppedBeforeConsumer(): number;
     /** The authenticated peer this stream is with, 16 lowercase hex. */
     get peerNode(): string;
     /**
@@ -169,6 +189,14 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
      * taken as an already-decoded payload, which is what a
      * host-supplied {@link LeafWasmStreamLike} may deliver.
      */
+    /**
+     * Hand the pre-consumer buffer over, emptying it — count included. The
+     * byte count stayed at the drained total, so after a consumer drained the
+     * buffer and detached, rebuffering tripped the byte cap almost at once
+     * and evicted all but the newest frame on nearly every arrival (code
+     * review 2026-10-11, BROWSER-1).
+     */
+    private drainPending;
     private receive;
     private decode;
 }

package/dist/stream.js

@@ -17,13 +17,24 @@ export class StreamIdentityError extends SessionError {
         this.name = 'StreamIdentityError';
     }
 }
+/** Most frames a {@link LeafStream} buffers before its first consumer. */
+export const LEAF_STREAM_PENDING_MAX_FRAMES = 1024;
+/** Most bytes a {@link LeafStream} buffers before its first consumer. */
+export const LEAF_STREAM_PENDING_MAX_BYTES = 1 << 20;
 /**
  * One open stream.
  *
  * Inbound payloads are delivered to `for await` consumers and to
  * {@link LeafStream.onMessage} listeners. Payloads that arrive before
  * anyone consumes them are buffered in arrival order, so a page that
- * opens a stream and awaits it a tick later loses nothing.
+ * opens a stream and awaits it a tick later loses nothing — up to
+ * {@link LEAF_STREAM_PENDING_MAX_FRAMES} frames and
+ * {@link LEAF_STREAM_PENDING_MAX_BYTES} bytes. Past either bound the
+ * OLDEST buffered frame is dropped and counted in
+ * {@link LeafStream.droppedBeforeConsumer} (a single frame larger than the
+ * byte bound is never buffered, and is counted there too): a stream used only to send
+ * (the store, netcode and region-link layers read inbound traffic
+ * elsewhere) must not keep every frame the peer sends for its lifetime.
  */
 export class LeafStream {
     inner;
@@ -31,7 +42,11 @@ export class LeafStream {
     queues = new Set();
     listeners = new Set();
     pending = [];
+    pendingBytes = 0;
+    dropped = 0;
     closed = false;
+    /** Why the SESSION closed this stream, when it did so for a leader change. */
+    retiredBy = null;
     /**
      * This stream's wire id as a number, or `null` when the inner
      * object's `stream_id_hex()` was not hex.
@@ -94,6 +109,13 @@ export class LeafStream {
         }
         inner.on_message((event) => this.receive(event));
     }
+    /**
+     * Frames dropped from the pre-consumer buffer because no `for await`
+     * consumer or `onMessage` listener was attached and it was full.
+     */
+    get droppedBeforeConsumer() {
+        return this.dropped;
+    }
     /** The authenticated peer this stream is with, 16 lowercase hex. */
     get peerNode() {
         return this.inner.peer_node_hex();
@@ -113,7 +135,7 @@ export class LeafStream {
     /** Send one payload. Fragmentation at `MAX_PAYLOAD_SIZE` is the leaf's. */
     async send(payload) {
         if (this.closed)
-            throw new SessionError('the stream is closed');
+            throw new SessionError(this.retiredBy ?? 'the stream is closed');
         try {
             await this.inner.send(payload);
         }
@@ -124,7 +146,7 @@ export class LeafStream {
     /** Listen for payloads. Returns a cancel handle. */
     onMessage(listener) {
         this.listeners.add(listener);
-        const buffered = this.pending.splice(0, this.pending.length);
+        const buffered = this.drainPending();
         for (const payload of buffered)
             listener(payload);
         return () => {
@@ -134,13 +156,26 @@ export class LeafStream {
     [Symbol.asyncIterator]() {
         const queue = new AsyncQueue(() => this.queues.delete(queue));
         this.queues.add(queue);
-        const buffered = this.pending.splice(0, this.pending.length);
+        const buffered = this.drainPending();
         for (const payload of buffered)
             queue.push(payload);
         if (this.closed)
             queue.end();
         return queue;
     }
+    /**
+     * @internal — the session closing this stream because the leader it
+     * was opened on is gone. Later sends fail with the leaf's own
+     * reopenable wording ("stale stream handle"), so a store that cached
+     * the stream reopens it on the new leader instead of failing every
+     * frame forever (SDK audit 2026-10-11).
+     */
+    retire(reason) {
+        if (this.closed)
+            return;
+        this.retiredBy = reason;
+        this.close();
+    }
     /** Close the stream and end every consumer. */
     close() {
         if (this.closed)
@@ -163,12 +198,39 @@ export class LeafStream {
      * taken as an already-decoded payload, which is what a
      * host-supplied {@link LeafWasmStreamLike} may deliver.
      */
+    /**
+     * Hand the pre-consumer buffer over, emptying it — count included. The
+     * byte count stayed at the drained total, so after a consumer drained the
+     * buffer and detached, rebuffering tripped the byte cap almost at once
+     * and evicted all but the newest frame on nearly every arrival (code
+     * review 2026-10-11, BROWSER-1).
+     */
+    drainPending() {
+        this.pendingBytes = 0;
+        return this.pending.splice(0, this.pending.length);
+    }
     receive(event) {
         const payload = this.decode(event);
         if (payload === null || this.closed)
             return;
         if (this.queues.size === 0 && this.listeners.size === 0) {
+            // A single frame over the byte cap is dropped and counted rather
+            // than buffered: the eviction loop below stops at one frame, so it
+            // would otherwise sit there past the cap (cubic review of PR #1228).
+            if (payload.byteLength > LEAF_STREAM_PENDING_MAX_BYTES) {
+                this.dropped += 1;
+                return;
+            }
             this.pending.push(payload);
+            this.pendingBytes += payload.byteLength;
+            // Bounded (SDK audit 2026-10-11): unbounded, an unread stream grew
+            // at the peer's send rate until the tab ran out of memory.
+            while (this.pending.length > LEAF_STREAM_PENDING_MAX_FRAMES ||
+                this.pendingBytes > LEAF_STREAM_PENDING_MAX_BYTES) {
+                const oldest = this.pending.shift();
+                this.pendingBytes -= oldest.byteLength;
+                this.dropped += 1;
+            }
             return;
         }
         for (const listener of this.listeners) {

package/dist/udp-probe.d.ts

@@ -53,7 +53,12 @@ export type StunProbeOutcome =
     readonly type: 'unanswered';
     readonly detail: string;
 }
-/** The probe was not run — no address to aim at, or it was disabled. */
+/**
+ * The probe established nothing either way: it was not run (no address
+ * to aim at, disabled, or the connection failed before gathering), or
+ * it ran and was inconclusive (gathering completed with neither an
+ * answer nor a "no response" report). Never evidence of blocked UDP.
+ */
  | {
     readonly type: 'notRun';
     readonly reason: string;
@@ -76,6 +81,10 @@ export type ProbeEvent = {
 /** The probe connection's ICE state became `failed`. */
  | {
     readonly ice: 'failed';
+}
+/** Gathering completed (the end-of-candidates signal). */
+ | {
+    readonly gathering: 'complete';
 };
 /**
  * Is this candidate line server-reflexive? The `typ` token followed by
@@ -98,10 +107,19 @@ export declare function probeEventAnswers(event: ProbeEvent): boolean;
  * event answers, `notRun` when the engine failed the connection before
  * gathering a single candidate (nothing was sent, so silence is not
  * evidence — measured: Firefox without a media permission on an
- * IPv6-only network with no IPv4 route), `unanswered` otherwise. The
- * Rust probe's `probe_verdict`, the same three answers.
+ * IPv6-only network with no IPv4 route) or when gathering completed with
+ * neither an answer nor a "no response" report (inconclusive),
+ * `unanswered` otherwise. The Rust probe's `probe_verdict`, the same
+ * three answers.
  */
 export declare function stunProbeVerdict(events: readonly ProbeEvent[]): 'answered' | 'unanswered' | 'notRun';
+/**
+ * Is this a `typ host` candidate whose address is a literal publicly
+ * routable IP (not private, loopback, link-local, CGNAT, unique-local or
+ * unspecified)? An obfuscated `.local` address is not known public. Mirrors
+ * the Rust `host_candidate_is_public`.
+ */
+export declare function hostCandidateIsPublic(line: string): boolean;
 /** {@link probeEventAnswers} over everything one probe reported. */
 export declare function stunProbeAnswered(events: readonly ProbeEvent[]): boolean;
 /** One endpoint and what probing it established. */

package/dist/udp-probe.js

@@ -61,15 +61,71 @@ export function probeEventAnswers(event) {
  * event answers, `notRun` when the engine failed the connection before
  * gathering a single candidate (nothing was sent, so silence is not
  * evidence — measured: Firefox without a media permission on an
- * IPv6-only network with no IPv4 route), `unanswered` otherwise. The
- * Rust probe's `probe_verdict`, the same three answers.
+ * IPv6-only network with no IPv4 route) or when gathering completed with
+ * neither an answer nor a "no response" report (inconclusive),
+ * `unanswered` otherwise. The Rust probe's `probe_verdict`, the same
+ * three answers.
  */
 export function stunProbeVerdict(events) {
     if (events.some(probeEventAnswers))
         return 'answered';
     const gathered = events.some((event) => 'candidate' in event);
     const failed = events.some((event) => 'ice' in event && event.ice === 'failed');
-    return failed && !gathered ? 'notRun' : 'unanswered';
+    if (failed && !gathered)
+        return 'notRun';
+    // Gathering that COMPLETED with no reflexive candidate and no "no
+    // response" report is inconclusive ONLY when a host candidate carried a
+    // literal public address: an engine may suppress a srflx equal to it, so
+    // a host with no NAT would otherwise read as `udp-blocked` (SDK audit
+    // 2026-10-11). Behind NAT the srflx is never suppressed, so its absence
+    // is silence — what blocked UDP looks like in Chromium (browser matrix,
+    // PR #1228). Same rule as the Rust `probe_verdict`.
+    const completed = events.some((event) => 'gathering' in event);
+    const reportedNoResponse = events.some((event) => 'error' in event && event.error >= STUN_NO_RESPONSE_CODE);
+    const publicHost = events.some((event) => 'candidate' in event && hostCandidateIsPublic(event.candidate));
+    return completed && !reportedNoResponse && publicHost ? 'notRun' : 'unanswered';
+}
+/**
+ * Is this a `typ host` candidate whose address is a literal publicly
+ * routable IP (not private, loopback, link-local, CGNAT, unique-local or
+ * unspecified)? An obfuscated `.local` address is not known public. Mirrors
+ * the Rust `host_candidate_is_public`.
+ */
+export function hostCandidateIsPublic(line) {
+    const tokens = line.trim().split(/\s+/);
+    let host = false;
+    for (let i = 0; i + 1 < tokens.length; i += 1) {
+        if (tokens[i] === 'typ' && tokens[i + 1] === 'host')
+            host = true;
+    }
+    const addr = tokens[4];
+    if (!host || addr === undefined)
+        return false;
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+    if (v4 !== null) {
+        const o = v4.slice(1).map(Number);
+        if (o.some((n) => n > 255))
+            return false;
+        const [a, b] = o;
+        const isPrivate = a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+        const loopback = a === 127;
+        const linkLocal = a === 169 && b === 254;
+        const unspecified = o.every((n) => n === 0);
+        const broadcast = o.every((n) => n === 255);
+        const cgnat = a === 100 && (b & 0xc0) === 64;
+        return !(isPrivate || loopback || linkLocal || unspecified || broadcast || cgnat);
+    }
+    if (!addr.includes(':') || !/^[0-9a-f:.]+$/i.test(addr))
+        return false;
+    const lower = addr.toLowerCase();
+    if (lower === '::' || lower === '::1')
+        return false;
+    const first = Number.parseInt(lower.startsWith(':') ? '0' : lower.split(':')[0] ?? '0', 16);
+    if (Number.isNaN(first))
+        return false;
+    const uniqueLocal = (first & 0xfe00) === 0xfc00;
+    const linkLocalV6 = (first & 0xffc0) === 0xfe80;
+    return !(uniqueLocal || linkLocalV6);
 }
 /** {@link probeEventAnswers} over everything one probe reported. */
 export function stunProbeAnswered(events) {
@@ -154,11 +210,24 @@ export async function probeStunBinding(rtcAddr, options = {}) {
     // load-bearing rather than a safety net.
     let noResponse = null;
     const timer = setTimeout(() => settle({ type: 'unanswered', detail: noResponse ?? 'no answer inside the probe deadline' }), timeoutMs);
+    // Completion with no reflexive candidate is inconclusive only when no
+    // "no response" report came AND a host candidate carried a literal
+    // public address: libwebrtc drops a reflexive candidate equal to it, so
+    // the anchor can have answered with nothing visible. Behind NAT, or
+    // with only `.local` hosts (Firefox, which also makes no "no response"
+    // report), the srflx is never suppressed and its absence is silence
+    // (`stunProbeVerdict`, the same rule).
+    let publicHost = false;
     const gatheringDone = () => {
-        settle({
-            type: 'unanswered',
-            detail: noResponse ?? 'gathering completed with no reflexive candidate',
-        });
+        if (noResponse === null && publicHost) {
+            settle({
+                type: 'notRun',
+                reason: 'gathering completed beside a public host with no reflexive candidate and no "no response" report: ' +
+                    'inconclusive',
+            });
+            return;
+        }
+        settle({ type: 'unanswered', detail: noResponse ?? 'gathering completed with no reflexive candidate' });
     };
     // Did the engine gather anything at all? A connection it fails
     // before the first candidate is one it could not gather for, and
@@ -179,6 +248,8 @@ export async function probeStunBinding(rtcAddr, options = {}) {
             return;
         }
         gathered = true;
+        if (hostCandidateIsPublic(candidate.candidate))
+            publicHost = true;
         // Host candidates are gathered regardless of what the network does
         // to UDP — Chromium even hides them behind an mDNS `.local` name —
         // so only a reflexive one is evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/browser",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Browser-native Net mesh leaf \u2014 idiomatic TypeScript over the net-mesh-leaf wasm node",
   "type": "module",
   "main": "dist/index.js",