p2party 0.14.2 → 0.14.7

package/lib/utils/constants.d.ts

@@ -1,3 +1,5 @@
+/** One bound shared by room admission and all signaling lifecycle registries. */
+export declare const MAX_ACTIVE_SIGNALING_ROOMS = 256;
 export declare const MESSAGE_LEN: number;
 export declare const MAX_MESSAGE_SIZE: number;
 export declare const MAX_BUFFERED_AMOUNT: number;
@@ -49,9 +51,19 @@ export declare const MAX_RETRANSMITS = 5;
 export declare const RETRANSMIT_TIMEOUT_MS = 2000;
 export declare const CHANNEL_OPEN_TIMEOUT_MS = 3000;
 export declare const CHANNEL_OPEN_POLL_MS = 25;
+export declare const PEER_ADMISSION_WAIT_MS = 12000;
 export declare const RECONNECT_RESUME_TIMEOUT_MS = 30000;
 export declare const RECONNECT_RESUME_POLL_MS = 500;
 export declare const MAX_RESUME_ATTEMPTS = 3;
+export declare const RATCHET_GATE_WAIT_TIMEOUT_MS = 45000;
+export declare const SIGNALING_HEARTBEAT_TIMEOUT_MS = 25000;
+export declare const SIGNALING_HEARTBEAT_CHECK_MS = 5000;
+export declare const REBIND_AUTHENTICATION_DEADLINE_MS = 10000;
+export declare const PC_OPERATION_POLL_MS = 100;
+export declare const PC_OPERATION_TIMEOUT_MS = 8000;
 export declare const HASH_WINDOW_BYTES: number;
 export declare const HASH_WASM_CHUNK_BYTES: number;
 export declare const OPFS_REASSEMBLE_DIR = "p2party-reassembled";
+export declare const ROOM_ROSTER_RECONCILE_DELAYS_MS: number[];
+export declare const ROOM_ROSTER_RECONCILE_MAX_ATTEMPTS = 8;
+export declare const ROOM_ROSTER_RECONCILE_DEBOUNCE_MS = 4000;

package/lib/utils/correlationId.d.ts

@@ -0,0 +1,4 @@
+export declare const UUID_V4_PATTERN: RegExp;
+export declare const isUuidV4: (value: string) => boolean;
+/** One SSOT for every request/ack correlation nonce carried on the wire. */
+export declare const randomUuidV4: () => string;

package/lib/utils/identityRestore.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Identity restore, expressed as effects rather than as calls into the store,
+ * the database worker and the signaling API.
+ *
+ * Restoring a recovery phrase rotates the Ed25519 account key underneath a
+ * running mesh, so the order of what happens is the whole of the security
+ * argument: transports carrying the outgoing identity are terminal before the
+ * incoming one is adopted, and nothing is torn down until a key has actually
+ * been derived. Keeping that order here, behind an injectable surface, is what
+ * makes it assertable without a socket, a WebRTC stack or IndexedDB.
+ */
+import type { TerminalSettlementStep } from "./terminalSettlement";
+/**
+ * A recovery phrase that cannot derive an identity: an unknown word, the wrong
+ * number of words, or a failed checksum. Typed so a caller can tell a mistyped
+ * phrase apart from a storage or transport failure and keep the user in the
+ * form instead of showing them a purge.
+ */
+export declare class InvalidRecoveryPhraseError extends Error {
+    constructor(message: string);
+}
+/** Raw Ed25519 account key material, owned by the restore that derived it. */
+export interface DerivedIdentityKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export interface IdentityRestoreEffects {
+    /** Stretch the phrase into the Ed25519 identity it encodes (argon2id). */
+    readonly deriveIdentity: (mnemonic: string, password?: string) => Promise<DerivedIdentityKeyPair>;
+    /**
+     * Run the identity swap under the same exclusive boundary a purge uses, so
+     * no connection attempt, room operation or bootstrap can interleave with it.
+     */
+    readonly runExclusive: <T>(operation: () => Promise<T>) => Promise<T>;
+    readonly disconnectSignaling: TerminalSettlementStep;
+    /**
+     * Close every authenticated WebRTC transport. Rooms, their messages and the
+     * address book are kept: this rotates the account key, it does not purge the
+     * account.
+     */
+    readonly teardownRooms: TerminalSettlementStep;
+    /**
+     * D2=B: the X25519 identity is cross-signed by the outgoing Ed25519 key, so
+     * it must not outlive it. The next bootstrap regenerates and re-cross-signs.
+     */
+    readonly deleteIdentityX25519: TerminalSettlementStep;
+    readonly writeIdentityEd25519: (identity: DerivedIdentityKeyPair) => void | Promise<void>;
+    /** Record that this key came from a phrase, so it can be backed up again. */
+    readonly recordDerivation: TerminalSettlementStep;
+    /** Drop the previous identity's peer id, challenge and signature. */
+    readonly resetIdentityState: TerminalSettlementStep;
+    readonly adoptIdentity: (publicKey: string, secretKey: string) => void;
+}
+/** What a caller needs to show the user, and nothing that could identify them further. */
+export interface RestoredIdentity {
+    publicKey: string;
+}
+export interface CreateRecoverableIdentityOptions {
+    /** Entropy bits: 128 gives a 12-word phrase, 256 a 24-word one. */
+    strength?: 128 | 256;
+    /**
+     * Folded into the derivation as the argon2id salt. It is never stored and
+     * never checked, so restoring with a different password silently produces a
+     * different identity — the phrase alone is not enough to get back in.
+     */
+    password?: string;
+}
+export interface CreatedRecoverableIdentity extends RestoredIdentity {
+    /**
+     * Shown to the user exactly once. Neither the SDK nor its storage keeps a
+     * copy, by design: a phrase at rest is the whole identity at rest.
+     */
+    mnemonic: string;
+}
+/**
+ * Adopt the identity a recovery phrase encodes, replacing whatever identity is
+ * currently in use.
+ *
+ * The phrase is checked, then derived, before any effect runs, so a mistyped
+ * phrase costs the caller nothing. Only then does the exclusive boundary open:
+ * signaling is disconnected, every room transport is brought to a terminal
+ * state, and the cross-signed X25519 identity is dropped — all three settle
+ * even if one of them fails, and a failure there aborts the swap rather than
+ * moving the identity out from under a transport that may still be live.
+ *
+ * The remaining steps are fail-fast in dependency order: the Ed25519 key is
+ * persisted first, because the derivation flag binds to whatever key is stored
+ * when it is written; the in-memory identity is adopted last, because an
+ * identity that could not be persisted must not survive only until a reload.
+ *
+ * @param effects - The storage, transport and state seams to drive
+ * @param mnemonic - The recovery phrase, in any transcription
+ * @param password - The optional passphrase the phrase was created with
+ * @returns The restored Ed25519 public key, hex-encoded
+ */
+export declare const restoreIdentityFromMnemonicWith: (effects: IdentityRestoreEffects, mnemonic: string, password?: string) => Promise<RestoredIdentity>;
+/**
+ * Generate a recovery phrase and adopt the identity it encodes, so the phrase
+ * the user writes down is provably the one that restores this account.
+ *
+ * The phrase is returned once and kept nowhere. A caller that loses it before
+ * the user has copied it has lost the only backup.
+ *
+ * @param effects - The storage, transport and state seams to drive
+ * @param options - Entropy bits and an optional passphrase
+ * @returns The phrase and the Ed25519 public key it now derives
+ */
+export declare const createRecoverableIdentityWith: (effects: IdentityRestoreEffects, options?: CreateRecoverableIdentityOptions) => Promise<CreatedRecoverableIdentity>;

package/lib/utils/interfaces.d.ts

@@ -5,6 +5,19 @@ export interface WebSocketMessagePongResponse {
     type: "pong";
     fromPeerId: string;
 }
+export interface WebSocketMessageLeaveRoomRequest {
+    type: "leaveRoom";
+    protocolVersion: 4;
+    fromPeerId: string;
+    roomUrl: string;
+    roomLeaveId: string;
+}
+export interface WebSocketMessageRoomLeftResponse {
+    type: "roomLeft";
+    protocolVersion: 4;
+    roomUrl: string;
+    roomLeaveId: string;
+}
 export interface WebSocketMessageChallengeRequest {
     type: "peerId";
     peerId: string;
@@ -23,28 +36,34 @@ export interface WebSocketMessageSuccessfulChallenge {
     type: "challenge";
     challengeId: string;
     protocolVersion: number;
-    username?: string;
-    credential?: string;
 }
 export interface WebSocketMessageRoomIdRequest {
     type: "room";
     fromPeerId: string;
     roomUrl: string;
-    protocolVersion: number;
+    /** Fresh request/response correlation nonce. Never reused across requests. */
+    roomRequestId: string;
+    protocolVersion: 4;
 }
 export interface TurnCredentials {
     urls: string[];
     username: string;
     credential: string;
-    ttl: number;
+    /**
+     * Absolute TURN REST expiry. It must equal the timestamp prefix authenticated
+     * inside `username`; carrying it explicitly lets clients schedule refresh
+     * without interpreting an undocumented deployment convention.
+     */
+    expiresAtUnixSeconds: number;
 }
 export interface WebSocketMessageRoomIdResponse {
     type: "roomId";
     roomId: string;
     roomUrl: string;
+    /** Exact echo of the request's fresh `roomRequestId`. */
+    roomRequestId: string;
     turnCredentials?: TurnCredentials;
-    /** Optional only so missing/pre-v3 server responses fail closed at runtime. */
-    protocolVersion?: number;
+    protocolVersion: 4;
 }
 export interface WebSocketMessageDescriptionSend {
     type: "description";

package/lib/utils/roomConnectAdmission.d.ts

@@ -0,0 +1,15 @@
+import type { RoomPolicyV1 } from "../roomPolicy";
+export interface RoomConnectAdmissionInput {
+    readonly existingPolicy?: RoomPolicyV1;
+    readonly persistedPolicy?: RoomPolicyV1;
+    readonly requestedPolicy?: RoomPolicyV1;
+    readonly providedPin?: unknown;
+    readonly hasTransientPin: boolean;
+}
+/**
+ * One pure admission decision for every public room-connect entry point.
+ *
+ * In particular, an empty Redux store does not imply a new no-PIN room when
+ * IndexedDB retains an immutable PIN policy for the same capability.
+ */
+export declare const resolveRoomConnectAdmission: ({ existingPolicy, persistedPolicy, requestedPolicy, providedPin, hasTransientPin, }: RoomConnectAdmissionInput) => RoomPolicyV1;

package/lib/utils/roomLeaveCoordinator.d.ts

@@ -0,0 +1,38 @@
+import type { WebSocketMessageLeaveRoomRequest, WebSocketMessageRoomLeftResponse } from "./interfaces";
+export declare const ROOM_LEAVE_ACK_TIMEOUT_MS = 2000;
+export declare const MAX_PENDING_ROOM_LEAVES = 256;
+export type RemoteRoomRevocationFailure = "no-current-socket" | "send-failed" | "ack-timeout" | "socket-closed" | "socket-replaced" | "ingress-rejected";
+/**
+ * Local room state and transports are already terminal when this is surfaced.
+ * It says only that authoritative unlinking at the rendezvous server was not
+ * confirmed; callers may safely forget the local room while reporting that
+ * narrower remote uncertainty.
+ */
+export declare class RemoteRoomRevocationUnconfirmedError extends Error {
+    readonly roomUrl: string;
+    readonly roomLeaveId: string;
+    readonly reason: RemoteRoomRevocationFailure;
+    constructor(roomUrl: string, roomLeaveId: string, reason: RemoteRoomRevocationFailure, detail?: string);
+}
+type SendRoomLeave = (request: WebSocketMessageLeaveRoomRequest) => void | Promise<unknown>;
+export declare const buildRoomLeaveRequest: (fromPeerId: string, roomUrl: string, roomLeaveId?: string) => WebSocketMessageLeaveRoomRequest;
+export interface RequestRoomLeaveOptions {
+    readonly timeoutMs?: number;
+    readonly roomLeaveId?: string;
+}
+/**
+ * Install correlation before sending, so even a synchronous in-memory server
+ * acknowledgement cannot outrun the waiter.
+ */
+export declare const requestRoomLeaveAcknowledgement: (fromPeerId: string, roomUrl: string, socketToken: object, send: SendRoomLeave, options?: RequestRoomLeaveOptions) => Promise<void>;
+export declare const hasExactRoomLeftShape: (message: WebSocketMessageRoomLeftResponse) => boolean;
+/** Parse only the tiny exact ack shape used by the socket fast path. */
+export declare const parseRoomLeftAcknowledgement: (data: unknown) => WebSocketMessageRoomLeftResponse | null;
+/**
+ * Settle only the exact socket+room+nonce waiter. The acknowledgement has no
+ * reducer side effect, so a duplicate or late frame cannot resurrect a room.
+ */
+export declare const acknowledgeRoomLeft: (message: WebSocketMessageRoomLeftResponse, socketToken: object) => boolean;
+export declare const cancelRoomLeavesForSocket: (socketToken: object, reason: Exclude<RemoteRoomRevocationFailure, "no-current-socket" | "send-failed" | "ack-timeout">) => number;
+export declare const pendingRoomLeaveCount: () => number;
+export {};

package/lib/utils/roomRequestCoordinator.d.ts

@@ -0,0 +1,104 @@
+import { MAX_ACTIVE_SIGNALING_ROOMS } from "./constants";
+import type { WebSocketMessageRoomIdRequest } from "./interfaces";
+export { MAX_ACTIVE_SIGNALING_ROOMS };
+export declare const MAX_PENDING_ROOM_REQUESTS = 256;
+export declare const MAX_ROOM_REQUEST_RETRY_WAITERS = 256;
+export declare const ROOM_RESPONSE_TIMEOUT_MS = 15000;
+export declare const SOCKET_PROOF_TIMEOUT_MS = 15000;
+export declare const TURN_REFRESH_LEAD_MS: number;
+export declare const MIN_TURN_REFRESH_DELAY_MS = 1000;
+export declare const TURN_REFRESH_RETRY_BASE_MS = 1000;
+export declare const MAX_TURN_REFRESH_RETRY_MS = 30000;
+export declare const MAX_TURN_REFRESH_ATTEMPTS = 8;
+export interface AppliedRoomResponse {
+    roomUrl: string;
+    roomId: string;
+    roomRequestId: string;
+    requestGeneration: number;
+    expiresAtUnixSeconds: number | null;
+}
+type SendRoomRequest = (request: WebSocketMessageRoomIdRequest) => void | Promise<unknown>;
+export interface RoomCredentialRefreshReservation {
+    readonly roomUrl: string;
+    readonly token: symbol;
+}
+export declare const buildRoomRequest: (peerId: string, roomUrl: string) => WebSocketMessageRoomIdRequest;
+/**
+ * Start one wire-bound room request, or join the exact in-flight request.
+ *
+ * A fresh UUID is carried on the wire and must be echoed by the server. Merely
+ * keeping a local generation would not distinguish an old same-room response
+ * that arrived during a later request.
+ */
+export declare const requestRoomResponse: (peerId: string, roomUrl: string, send: SendRoomRequest, options?: {
+    readonly timeoutMs?: number;
+}) => Promise<AppliedRoomResponse>;
+export interface PendingRoomResponseClaim {
+    readonly roomUrl: string;
+    readonly roomRequestId: string;
+    readonly requestGeneration: number;
+}
+/** Claim only the exact echoed UUID of the current single-flight request. */
+export declare const claimRoomResponse: (roomUrl: string, roomRequestId: string) => PendingRoomResponseClaim | null;
+export declare const completeRoomResponse: (response: AppliedRoomResponse) => boolean;
+export declare const rejectRoomResponse: (roomUrl: string, roomRequestId: string, error: Error) => boolean;
+export declare const pendingRoomRequestId: (roomUrl: string) => string | null;
+/** True only while the exact claimed response still owns its pending slot. */
+export declare const isRoomResponseClaimCurrent: (claim: PendingRoomResponseClaim) => boolean;
+export declare const waitForFreshSocketProof: (alreadyVerified: boolean, timeoutMs?: number, lifecycleEpoch?: number) => Promise<void>;
+export declare const markFreshSocketProof: (lifecycleEpoch?: number) => void;
+export declare const currentRoomRequestLifecycleEpoch: () => number;
+export declare const isRoomRequestLifecycleCurrent: (lifecycleEpoch: number) => boolean;
+export declare const waitForRoomRequestRetry: (roomUrl: string, lifecycleEpoch: number, delayMs: number) => Promise<void>;
+export declare const turnRefreshDelayMs: (expiresAtUnixSeconds: number, nowMs?: number, minimumDelayMs?: number) => number;
+export interface RoomCredentialRefreshOptions {
+    /** Test seam; production uses Date.now(). */
+    nowMs?: number;
+    /** Dynamic test seam for time that can advance while refresh is awaited. */
+    now?: () => number;
+    /** Test seams; production uses the bounded constants above. */
+    retryBaseMs?: number;
+    maxRetryMs?: number;
+    maxAttempts?: number;
+    minimumInitialDelayMs?: number;
+}
+export declare const turnRefreshRetryDelayMs: (attempt: number, remainingMs: number, options?: RoomCredentialRefreshOptions) => number;
+export declare const scheduleRoomCredentialRefresh: (roomUrl: string, expiresAtUnixSeconds: number | null, refresh: () => Promise<unknown>, expire?: () => void | Promise<void>, options?: RoomCredentialRefreshOptions, ownerToken?: symbol) => void;
+/**
+ * Preflight used immediately before publishing a room response.
+ *
+ * A replacement owns its existing slot; a STUN-only response needs no slot.
+ * Callers recheck after asynchronous live-PC configuration, then publish and
+ * schedule synchronously so the bound cannot change between those operations.
+ */
+export declare function canScheduleRoomCredentialRefresh(roomUrl: string, expiresAtUnixSeconds: number | null): boolean;
+export declare const reserveRoomCredentialRefresh: (roomUrl: string, expiresAtUnixSeconds: number | null) => RoomCredentialRefreshReservation;
+export declare const isRoomCredentialRefreshReservationCurrent: (reservation: RoomCredentialRefreshReservation) => boolean;
+export declare const releaseRoomCredentialRefreshReservation: (reservation: RoomCredentialRefreshReservation) => boolean;
+export declare const finalizeRoomCredentialRefresh: (reservation: RoomCredentialRefreshReservation, expiresAtUnixSeconds: number | null, refresh: () => Promise<unknown>, expire?: () => void | Promise<void>, options?: RoomCredentialRefreshOptions) => void;
+/**
+ * Release whichever refresh object this exact response still owns.
+ *
+ * A stale handler must never clear a replacement reservation/timer installed
+ * for the same room URL after delete/reactivate or socket reset.
+ */
+export declare const clearRoomCredentialRefreshIfOwned: (reservation: RoomCredentialRefreshReservation) => boolean;
+export declare const clearRoomCredentialRefresh: (roomUrl: string) => void;
+/** Cancel every coordinator handle owned by one retained room. */
+export declare const cancelRoomRequestLifecycle: (roomUrl: string, reason?: string) => void;
+/**
+ * Socket teardown invalidates responses and fails closed on managed TURN.
+ *
+ * With no authenticated path available to refresh, keeping a credential timer
+ * but losing its refresh context risks stale use after background suspension.
+ * Remove the managed bundle now; a later proof repopulates it before repair.
+ */
+export declare const resetRoomRequestLifecycle: (reason?: string) => void;
+/** Test-only observability without exposing mutable coordinator maps. */
+export declare const roomRequestCoordinatorCounts: () => {
+    pending: number;
+    proofWaiters: number;
+    retryWaiters: number;
+    refreshTimers: number;
+    refreshReservations: number;
+};

package/lib/utils/roomRosterReconciler.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Bounded "is anyone still there?" retries for a room that has nobody in it.
+ *
+ * Every roster request this SDK sends is caused by an event: a room join, a
+ * peer introduction from the server, an edge teardown that re-dials. That is
+ * enough while events keep arriving, and nothing at all once they stop. A
+ * socket can be connected and identity-verified, its room still active, and
+ * its roster empty for good — no peer to hear from, no teardown left to fire,
+ * so no event that would ask again. Both sides then sit in a healthy-looking
+ * room, alone, until the user reloads the page.
+ *
+ * The property this restores is deliberately weak and deliberately bounded: a
+ * verified socket in an active room with nobody authenticated on it asks the
+ * server for its peer list again on a backoff, a capped number of times, and
+ * stops the moment anything changes. It is not a keepalive and not a repair
+ * loop — a peers request is idempotent at the server (it re-introduces this
+ * client to the room's live members, which is exactly what a stranded room
+ * needs) and the caller still owns whether one may be sent at all.
+ *
+ * Store-free on purpose: the caller injects the timeout scheduler and decides,
+ * at each attempt, whether the room is still stranded. Nothing here reads a
+ * clock, a store or a browser global, so the whole backoff is exercisable in
+ * virtual time.
+ */
+/**
+ * Runs one reconciliation attempt for a room. Returns whether the room is
+ * still stranded and the backoff should continue; `false` retires it.
+ */
+export type RoomRosterReconcileTick = (roomId: string) => boolean;
+export interface RoomRosterReconcilerScheduler<Handle> {
+    readonly setTimeout: (callback: () => void, delayMs: number) => Handle;
+    readonly clearTimeout: (handle: Handle) => void;
+}
+export interface RoomRosterReconcilerOptions<Handle> {
+    readonly schedule: RoomRosterReconcilerScheduler<Handle>;
+    /** Delay before attempt n; the last entry is the cap for every attempt after. */
+    readonly delaysMs: readonly number[];
+    /** Total attempts allowed for one uninterrupted strand. */
+    readonly maxAttempts: number;
+}
+export interface RoomRosterReconciler {
+    /**
+     * Report that a room is stranded. Idempotent: a room already under a backoff
+     * keeps its schedule and its attempt count, and only its tick is refreshed,
+     * so repeated observations can never rewind the backoff or stack timers. A
+     * room that already spent its attempts stays retired until `cancel`.
+     */
+    arm(roomId: string, tick: RoomRosterReconcileTick): void;
+    /** Forget a room: releases its timer and resets its attempt budget. */
+    cancel(roomId: string): void;
+    /** Forget every room, for a lost socket or a purged store. */
+    cancelAll(): void;
+    /** Rooms this reconciler still tracks, retired ones included. */
+    armedRooms(): readonly string[];
+}
+export declare const createRoomRosterReconciler: <Handle>(options: RoomRosterReconcilerOptions<Handle>) => RoomRosterReconciler;
+/** The shape of a room this predicate needs; a superset of the reducer's. */
+export interface ReconcilableRoom {
+    readonly id: string;
+    readonly signalingActive?: boolean;
+    readonly peers: readonly {
+        readonly peerId: string;
+    }[];
+    readonly handshakeStatusByPeer?: Readonly<Record<string, {
+        readonly status: string;
+    } | undefined>>;
+}
+export interface ReconcilableSocket {
+    readonly isConnected: boolean;
+    readonly isVerified: boolean;
+}
+/**
+ * Whether a room is worth asking about again.
+ *
+ * "Nobody to talk to" is not the same as "no peers": a roster full of edges
+ * that never finished authenticating is just as empty in practice, and the
+ * server re-introducing this client is what gives those edges a fresh start.
+ * A room the user left (`signalingActive === false`, which `deleteRoom` sets),
+ * a room with no signaling identity yet, and any socket that is not both
+ * connected and verified are all excluded — a request on those either cannot
+ * be sent or would be an unwanted rejoin.
+ */
+export declare const isRoomRosterStranded: (room: ReconcilableRoom, socket: ReconcilableSocket) => boolean;

package/lib/utils/sdpFingerprint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Raw bytes of the `a=fingerprint:sha-256 XX:XX:...` line in an SDP blob.
+ * Throws if no sha-256 fingerprint attribute is present, or if the one found
+ * doesn't decode to exactly 32 bytes.
+ */
+export declare const parseFingerprintFromSdp: (sdp: string) => Uint8Array;

package/lib/utils/signalingAttemptLifecycle.d.ts

@@ -0,0 +1,33 @@
+export interface SignalingAttempt {
+    readonly token: symbol;
+    readonly cancelled: Promise<void>;
+}
+/**
+ * SSOT for socket-attempt ownership, prompt cancellation, and serialized
+ * identity bootstrap. Cancellation settles independently of a blocked
+ * IndexedDB/crypto operation; the bootstrap lock remains held until that
+ * operation unwinds, so its replacement cannot race identity mutation.
+ */
+export declare class SignalingAttemptLifecycle {
+    private activeToken;
+    private cancelCurrent;
+    private identityPurgeRequests;
+    private readonly bootstrapMutex;
+    begin(label: string): SignalingAttempt;
+    isCurrent(token: symbol): boolean;
+    hasActiveAttempt(): boolean;
+    assertCurrent(token: symbol): void;
+    addCancellationEffect(token: symbol, effect: () => void): boolean;
+    disarmCancellation(token: symbol): boolean;
+    clear(token: symbol): boolean;
+    cancelActive(): void;
+    isIdentityPurgeActive(): boolean;
+    acquireBootstrap(token: symbol): Promise<() => void>;
+    /**
+     * Cancel any socket/bootstrap attempt, then enter the same exclusive
+     * identity boundary used by bootstrap. Purge uses this so no cancelled
+     * bootstrap can persist or dispatch an identity after deletion.
+     */
+    cancelAndAcquireBootstrap(): Promise<() => void>;
+}
+export declare const signalingAttemptLifecycle: SignalingAttemptLifecycle;

package/lib/utils/signalingAuth.d.ts

@@ -1,8 +1,27 @@
-import type { WebSocketMessageChallengeRequest, WebSocketMessageSuccessfulChallenge } from "./interfaces";
+import type { TurnCredentials, WebSocketMessageChallengeRequest, WebSocketMessageSuccessfulChallenge } from "./interfaces";
+export declare const MIN_TURN_CREDENTIAL_REMAINING_SECONDS = 30;
+export declare const MAX_TURN_CREDENTIAL_LIFETIME_SECONDS: number;
+/** Stale bearer-shaped key fields never authenticate a replacement socket. */
+export declare const hasCurrentSocketProof: (keyPair: {
+    peerId: string;
+    challenge: string;
+    signature: string;
+}, signalingServer: {
+    isConnected: boolean;
+    isVerified: boolean;
+}) => boolean;
 /**
  * Exact protocol-v3 server challenge. Legacy reconnect credentials are
  * deliberately not accepted: every WebSocket must prove possession anew.
  */
 export declare const isFreshV3Challenge: (value: unknown) => value is WebSocketMessageChallengeRequest;
-/** Exact protocol-v3 proof-success response, with an all-or-none TURN pair. */
+/** Exact protocol-v3 proof-success response. TURN is issued only at room join. */
 export declare const isV3ChallengeSuccess: (value: unknown) => value is WebSocketMessageSuccessfulChallenge;
+/**
+ * Decode the one nested TURN credential object used by room responses.
+ *
+ * The server controls the relay, but only bounded `turn:`/`turns:` URIs may
+ * reach the browser ICE stack. Rejecting the complete object on one malformed
+ * field keeps this a closed wire contract rather than a best-effort filter.
+ */
+export declare const parseTurnCredentials: (value: unknown, nowMs?: number, expectedPublicKey?: string) => TurnCredentials | null;

package/lib/utils/signalingBounds.d.ts

@@ -4,6 +4,12 @@ export declare const MAX_ICE_CANDIDATE_CHARS = 4096;
 export declare const MAX_ICE_FIELD_CHARS = 256;
 export declare const MAX_SIGNALING_LABELS = 64;
 export declare const MAX_DATA_CHANNEL_LABEL_CHARS = 193;
+/** Per-client legacy mesh edge cap; also bounds cumulative server roster state. */
+export declare const MAX_SIGNALING_ROOM_PEERS = 64;
+/** At most 64 active logical channels per bounded room edge. */
+export declare const MAX_SIGNALING_ROOM_CHANNELS: number;
 export declare const isBoundedDescription: (description: RTCSessionDescription | RTCSessionDescriptionInit) => boolean;
 export declare const isBoundedIceCandidate: (candidate: RTCIceCandidateInit | RTCIceCandidate) => boolean;
 export declare const areBoundedDataChannelLabels: (labels: unknown) => labels is string[];
+/** Legacy connection signaling negotiates only the persistent handshake lane. */
+export declare const areCanonicalConnectionLabels: (labels: unknown) => labels is ["main"];

package/lib/utils/signalingFrame.d.ts

@@ -0,0 +1,21 @@
+import type { BaseQueryApi } from "@reduxjs/toolkit/query";
+import type { WebSocketPeerConnectionParams } from "./interfaces";
+export type WebSocketBaseResult = {
+    data: undefined;
+} | {
+    error: string;
+};
+type SignalingQueryApi = Pick<BaseQueryApi, "dispatch" | "getState">;
+type SignalingSocket = Pick<WebSocket, "readyState" | "send">;
+export interface AuthenticatedSignalingFrame<Content extends {
+    fromPeerId: string;
+} = {
+    fromPeerId: string;
+}> {
+    content: Content;
+}
+export declare const sendAuthenticatedSignalingFrame: <Content extends {
+    fromPeerId: string;
+}>(socket: SignalingSocket, message: AuthenticatedSignalingFrame<Content>, api: SignalingQueryApi, isCurrentSocket: () => boolean) => WebSocketBaseResult;
+export declare const sendPeerConnectionRequest: (socket: SignalingSocket, { peerId, peerPublicKey, roomId }: WebSocketPeerConnectionParams, api: SignalingQueryApi, isCurrentSocket: () => boolean) => WebSocketBaseResult;
+export {};

package/lib/utils/signalingHeartbeatWatchdog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Wall-clock watchdog over the signaling server's heartbeats.
+ *
+ * A WebSocket that the platform silently half-opened (page frozen with the
+ * radio off, NAT binding dropped) fires no `close` event until the TCP stack
+ * notices, which can take minutes. Meanwhile the server, which pings on a
+ * fixed interval, has already closed its end. This watchdog owns no browser
+ * globals: the caller injects the clock, the interval scheduler and the wake
+ * event source, so it is exactly testable and inert outside a browser.
+ *
+ * `check()` runs on the interval and immediately on every wake event
+ * (`visibilitychange` while visible, `pageshow`, `online`, `focus`), because
+ * timers are throttled or suspended while a page is hidden and the first
+ * useful moment to notice a dead socket is the moment the page wakes up.
+ */
+export type SignalingWakeEventName = "visibilitychange" | "pageshow" | "online" | "focus";
+export interface SignalingHeartbeatWatchdogScheduler<Handle> {
+    readonly setInterval: (callback: () => void, intervalMs: number) => Handle;
+    readonly clearInterval: (handle: Handle) => void;
+}
+export interface SignalingHeartbeatWatchdogEnv {
+    readonly addListener: (name: SignalingWakeEventName, listener: () => void) => void;
+    readonly removeListener: (name: SignalingWakeEventName, listener: () => void) => void;
+    /** Consulted on `visibilitychange`; a page going hidden is not a wake. */
+    readonly isVisible: () => boolean;
+}
+export interface SignalingHeartbeatWatchdogOptions<Handle> {
+    /** Wall clock in milliseconds; must keep advancing while the page sleeps. */
+    readonly now: () => number;
+    readonly timeoutMs: number;
+    readonly checkEveryMs: number;
+    readonly schedule: SignalingHeartbeatWatchdogScheduler<Handle>;
+    readonly env?: SignalingHeartbeatWatchdogEnv;
+    /** Invoked at most once; the watchdog has already stopped itself. */
+    readonly onDead: () => void;
+}
+export interface SignalingHeartbeatWatchdog {
+    /** Record that a server heartbeat was just answered. */
+    beat(): void;
+    /** Declare the socket dead if the heartbeat window has elapsed. */
+    check(): void;
+    /** Release the interval and wake listeners; idempotent and terminal. */
+    stop(): void;
+}
+export declare const createSignalingHeartbeatWatchdog: <Handle>(options: SignalingHeartbeatWatchdogOptions<Handle>) => SignalingHeartbeatWatchdog;

package/lib/utils/signalingIngressQueue.d.ts

@@ -0,0 +1,49 @@
+export declare const MAX_SIGNALING_INGRESS_BACKLOG = 128;
+export declare const MAX_SIGNALING_INGRESS_BYTES: number;
+export type SignalingHeartbeatKind = "raw" | "json";
+/**
+ * Heartbeats bypass protocol work so an ICE/IndexedDB operation cannot make a
+ * healthy client miss the server timeout. Parsing is restricted to a tiny
+ * input and the JSON form must be exactly `{type:"ping"}`.
+ */
+export declare const classifySignalingHeartbeat: (data: unknown) => SignalingHeartbeatKind | null;
+export interface SignalingHeartbeatResponders {
+    readonly raw: () => void;
+    readonly json: () => void;
+}
+/** Answer one exact heartbeat synchronously; return false for protocol data. */
+export declare const answerImmediateSignalingHeartbeat: (data: unknown, responders: SignalingHeartbeatResponders) => boolean;
+export interface SignalingIngressQueueOptions {
+    readonly maxPending?: number;
+    readonly maxPendingBytes?: number;
+    readonly onOverflow: () => void;
+    readonly onTaskError?: (error: unknown) => void;
+}
+/**
+ * Synchronously revocable ownership for handlers already running on a socket.
+ * Closing a WebSocket is asynchronous, so exact-socket identity alone remains
+ * true until `close`; this lease makes overflow/oversize rejection immediate.
+ */
+export declare class SignalingSocketIngressLease {
+    #private;
+    isCurrent(ownsSocket: () => boolean): boolean;
+    invalidate(): void;
+}
+/**
+ * A socket-local, bounded FIFO for signaling frames.
+ *
+ * WebSocket EventTarget ignores promises returned by `onmessage`; assigning an
+ * async handler therefore starts unbounded concurrent protocol and IndexedDB
+ * work. This queue preserves wire order and closes admission before invoking
+ * the overflow callback, so a synchronous burst cannot schedule more work
+ * while the socket close handshake is in flight.
+ */
+export declare class SignalingIngressQueue {
+    #private;
+    constructor(options: SignalingIngressQueueOptions);
+    get pendingCount(): number;
+    get pendingBytes(): number;
+    get isClosed(): boolean;
+    enqueue(task: () => void | Promise<void>, byteLength?: number): boolean;
+    close(): void;
+}