svelte-realtime 0.5.0-next.21 → 0.5.0-next.22

package/README.md

@@ -1815,6 +1815,8 @@ For custom lock implementations, the option is forwarded as the third argument:
 
 `live.push({ userId }, event, data, options?)` sends a server-initiated request to a connected user and awaits the reply. Routes through a per-instance userId -> WebSocket registry maintained by a small pair of hooks.
 
+> **Trust model:** `live.push` and `live.notify` are **server-trust primitives**. The `userId` you pass is whatever you pass; the framework does NOT check that the calling context is allowed to address that user. If your call site interpolates a wire-supplied value, read [Trust model: target.userId is whatever the caller passes](#trust-model-targetuserid-is-whatever-the-caller-passes) below before shipping.
+
 ```js
 // hooks.ws.js - wire the registry once
 import { pushHooks } from 'svelte-realtime/server';
@@ -1888,6 +1890,60 @@ Multi-device users see most-recent-connection-wins routing within each instance,
 
 `onPush(event, handler)` multiplexes multiple events over the adapter's single `onRequest` channel. Returning a value sends it as the reply; throwing rejects the server-side promise. Returns an unsubscribe function.
 
+### Trust model: target.userId is whatever the caller passes
+
+`live.push` and `live.notify` are **server-trust primitives**. Calling `live.push({ userId: someId }, event, data)` delivers `event` to whichever connection is registered under `someId`, full stop. The framework does NOT check that the server context invoking the push is allowed to address that user. It cannot - your authorization model lives outside the framework.
+
+This matters most when a message handler interpolates a wire-supplied target:
+
+```js
+// BUG: `msg.to` is client-controlled. Any authenticated user can push
+// arbitrary events to any other user - including admins, including
+// users in other tenants.
+export const dm = live(async (ctx, msg) => {
+  await live.notify({ userId: msg.to }, 'message', {
+    from: ctx.user.id,
+    text: msg.text
+  });
+});
+```
+
+The exploit shape is one line of client code: `dm.invoke({ to: 'admin-1', text: 'fake admin notification' })`. The fix is a tiny ownership check at the handler boundary - keep it generic and reuse it everywhere the handler routes to a `userId` from the wire:
+
+```js
+import { live, RpcError } from 'svelte-realtime/server';
+
+function mustOwnUser(ctx, targetUserId) {
+  if (ctx.user?.id === targetUserId) return;        // self-targeted (allowed)
+  if (ctx.user?.role === 'admin') return;           // admins can address anyone
+  if (sameTenant(ctx.user, targetUserId)) return;   // tenant peers
+  throw new RpcError('FORBIDDEN', 'You cannot push to that user');
+}
+
+export const dm = live(async (ctx, msg) => {
+  mustOwnUser(ctx, msg.to); // <-- decision lives here, not in live.push
+  await live.notify({ userId: msg.to }, 'message', {
+    from: ctx.user.id,
+    text: msg.text
+  });
+});
+```
+
+The rule of thumb: every `userId` you hand to `live.push` / `live.notify` must come from a value the **server** trusts. Safe sources:
+
+- `ctx.user.id` - you put it there in `upgrade()`; the framework guarantees provenance.
+- A database row your server just looked up (the DB is server-trusted).
+- A cron job's iteration target (cron payloads are server-authored).
+- A webhook payload **after** you've verified the source and confirmed it's allowed to address that userId. The userId field of an unverified third-party webhook is just another wire value.
+
+Unsafe sources without an ownership check:
+
+- `msg.targetUserId`, `payload.to`, `args.recipient` - any field that arrived on the WebSocket wire.
+- `searchParams.get('user')` on a webhook endpoint - same shape, different transport.
+- A row id chosen by a client even if you fetched the row server-side - the row is trusted, but the choice of WHICH row to fetch was not.
+
+The same contract applies to any future push-target shape (`{ group, role, tenant }`, etc.): the framework treats the target as an instruction, not as an authorization claim. Authorization is your handler's job; the framework is the delivery primitive.
+
 ### Fire-and-forget: `live.notify`
 
 For server-initiated events where you don't need a reply - progress notifications, "upload complete" pings, "new message available" hints, cron-driven price ticks fanned out to many users - use `live.notify(target, event, data)` instead of `live.push`:

package/cli.js

@@ -1,13 +1,72 @@
 #!/usr/bin/env node
 // @ts-check
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { writeFileSync, existsSync, mkdirSync } from 'fs';
 import { resolve, join } from 'path';
 import * as p from '@clack/prompts';
 import { detectAgent, parseArgs, VALID_NAME_RE } from './cli-utils.js';
 
+const IS_WIN = process.platform === 'win32';
+
+/**
+ * Resolve a binary name to the OS-specific form. npm / pnpm / yarn / bun / npx
+ * ship as `.cmd` shims on Windows; Node's execFileSync (no shell) refuses to
+ * launch them without the extension. Native binaries (git) work as-is on
+ * every platform because Node resolves PATHEXT for them.
+ * @param {string} name
+ */
+function bin(name) {
+	return IS_WIN && name !== 'git' ? `${name}.cmd` : name;
+}
+
 const DEMO_REPO = 'https://github.com/lanteanio/svelte-realtime-demo.git';
 
+// The scaffolded upgrade() hook is intentionally permissive so the first
+// `npm run dev` works without any identity wiring: every connection gets a
+// fresh UUID and accepts. The hook also fires a console.warn on every
+// accepted connection until the developer deletes the SCAFFOLD_PLACEHOLDER
+// line. Deletion is the explicit "I have replaced this with real auth, stop
+// nagging me" action. Without that, the warning floods stderr/log
+// aggregators - unmissable in dev, impossible to ignore in prod.
+const UPGRADE_HOOK_SCAFFOLD = `// SECURITY: this scaffolded upgrade() hook accepts every WebSocket
+// connection and gives it a random UUID identity. It exists so the
+// scaffold works out of the box. Before deploying anything that
+// touches a real session store, real users, or anything else worth
+// protecting, replace this hook with one of:
+//
+//   1. Cookie session - parse req.getHeader('cookie'), look up the
+//      session id in your store, return { id: session.userId } or
+//      false if missing/expired.
+//
+//   2. Bearer token - parse req.getHeader('authorization'), validate
+//      the JWT or opaque token, return { id: claims.sub } or false.
+//
+//   3. Signed query token - parse the upgrade URL's query string,
+//      verify a server-issued HMAC, return { id: claims.userId } or
+//      false. Useful when the client cannot send custom headers.
+//
+// Returning false from upgrade() rejects the connection. The object
+// you return becomes ctx.user on every message and live() call.
+//
+// Delete the SCAFFOLD_PLACEHOLDER line below to silence the runtime
+// warning once your auth is in place.
+import { message } from 'svelte-realtime/server';
+export { message };
+
+const SCAFFOLD_PLACEHOLDER = true;
+
+export function upgrade() {
+\tif (SCAFFOLD_PLACEHOLDER) {
+\t\tconsole.warn(
+\t\t\t'[svelte-realtime] upgrade() is the scaffold default. ' +
+\t\t\t\t'Every connection gets a random UUID identity. ' +
+\t\t\t\t'Edit src/hooks.ws.ts before deploying - see the SECURITY block at the top of the file.'
+\t\t);
+\t}
+\treturn { id: crypto.randomUUID() };
+}
+`;
+
 const parsed = parseArgs(process.argv.slice(2), {
 	dirExists: (name) => existsSync(resolve(process.cwd(), name))
 });
@@ -84,23 +143,23 @@ const agent = detectAgent(process.env.npm_config_user_agent);
 
 if (template === 'demo') {
 	p.log.step('Cloning demo repository');
-	run(`git clone ${DEMO_REPO} "${name}"`);
+	run('git', ['clone', DEMO_REPO, name]);
 
 	p.log.step('Installing dependencies');
-	run(`${agent} install`, dest);
+	run(bin(agent), ['install'], dest);
 
 	p.outro(`Done. cd ${name} && ${agent} run dev`);
 	process.exit(0);
 }
 
 p.log.step('Creating SvelteKit project');
-run(`npx -y sv create "${name}" --template minimal --types ts --no-add-ons --no-install`);
+run(bin('npx'), ['-y', 'sv', 'create', name, '--template', 'minimal', '--types', 'ts', '--no-add-ons', '--no-install']);
 
 p.log.step('Installing dependencies');
 const add = agent === 'npm' ? 'install' : 'add';
-run(`${agent} ${add} svelte-adapter-uws svelte-realtime`, dest);
-run(`${agent} ${add} uNetworking/uWebSockets.js#v20.60.0`, dest);
-run(`${agent} ${add} -D ws`, dest);
+run(bin(agent), [add, 'svelte-adapter-uws', 'svelte-realtime'], dest);
+run(bin(agent), [add, 'uNetworking/uWebSockets.js#v20.60.0'], dest);
+run(bin(agent), [add, '-D', 'ws'], dest);
 
 p.log.step('Configuring svelte-realtime');
 
@@ -132,23 +191,7 @@ export default defineConfig({
 `
 );
 
-writeFileSync(
-	join(dest, 'src', 'hooks.ws.ts'),
-	`// SECURITY: this scaffolded upgrade() hook authenticates every connection
-// with a random UUID - nobody is rejected and nobody is identified. It exists
-// to make the scaffold work out of the box. Before deploying anything that
-// touches a real session store, real users, or anything else worth protecting,
-// replace this with a real authentication step that validates a session
-// cookie / bearer token / signed handshake against your identity provider.
-// Returning false from upgrade() rejects the connection.
-import { message } from 'svelte-realtime/server';
-export { message };
-
-export function upgrade() {
-\treturn { id: crypto.randomUUID() };
-}
-`
-);
+writeFileSync(join(dest, 'src', 'hooks.ws.ts'), UPGRADE_HOOK_SCAFFOLD);
 
 if (template === 'example') {
 	mkdirSync(join(dest, 'src', 'live'), { recursive: true });
@@ -196,16 +239,46 @@ p.outro(`Done. cd ${name} && ${agent} run dev`);
 
 // ---------------------------------------------------------------------------
 
-/** @param {string} cmd @param {string} [cwd] */
-function run(cmd, cwd) {
+/**
+ * Run an external binary. Args are passed as an explicit array so they reach
+ * the OS exec call without shell tokenization - no template-string injection
+ * possible from this entrypoint regardless of how the caller assembles args.
+ *
+ * On Windows, package-manager shims (npm.cmd / pnpm.cmd / yarn.cmd / bun.cmd
+ * / npx.cmd) must run under a shell because Node >=22 EINVALs `.cmd` files
+ * under `shell: false`. The `shell: IS_WIN` toggle is scoped per-call to that
+ * platform-specific need; on Linux / Mac the no-shell path is the default.
+ * Even on Windows, the shell:true escaping caveat (DEP0190) is bounded here
+ * because every arg fed to run() in this file is either a hardcoded literal,
+ * the cli-utils VALID_NAME_RE-validated project name, or the hardcoded demo
+ * repo URL - none of which carry shell metacharacters. Adding an arg from an
+ * unvalidated source reintroduces the shell-injection class this refactor
+ * was designed to remove; new args must keep that invariant.
+ *
+ * @param {string} file
+ * @param {string[]} args
+ * @param {string} [cwd]
+ */
+function run(file, args, cwd) {
+	// Strip NODE_ENV so the scaffold runs npm/pnpm install as if from a clean
+	// shell - if the user invoked `npx svelte-realtime` inside an env where
+	// NODE_ENV=production was set, the package manager would skip devDeps and
+	// the resulting project would be broken. Use `delete` rather than spread +
+	// undefined: both have the same effect on Node 22+ (Node drops undefined
+	// env entries) but `delete` is the unambiguous form that does not depend
+	// on Node-internal handling of undefined env values.
+	const env = { ...process.env };
+	delete env.NODE_ENV;
 	try {
-		execSync(cmd, {
+		execFileSync(file, args, {
 			cwd,
 			stdio: 'inherit',
-			env: { ...process.env, NODE_ENV: undefined }
+			env,
+			shell: IS_WIN
 		});
 	} catch (e) {
-		p.cancel(`Command failed: ${cmd}\n${/** @type {any} */ (e).stderr || /** @type {any} */ (e).message}`);
+		const line = `${file} ${args.join(' ')}`;
+		p.cancel(`Command failed: ${line}\n${/** @type {any} */ (e).stderr || /** @type {any} */ (e).message}`);
 		process.exit(1);
 	}
 }

package/client.js

@@ -4,6 +4,7 @@ import { writable, readable } from 'svelte/store';
 import { assert } from './shared/assert.js';
 export { assert, getAssertionCounters, _resetAssertCounters } from './shared/assert.js';
 import { mergeKeyField, rebuildIndex } from './shared/merge.js';
+import { sanitizeRowData } from './shared/safe-assign.js';
 // Namespace import lets .rune() access fromStore (Svelte 5 only) without
 // breaking the module under Svelte 4 - missing exports become undefined,
 // not module-load errors.
@@ -83,7 +84,10 @@ export class RpcError extends Error {
 	}
 }
 
-/** Incrementing counter for short correlation IDs, prefixed to avoid cross-tab collision */
+// Incrementing counter for short correlation IDs, prefixed to avoid cross-tab
+// collision. Math.random is the right primitive: this prefix is response-routing
+// bookkeeping, not a session token or any value that crosses a trust boundary.
+// Not security-relevant; collision-avoidance only.
 const _idPrefix = Math.random().toString(36).slice(2, 6);
 let idCounter = 0;
 
@@ -1938,7 +1942,17 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 	 *     true in all other paths.
 	 */
 	function _applyMergeFn(value, index, envelope, optimisticKeys) {
-		const { event, data } = envelope;
+		const { event } = envelope;
+		// Defense-in-depth: strip prototype-pollution keys (`__proto__`,
+		// `constructor`, `prototype`) from envelope data at ingress for
+		// keyed merge strategies. The framework does not currently spread
+		// or `Object.assign` stored items, so the live exploit surface is
+		// host-app code that later iterates the array. The sanitizer is a
+		// no-op (zero allocation) when the danger keys are absent, which
+		// is every legitimate envelope.
+		const data = (merge === 'crud' || merge === 'presence' || merge === 'cursor')
+			? sanitizeRowData(envelope.data)
+			: envelope.data;
 
 		if (event === 'refreshed') {
 			value = data;
@@ -2606,6 +2620,10 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 						_statusStore.set('reconnecting');
 						if (_reconnectTimer) clearTimeout(_reconnectTimer);
 						let delay;
+						// Reconnect jitter: spread a fleet's reconnect attempts across the
+						// window so a server restart does not get a thundering-herd retry
+						// spike. Math.random is the right primitive here - jitter does not
+						// need crypto-quality entropy. Not security-relevant.
 						if (_reconnectAttempts < 2) {
 							delay = 20 + Math.floor(Math.random() * 80);
 						} else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.0-next.21",
+  "version": "0.5.0-next.22",
   "publishConfig": {
     "tag": "next"
   },

package/server.d.ts

@@ -455,6 +455,21 @@ export interface HandleRpcOptions {
 	 * Use for error reporting (Sentry, logging, etc.).
 	 */
 	onError?(path: string, error: unknown, ctx: LiveContext<any>): void;
+
+	/**
+	 * Maximum nesting depth allowed in an inbound RPC envelope. Envelopes
+	 * whose parsed JSON has any descendant deeper than this are dropped at
+	 * ingress (the same path as malformed JSON). Defense in depth against
+	 * downstream handlers / instrumentation that recursively walk the
+	 * parsed object and would stack-overflow on pathological depth.
+	 *
+	 * The adapter's `maxPayloadLength` (default 1 MB) is the primary cap
+	 * - it bounds the bytes `JSON.parse` ever sees. This is a second
+	 * line of defense for the post-parse shape.
+	 *
+	 * @default 64
+	 */
+	maxEnvelopeDepth?: number;
 }
 
 /**

package/server.js

@@ -1,11 +1,54 @@
 // @ts-check
 import { assert, wireAssertionMetrics } from './shared/assert.js';
+import { safeAssign as _safeAssignSnapshot } from './shared/safe-assign.js';
 export { assert, getAssertionCounters, _resetAssertCounters } from './shared/assert.js';
 
 const textDecoder = new TextDecoder();
 const _validPathRe = /^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)+$/;
 const _validSegmentRe = /^[a-zA-Z0-9_]+$/;
 
+/**
+ * Max accepted length for a userId that flows into a topic name via
+ * `__signal:${userId}` / `__push:${userId}` and similar server-built
+ * system topics. 256 chars is generous for any realistic identifier
+ * (UUIDs, opaque session tokens, prefixed-by-tenant ids) without
+ * bloating log lines or stressing the adapter's wire-topic budget.
+ */
+const _MAX_USER_ID_LENGTH = 256;
+
+/**
+ * Validate that a userId is safe to interpolate into a system topic
+ * name. Returns `null` if valid, otherwise a short error reason string
+ * suitable for embedding in a thrown LiveError / Error message.
+ *
+ * Server-side helpers that build `__signal:${userId}` / `__push:${userId}`
+ * topic names from caller-supplied identifiers go through this gate so
+ * malformed identifiers (control bytes, CR/LF, NUL, quotes, backslash,
+ * empty, non-string, oversized) cannot poison the topic namespace,
+ * corrupt log lines, or escape the system-topic prefix into the
+ * user-topic space. Non-ASCII bytes are allowed for parity with the
+ * adapter's `allowNonAsciiTopics` opt-in; the server-side builder
+ * trusts identifier shapes set by upgrade hooks.
+ *
+ * @param {unknown} userId
+ * @returns {string | null}
+ */
+function _validUserIdReason(userId) {
+	if (typeof userId !== 'string') return 'userId must be a string (got ' + (typeof userId) + ')';
+	if (userId.length === 0) return 'userId must be non-empty';
+	if (userId.length > _MAX_USER_ID_LENGTH) return 'userId exceeds maximum length ' + _MAX_USER_ID_LENGTH + ' (got ' + userId.length + ')';
+	for (let i = 0; i < userId.length; i++) {
+		const c = userId.charCodeAt(i);
+		// Reject ASCII C0 controls (0x00-0x1F), DEL (0x7F), and the two
+		// characters the adapter's wire-topic validator forbids:
+		// 0x22 (double-quote), 0x5C (backslash).
+		if (c < 0x20 || c === 0x7F || c === 0x22 || c === 0x5C) {
+			return 'userId contains invalid character at index ' + i + ' (charCode ' + c + ')';
+		}
+	}
+	return null;
+}
+
 // - Bounded-by-default capacity caps (server side) -------------------------
 // Every per-process Map / Set with caller-driven growth is bounded. Numbers
 // are deliberately generous - far above any healthy single-instance workload
@@ -1182,7 +1225,11 @@ function _getCtxHelpers(platform) {
 			publish,
 			throttle: (topic, event, data, ms) => _throttlePublish(platform, topic, event, data, ms),
 			debounce: (topic, event, data, ms) => _debouncePublish(platform, topic, event, data, ms),
-			signal: (userId, event, data) => platform.publish('__signal:' + userId, event, data),
+			signal: (userId, event, data) => {
+				const reason = _validUserIdReason(userId);
+				if (reason !== null) throw new LiveError('INVALID_USER_ID', 'ctx.signal: ' + reason);
+				return platform.publish('__signal:' + userId, event, data);
+			},
 			batch: (messages) => platform.batch ? platform.batch(messages) : messages.forEach((m) => publish(m.topic, m.event, m.data, m.options)),
 			shed: (className) => _shouldShed(platform, className)
 		};
@@ -1960,6 +2007,36 @@ function _consumeRateLimitBucket(bucketKey, points, windowMs) {
 
 /**
  * Declarative per-function rate limiting.
+ * Marker wrapper that declares an RPC is intentionally public (no
+ * `_guard` required). Returns the inner handler unchanged at runtime;
+ * the vite codegen detects `live.public(...)` in source and
+ * suppresses the build-time "no _guard" warning for that module.
+ *
+ * Use per-export to flag handlers that genuinely accept any
+ * authenticated client (e.g. server-time, public health probes,
+ * unauthenticated read-only endpoints). For module-wide public RPCs,
+ * the `// realtime-allow-public` source comment is the lighter
+ * alternative.
+ *
+ * @param {Function} fn - Handler function (ctx, ...args)
+ * @returns {Function}
+ *
+ * @example
+ * ```js
+ * // src/lib/realtime/health.js
+ * import { live } from 'svelte-realtime';
+ *
+ * export const serverTime = live.public(async () => ({ now: Date.now() }));
+ * ```
+ */
+live.public = function publicMarker(fn) {
+	if (typeof fn !== 'function') {
+		throw new Error('[svelte-realtime] live.public(fn) requires a handler function');
+	}
+	return fn;
+};
+
+/**
  * Wraps a live() function with a sliding window rate limiter.
  *
  * @param {{ points: number, window: number, key?: (ctx: any) => string }} config
@@ -2817,8 +2894,9 @@ export const pushHooks = {
 		}
 		const userId = _getPushIdentify()(ws);
 		if (userId == null || userId === '') return;
-		if (typeof userId !== 'string') {
-			throw new Error('[svelte-realtime] pushHooks.open: identify(ws) must return a string, null, or undefined (got ' + typeof userId + ')');
+		const reason = _validUserIdReason(userId);
+		if (reason !== null) {
+			throw new Error('[svelte-realtime] pushHooks.open: ' + reason + '. identify(ws) must return a non-empty userId string that is safe to embed in a topic name (no control chars / CR / LF / NUL / quotes / backslash, max ' + _MAX_USER_ID_LENGTH + ' chars), or null / undefined for anonymous connections.');
 		}
 		if (!_pushRegistry.has(userId) && _pushRegistry.size >= _maxPushRegistry) {
 			if (!_pushRegistryWarnFired) {
@@ -3735,22 +3813,6 @@ export const combineMerge = (...buckets) => {
 	return merged;
 };
 
-/**
- * Copy own enumerable properties from `src` into `dst`, skipping
- * `__proto__` and `constructor`. Used to hydrate aggregate state from
- * an external snapshot (Redis cache, JSON payload, etc.) without giving
- * a hostile snapshot a path to set Object.prototype properties via
- * `Object.assign(target, JSON.parse('{"__proto__":{"polluted":1}}'))`.
- *
- * @param {object} dst
- * @param {object} src
- */
-function _safeAssignSnapshot(dst, src) {
-	for (const k of Object.keys(src)) {
-		if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
-		dst[k] = /** @type {any} */ (src)[k];
-	}
-}
 
 /**
  * Create a real-time incremental aggregation over a source topic.
@@ -6042,13 +6104,54 @@ export class LiveError extends Error {
 	}
 }
 
+/**
+ * Default maximum nesting depth allowed in an inbound RPC envelope.
+ * Anything deeper than this is rejected at ingress. 64 is well past any
+ * realistic application shape (typical envelopes nest one or two levels
+ * deep for `{args: [...]}` and an args payload) but well short of where
+ * any host-app recursive walker would stack-overflow. Override per-call
+ * via `handleRpc(ws, data, platform, { maxEnvelopeDepth })`.
+ */
+const _DEFAULT_MAX_ENVELOPE_DEPTH = 64;
+
+/**
+ * Iterative depth walk over a parsed JSON value. Returns true when the
+ * value (or any descendant) sits at a nesting depth greater than `max`.
+ * Stack-based so a pathological depth cannot itself stack-overflow the
+ * checker. Short-circuits on the first over-depth descendant found.
+ *
+ * @param {unknown} root
+ * @param {number} max
+ */
+function exceedsEnvelopeDepth(root, max) {
+	if (root === null || typeof root !== 'object') return false;
+	/** @type {Array<{ obj: any, depth: number }>} */
+	const stack = [{ obj: root, depth: 1 }];
+	while (stack.length > 0) {
+		const { obj, depth } = /** @type {{ obj: any, depth: number }} */ (stack.pop());
+		if (depth > max) return true;
+		if (Array.isArray(obj)) {
+			for (let i = 0; i < obj.length; i++) {
+				const v = obj[i];
+				if (v !== null && typeof v === 'object') stack.push({ obj: v, depth: depth + 1 });
+			}
+		} else {
+			for (const k of Object.keys(obj)) {
+				const v = obj[k];
+				if (v !== null && typeof v === 'object') stack.push({ obj: v, depth: depth + 1 });
+			}
+		}
+	}
+	return false;
+}
+
 /**
  * Check whether a raw WebSocket message is an RPC request and handle it.
  *
  * @param {any} ws
  * @param {ArrayBuffer} data - Raw message data from the adapter message hook
  * @param {import('svelte-adapter-uws').Platform} platform
- * @param {{ beforeExecute?: (ws: any, rpcPath: string, args: any[]) => Promise<void> | void, onError?: (path: string, error: unknown, ctx: any) => void }} [options]
+ * @param {{ beforeExecute?: (ws: any, rpcPath: string, args: any[]) => Promise<void> | void, onError?: (path: string, error: unknown, ctx: any) => void, maxEnvelopeDepth?: number }} [options]
  * @returns {boolean} true if the message was an RPC request
  */
 export function handleRpc(ws, data, platform, options) {
@@ -6107,6 +6210,16 @@ export function handleRpc(ws, data, platform, options) {
 		return false;
 	}
 
+	// Post-parse depth cap. The adapter's `maxPayloadLength` (default 1 MB)
+	// already bounds the bytes JSON.parse ever sees, so this is defense
+	// in depth against downstream handlers / instrumentation that recursively
+	// walk the parsed object and could stack-overflow on pathological depth.
+	// Iterative stack so the check itself never overflows.
+	const maxEnvelopeDepth = (options && options.maxEnvelopeDepth) || _DEFAULT_MAX_ENVELOPE_DEPTH;
+	if (exceedsEnvelopeDepth(msg, maxEnvelopeDepth)) {
+		return false;
+	}
+
 	// Batch request: {"batch": [...]}
 	if (Array.isArray(msg.batch)) {
 		_executeBatch(ws, msg, platform, options);
@@ -6264,28 +6377,35 @@ async function _executeStreamRpc(ws, platform, fn, ctx, args, msg, subscribedRef
 		}
 	}
 
-	// Wire-level subscribe gate: ask the adapter's `subscribe` /
-	// `subscribeBatch` hook chain whether this (ws, topic) pair would be
-	// denied at the wire-level subscribe-batch frame. Without this gate,
+	// Wire-level subscribe gate + atomic subscribe. `platform.subscribe`
+	// runs the adapter's `subscribe` / `subscribeBatch` hook chain,
+	// enforces `MAX_SUBSCRIPTIONS_PER_CONNECTION`, and updates the
+	// adapter-side per-connection subscription state (the `subs` Set,
+	// `totalSubscriptions` counter, and the close-hook's
+	// `ctx.subscriptions` parameter). Without going through this path,
 	// the loader would run, deliver initial data, and the room's
 	// __onSubscribe would publish a 'join' before the adapter's hook
 	// fires (which only fires on the client's follow-on subscribe-batch
-	// wire frame, AFTER the stream RPC returns). The optional-chain on
-	// `platform.checkSubscribe` keeps older adapters working: if the
-	// method isn't there, we fall through to the prior behavior and the
-	// in-realtime gates (`__streamFilter`, `live.room({ guard })`) remain
-	// the only stream-RPC access checks.
-	if (typeof platform.checkSubscribe === 'function') {
-		// Await the gate so async user hooks (the idiomatic pattern when
-		// the gate consults a session store or DB) deny correctly when
-		// they return `false`. A sync return is awaited transparently.
-		const denial = await platform.checkSubscribe(ws, topic);
-		if (denial) {
-			return { id, ok: false, code: denial, error: denial === 'UNAUTHENTICATED' ? 'Authentication required' : 'Access denied' };
-		}
-	}
-
-	try { ws.subscribe(topic); } catch { return { id, ok: false, code: 'CONNECTION_CLOSED', error: 'WebSocket closed' }; }
+	// wire frame, AFTER the stream RPC returns), AND the resulting
+	// subscription would be invisible to the adapter's observability
+	// surface (close-hook subscriptions set, per-conn cap). The
+	// optional-chain on `platform.subscribe` keeps older adapters
+	// working: if the method isn't there, we fall back to raw
+	// `ws.subscribe` and only the in-realtime gates (`__streamFilter`,
+	// `live.room({ guard })`) remain the stream-RPC access checks.
+	let _subscribeDenial = null;
+	try {
+		if (typeof platform.subscribe === 'function') {
+			_subscribeDenial = await platform.subscribe(ws, topic);
+		} else {
+			ws.subscribe(topic);
+		}
+	} catch {
+		return { id, ok: false, code: 'CONNECTION_CLOSED', error: 'WebSocket closed' };
+	}
+	if (_subscribeDenial) {
+		return { id, ok: false, code: _subscribeDenial, error: _subscribeDenial === 'UNAUTHENTICATED' ? 'Authentication required' : 'Access denied' };
+	}
 	_trackStreamSub(ws, topic, fn);
 	subscribedRef.topic = topic;
 
@@ -7604,9 +7724,15 @@ export function enableSignals(ws, options) {
 	const idField = options?.idField || 'id';
 	const userData = ws.getUserData();
 	const userId = userData?.[idField];
-	if (userId !== undefined && userId !== null) {
-		ws.subscribe('__signal:' + userId);
-	}
+	// null / undefined = anonymous connection, silently skip (no signal
+	// subscription wired). This preserves the documented pattern of
+	// calling `enableSignals(ws)` unconditionally in the open hook.
+	if (userId === undefined || userId === null) return;
+	const reason = _validUserIdReason(userId);
+	if (reason !== null) {
+		throw new Error('[svelte-realtime] enableSignals: ' + reason + '. The userData field "' + idField + '" must be a non-empty string safe to embed in a topic name (no control chars / CR / LF / NUL / quotes / backslash, max ' + _MAX_USER_ID_LENGTH + ' chars), or null / undefined for anonymous connections.');
+	}
+	ws.subscribe('__signal:' + userId);
 }
 
 /**

package/shared/safe-assign.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+/**
+ * Defense-in-depth helpers for sanitizing user-supplied object data
+ * before it lands in framework-owned reactive state.
+ *
+ * Why: any property assignment `target.__proto__ = X` mutates the
+ * target's [[Prototype]], and `Object.assign(target, src)` with
+ * `src.__proto__` present moves the value onto `Object.prototype`,
+ * polluting every plain object in the realm. The wire format
+ * (`JSON.parse`) does NOT prototype-pollute on its own (it sets
+ * `__proto__` as an own property), but any downstream code that does
+ * `Object.assign({}, item)` or `for..in` over the items inherits the
+ * pollution path.
+ *
+ * The framework's CRUD / presence / cursor merge paths store
+ * user-supplied envelopes verbatim in reactive arrays. Today's code
+ * neither spreads nor `Object.assign`s those items - the stored shape
+ * goes back out on the wire and into user code. We strip danger keys
+ * at envelope ingress so a future refactor that introduces a spread
+ * or assign cannot accidentally pollute the host process.
+ *
+ * @module svelte-realtime/shared/safe-assign
+ */
+
+/**
+ * Keys that mutate `Object.prototype` (or shadow built-ins) when
+ * assigned to a plain object. Frozen so a contributor cannot add a
+ * "safe" key here later without thinking about the implication.
+ */
+export const PROTO_POLLUTION_KEYS = Object.freeze(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Copy own enumerable properties from `src` into `dst`, skipping
+ * `__proto__`, `constructor`, and `prototype`. Used to hydrate
+ * snapshot state from an external source (Redis cache, JSON payload,
+ * etc.) without giving the snapshot a path to set Object.prototype
+ * properties via `Object.assign`. Returns `dst`.
+ *
+ * @template T
+ * @param {T} dst
+ * @param {Record<string, any>} src
+ * @returns {T}
+ */
+export function safeAssign(dst, src) {
+	for (const k of Object.keys(src)) {
+		if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+		/** @type {any} */ (dst)[k] = /** @type {any} */ (src)[k];
+	}
+	return dst;
+}
+
+/**
+ * Return `data` with `__proto__` / `constructor` / `prototype` stripped
+ * as own properties, when present. When `data` has none of the danger
+ * keys, returns `data` unchanged (no allocation, reference identity
+ * preserved). When at least one is present, returns a fresh shallow
+ * clone with those keys removed. Date, Map, Set and other non-plain
+ * objects pass through unchanged.
+ *
+ * Arrays are processed element-by-element. The returned array is the
+ * same reference when every element is danger-key-free, or a fresh
+ * array containing sanitized clones for the elements that needed it.
+ *
+ * Performance contract: the no-danger-key path is `hasOwnProperty` x3
+ * (~30ns) for plain objects, one iteration for arrays. No allocation
+ * in the common case. Negligible against the surrounding merge cost.
+ *
+ * @template T
+ * @param {T} data
+ * @returns {T}
+ */
+export function sanitizeRowData(data) {
+	if (!data || typeof data !== 'object') return data;
+	if (Array.isArray(data)) {
+		let cloned = null;
+		for (let i = 0; i < data.length; i++) {
+			const sanitized = sanitizeRowData(data[i]);
+			if (sanitized !== data[i]) {
+				if (cloned === null) cloned = data.slice();
+				cloned[i] = sanitized;
+			}
+		}
+		return /** @type {any} */ (cloned ?? data);
+	}
+	// Non-plain object (Date, Map, Set, etc.) - leave alone.
+	if (Object.getPrototypeOf(data) !== Object.prototype && Object.getPrototypeOf(data) !== null) {
+		return data;
+	}
+	const has = Object.prototype.hasOwnProperty;
+	if (
+		!has.call(data, '__proto__') &&
+		!has.call(data, 'constructor') &&
+		!has.call(data, 'prototype')
+	) {
+		return data;
+	}
+	const clone = /** @type {any} */ ({});
+	for (const k of Object.keys(/** @type {any} */ (data))) {
+		if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+		clone[k] = /** @type {any} */ (data)[k];
+	}
+	return clone;
+}
+
+/**
+ * Throws when the supplied key value (the resolved `data[keyField]`
+ * used as a Map / index slot) equals one of the prototype-pollution
+ * strings. Map keys themselves are not exploitable - the Map stores
+ * `'__proto__'` as a string key without mutating any prototype - but
+ * a downstream `obj[mapKey] = value` assignment would, so callers that
+ * use this value in BOTH a Map AND a plain-object assignment should
+ * gate it through this assert.
+ *
+ * @param {unknown} keyValue
+ */
+export function assertSafeMergeKey(keyValue) {
+	if (keyValue === '__proto__' || keyValue === 'constructor' || keyValue === 'prototype') {
+		throw new Error(`unsafe merge key "${String(keyValue)}" - prototype-pollution shapes are filtered at envelope ingress`);
+	}
+}

package/test.js

@@ -1,5 +1,6 @@
 // @ts-check
 import { __register, __registerGuard, __registerCron, __registerDerived, __registerEffect, __registerAggregate, __registerRoomActions, handleRpc, LiveError, _clearCron, _activateDerived, close, unsubscribe } from './server.js';
+import { sanitizeRowData } from './shared/safe-assign.js';
 
 /**
  * Build a `ctx`-shaped object suitable for direct unit tests of guards,
@@ -104,10 +105,17 @@ const textEncoder = new TextEncoder();
  * @returns {any}
  */
 function _applyTestMerge(current, envelope, merge, key, opts) {
-	const { event, data } = envelope;
+	const { event } = envelope;
 	const prepend = opts?.prepend || false;
 	const max = opts?.max || 50;
 
+	// Mirror the client's defense-in-depth: strip prototype-pollution
+	// keys at envelope ingress for keyed merges so test fixtures match
+	// the wire-shape clients actually observe.
+	const data = (merge === 'crud' || merge === 'presence' || merge === 'cursor')
+		? sanitizeRowData(envelope.data)
+		: envelope.data;
+
 	if (merge === 'set') return data;
 
 	if (merge === 'latest') {
@@ -225,6 +233,10 @@ export function createTestEnv(options) {
 
 	function _shouldChaosDropPublish() {
 		if (!chaosConfig || chaosConfig.dropRate === 0) return false;
+		// Chaos drop check: simulated network loss for test scenarios. chaosRng
+		// is a seeded PRNG when the caller configured `chaos: { seed }`; without
+		// a seed we fall back to Math.random for the unseeded shape. Test-only
+		// code path. Not security-relevant.
 		const r = chaosRng ? chaosRng() : Math.random();
 		if (r < chaosConfig.dropRate) {
 			chaosDropped++;
@@ -271,6 +283,18 @@ export function createTestEnv(options) {
 		subscribers(topic) {
 			return topicSubscribers.get(topic)?.size || 0;
 		},
+		// platform.subscribe / platform.checkSubscribe mirrors of the real
+		// adapter shape. The test platform has no user subscribe hooks, so
+		// these just delegate to ws.subscribe and report null (allow). Tests
+		// that need to exercise gate-denial paths can replace this mock
+		// with a custom platform.
+		async subscribe(ws, topic) {
+			try { ws.subscribe(topic); } catch { return 'CONNECTION_CLOSED'; }
+			return null;
+		},
+		async checkSubscribe() {
+			return null;
+		},
 		topic(t) {
 			return {
 				publish: (event, data) => platform.publish(t, event, data),

package/vite.js

@@ -28,6 +28,18 @@ const AGGREGATE_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.aggregate\s*\(/g
 // path. Without this, exports declared as `export const x = live.lock(...)`
 // would not be recognised and the client could not call them.
 const LOCK_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.lock\s*\(/g;
+// `live.public(...)` is a runtime no-op wrapper (returns the handler
+// unchanged) whose only job is to declare intent: "this RPC is
+// intentionally public; do not warn about a missing _guard." The
+// codegen treats it identically to `live(...)` for emission and uses
+// the presence of any `live.public` export as a module-level suppression
+// for the "no _guard" build-time warning.
+const PUBLIC_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.public\s*\(/g;
+// Module-level escape hatch: a `// realtime-allow-public` comment
+// anywhere in the source suppresses the "no _guard" warning for the
+// whole module. Use this when several or all live() exports in a
+// module are intentionally public.
+const PUBLIC_COMMENT_RE = /(?:\/\/|\/\*)\s*realtime-allow-public\b/;
 const IDEMPOTENT_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.idempotent\s*\(/g;
 
 const _validSegmentReVite = /^[a-zA-Z0-9_]+$/;
@@ -1074,9 +1086,18 @@ function _generateClientStubs(filePath, modulePath, dir) {
 
 	// Detect live() exports
 	let match;
+	// Track whether any live.public() export is present in the module - used
+	// alongside the `// realtime-allow-public` comment to suppress the
+	// "no _guard" build-time warning.
+	let hasPublicExport = false;
+	PUBLIC_EXPORT_RE.lastIndex = 0;
+	if (PUBLIC_EXPORT_RE.exec(source) !== null) {
+		hasPublicExport = true;
+	}
+	const hasPublicComment = PUBLIC_COMMENT_RE.test(source);
 	// live() and the wrappers that pass through unchanged on the client
-	// (validated/lock/idempotent/rateLimit) all emit the same __rpc line.
-	for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE]) {
+	// (validated/lock/idempotent/rateLimit/public) all emit the same __rpc line.
+	for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE, PUBLIC_EXPORT_RE]) {
 		re.lastIndex = 0;
 		while ((match = re.exec(source)) !== null) {
 			const name = match[1];
@@ -1279,6 +1300,30 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		}
 	}
 
+	// Build-time nudge: a module with live() exports but no `_guard`
+	// is opting into the framework's default-allow posture (every
+	// authenticated WS can invoke any registered handler). That is the
+	// correct default for "Hello, world" but is a foot-gun for apps that
+	// forget to add an auth gate.
+	//
+	// Suppression:
+	//   - export at least one `live.public(...)` (per-export intent, recommended)
+	//   - add `// realtime-allow-public` anywhere in the source (module-wide opt-out)
+	//   - export `_guard = guard(...)` (the framework auth gate)
+	//
+	// The warning is a soft nudge, not a hard error - runtime semantics
+	// are unchanged.
+	if (exportedNames.size > 0 && !hasGuard && !hasPublicExport && !hasPublicComment) {
+		console.warn(
+			`[svelte-realtime] ${dir}/${modulePath} has live() / live.stream() exports but no _guard. ` +
+			`Every authenticated WS can invoke any handler in this module. ` +
+			`Add 'export const _guard = guard(...)' to gate access, ` +
+			`mark individual handlers as 'live.public(...)' to declare them intentionally open, ` +
+			`or add '// realtime-allow-public' to the file to suppress this warning.\n` +
+			`  See: https://svti.me/guard`
+		);
+	}
+
 	const importLine = imports.size > 0
 		? `import { ${[...imports].join(', ')} } from 'svelte-realtime/client';\n`
 		: '';