@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/src/websocket/WebSocketConnection.ts

@@ -0,0 +1,162 @@
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+import { WebSocket, type RawData } from 'ws';
+import type { App } from '../server/App';
+import type { UserIdentity } from '../auth';
+import type * as socket from './contracts';
+
+/** One bounded JSON connection with fresh request authentication for application work. */
+export class WebSocketConnection {
+	readonly id = randomUUID();
+	readonly #abort = new AbortController();
+	#token = '';
+	#userId = '';
+	#ready = false;
+	#pending = 0;
+	/** Bounds retained payloads and concurrent access checks before transport buffering. */
+	#pendingSends = 0;
+	#chain: Promise<void> = Promise.resolve();
+	#alive = true;
+	#checking = false;
+	#timer: ReturnType<typeof setTimeout>;
+	#heartbeat: ReturnType<typeof setInterval>;
+	#finished: Promise<void>;
+	#finish!: () => void;
+
+	/** Attaches listeners synchronously so early frames cannot bypass authentication. */
+	constructor(readonly ws: WebSocket, readonly request: IncomingMessage, readonly app: App, readonly endpoint: socket.WebSocketEndpoint<any, any>, readonly limits: socket.WebSocketLimits, readonly report: (error: unknown) => void, readonly presenceChanged: () => void, readonly resolveToken?: socket.WebSocketOptions['resolveToken']) {
+		this.#finished = new Promise(resolve => { this.#finish = resolve; });
+		this.#abort.signal.addEventListener('abort', () => { if (this.#ready) this.presenceChanged(); }, { once: true });
+		this.#timer = setTimeout(() => this.stop(4401), limits.authTimeoutMs);
+		this.#heartbeat = setInterval(() => void this.#tick(), limits.heartbeatMs);
+		this.#timer.unref();
+		this.#heartbeat.unref();
+		ws.on('pong', () => { this.#alive = true; });
+		ws.on('error', () => this.stop(1011));
+		ws.on('message', (data, binary) => this.#receive(data, binary));
+		ws.once('close', code => {
+			this.#abort.abort();
+			this.#token = '';
+			clearTimeout(this.#timer);
+			clearInterval(this.#heartbeat);
+			// Wait for open/message work before cleanup, including an open action that closed itself.
+			void this.#chain.then(async () => {
+				if (this.#ready) await this.endpoint.close?.({ id: this.id, userId: this.#userId || null, code });
+			}).catch(this.report).finally(this.#finish);
+		});
+	}
+
+	/** Stops delivery immediately and bounds the close handshake for unresponsive peers. */
+	stop(code = 1000): void {
+		if (this.#abort.signal.aborted) return;
+		this.#abort.abort();
+		clearTimeout(this.#timer);
+		clearInterval(this.#heartbeat);
+		this.ws.close(code);
+		this.#timer = setTimeout(() => this.ws.terminate(), this.limits.shutdownTimeoutMs);
+		this.#timer.unref();
+	}
+
+	/** Resolves when the socket and application cleanup are finished. */
+	finished(): Promise<void> { return this.#finished; }
+
+	/** Returns local presence only after authorization and until shutdown/disconnection. */
+	get userId(): string | null { return this.#ready && !this.#abort.signal.aborted ? this.#userId : null; }
+
+	/** Queues bounded text messages; the first frame is reserved for authentication. */
+	#receive(data: RawData, binary: boolean): void {
+		if (this.#abort.signal.aborted) return;
+		if (binary) { this.stop(1003); return; }
+		if (++this.#pending > this.limits.maxPendingMessages) { this.stop(1008); return; }
+		const text = data.toString();
+		this.#chain = this.#chain.then(async () => {
+			if (this.#abort.signal.aborted) return;
+			let frame: any;
+			try { frame = JSON.parse(text); } catch { this.stop(1007); return; }
+			if (!this.#ready) {
+				if (this.endpoint.auth === 'public') {
+					if (frame?.type !== 'connect') { this.stop(1008); return; }
+				} else {
+					if (frame?.type !== 'authenticate') { this.stop(4401); return; }
+					const token = this.resolveToken ? await this.resolveToken(this.request) : frame.token;
+					if (typeof token !== 'string' || !token || token.length > 4096) { this.stop(4401); return; }
+					this.#token = token;
+				}
+				await this.#authorized(async context => {
+					this.#ready = true;
+					clearTimeout(this.#timer);
+					this.#write({ type: 'ready' });
+					this.presenceChanged();
+					await this.endpoint.open?.(context);
+				});
+				return;
+			}
+			if (frame?.type !== 'message' || !Object.hasOwn(frame, 'data')) { this.stop(1008); return; }
+			await this.#authorized(async context => {
+				if (await this.app.webSockets.channels.handle(this.endpoint.channels ?? [], context, frame.data)) return;
+				let data: unknown;
+				try { data = this.endpoint.parse ? await this.endpoint.parse(frame.data) : frame.data; } catch { this.stop(1008); return; }
+				if (!this.#abort.signal.aborted) await this.endpoint.message?.(context, data);
+			});
+		}).catch(error => { this.report(error); this.stop(1011); }).finally(() => { this.#pending--; });
+	}
+
+	/** Revalidates sessions and application access without retaining request-scoped Auth memoization. */
+	async #authorized(action: (context: socket.WebSocketContext<any>) => Promise<void>): Promise<boolean> {
+		if (this.#abort.signal.aborted) return false;
+		return this.app.requestContext.run(async () => {
+			const publicEndpoint = this.endpoint.auth === 'public';
+			const user = publicEndpoint ? null : await this.app.auth.authenticateToken(this.#token);
+			if (this.#abort.signal.aborted) return false;
+			if (!publicEndpoint && !user) { this.stop(4401); return false; }
+			const userId = user ? String(user.get((user.constructor as typeof UserIdentity).primaryKey)) : null;
+			if (this.#userId && this.#userId !== userId) { this.stop(4401); return false; }
+			this.#userId = userId ?? '';
+			const context: socket.WebSocketContext<any> = {
+				id: this.id, userId, user, request: this.request, signal: this.#abort.signal,
+				send: (data, authorize) => this.#send(data, authorize), close: () => this.stop(),
+			};
+			if (this.endpoint.authorize && !await this.endpoint.authorize(context)) { this.stop(4403); return false; }
+			if (this.#abort.signal.aborted) return false;
+			await action(context);
+			return true;
+		});
+	}
+
+	/** Bounds in-flight sends before fresh access checks; overload disconnects without queuing or replay. */
+	async #send(data: unknown, authorize?: Parameters<socket.WebSocketContext<any>['send']>[1]): Promise<boolean> {
+		if (this.#abort.signal.aborted) return false;
+		if (this.#pendingSends >= this.limits.maxPendingSends) { this.stop(1013); return false; }
+		this.#pendingSends++;
+		try {
+			let sent = false;
+			await this.#authorized(async context => {
+				if (!authorize || await authorize(context)) sent = this.#write({ type: 'message', data });
+			});
+			return sent;
+		} catch (error) { this.report(error); this.stop(1011); return false; }
+		finally { this.#pendingSends--; }
+	}
+
+	/** Enforces frame and buffered-byte limits before handing data to the socket. */
+	#write(frame: unknown): boolean {
+		if (this.#abort.signal.aborted || this.ws.readyState !== WebSocket.OPEN) return false;
+		const value = JSON.stringify(frame);
+		const bytes = Buffer.byteLength(value);
+		if (bytes > this.limits.maxPayloadBytes || this.ws.bufferedAmount + bytes > this.limits.maxBufferedBytes) { this.stop(1009); return false; }
+		this.ws.send(value, error => { if (error) this.stop(1011); });
+		return true;
+	}
+
+	/** Detects dead peers and revokes idle authenticated sockets as well as active ones. */
+	async #tick(): Promise<void> {
+		if (this.#abort.signal.aborted) return;
+		if (!this.#alive || this.#checking) { this.stop(1011); return; }
+		this.#alive = false;
+		this.ws.ping();
+		if (!this.#ready) return;
+		this.#checking = true;
+		try { await this.#authorized(async () => {}); } catch (error) { this.report(error); this.stop(1011); }
+		finally { this.#checking = false; }
+	}
+}

package/src/websocket/WebSockets.ts

@@ -0,0 +1,157 @@
+import type { Server, IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import type { App } from '../server/App';
+import { WebSocketConnection } from './WebSocketConnection';
+import { WebSocketChannels } from './WebSocketChannels';
+import type * as socket from './contracts';
+
+/** App-owned WebSocket endpoints on an existing Node HTTP/S listener. */
+export class WebSockets {
+	/** Process-local, server-authorized channels. Each delivery rechecks the connection's policy. */
+	readonly channels = new WebSocketChannels();
+	#close: (() => Promise<void>) | undefined;
+	readonly #connections = new Map<WebSocketConnection, string>();
+	readonly #presenceListeners = new Map<string, Set<() => void | Promise<void>>>();
+	#closed = false;
+
+	/** Configures worker HTTP delivery without opening a connection or starting a polling loop. */
+	constructor(readonly app: App, readonly options: socket.WebSocketServiceOptions = {}) {
+		if (options.publish) {
+			const { url, token, timeoutMs = 5000 } = options.publish;
+			const target = new URL(url);
+			if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.hash || target.search) throw new Error('Use a trusted HTTP(S) publishing URL without credentials, query or fragment.');
+			if (!/^[A-Za-z0-9_-]{32,256}$/.test(token)) throw new Error('WebSocket publish token must contain 32 to 256 URL-safe characters.');
+			if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error('Invalid WebSocket publish timeout.');
+		}
+	}
+
+	/** Returns a publisher for a concrete authorized resource channel. No client subscription is created. */
+	channel(name: string): socket.WebSocketChannelPublisher {
+		if (name.length > 256 || !/^[a-zA-Z0-9_.-]+(?::[a-zA-Z0-9_.-]+)*$/.test(name)) throw new Error('Invalid channel name.');
+		return { publish: async (event, data) => {
+			if (!event || event.length > 256) throw new Error('Invalid channel event.');
+			if (this.#closed) throw new Error('WebSocket service is closed.');
+			const message = JSON.stringify({ channel: name, event, data });
+			if (Buffer.byteLength(message) > 65536) throw new Error('WebSocket event exceeds 64 KiB.');
+			if (!this.#close && this.options.publish) {
+				const { url, token, timeoutMs = 5000 } = this.options.publish;
+				const response = await fetch(url, {
+					method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+					headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: message,
+				});
+				try {
+					if (!response.ok) throw new Error(`WebSocket publishing failed (${response.status}).`);
+					// HTTP acceptance is not a browser delivery receipt or a remote connection count.
+					return 0;
+				} finally { await response.body?.cancel(); }
+			}
+			return this.channels.publishEvent(name, event, data);
+		} };
+	}
+
+	/**
+	 * Mounts exact-path endpoint actions on one existing HTTP/S server.
+	 * @param server - Host-owned listener; the service never opens or closes its port.
+	 * @param options - Allowed origins, controller definitions and resource limits.
+	 */
+	mount(server: Server, options: socket.WebSocketOptions): void {
+		if (this.#close) throw new Error('WebSockets are already mounted.');
+		this.#closed = false;
+		const origins = new Set(options.origins);
+		if (!origins.size || [...origins].some(origin => { try { const url = new URL(origin); return !['http:', 'https:'].includes(url.protocol) || url.origin !== origin; } catch { return true; } })) throw new Error('WebSockets require exact HTTP(S) origins.');
+		const endpoints = new Map(Object.entries(options.endpoints));
+		for (const [path, endpoint] of endpoints) {
+			if (!path.startsWith('/') || path.startsWith('//') || /[?#\s]/.test(path) || !endpoint || typeof endpoint !== 'object') throw new Error('Invalid WebSocket endpoint.');
+		}
+		const limits: socket.WebSocketLimits = { maxConnections: 1000, maxPayloadBytes: 65536, maxBufferedBytes: 262144, maxPendingMessages: 16, maxPendingSends: 32, authTimeoutMs: 5000, heartbeatMs: 30000, shutdownTimeoutMs: 3000 };
+		for (const key of Object.keys(limits) as (keyof socket.WebSocketLimits)[]) {
+			const value = options[key] ?? limits[key];
+			if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`Invalid WebSocket limit: ${key}.`);
+			limits[key] = value;
+		}
+		const connections = this.#connections;
+		const sockets = new WebSocketServer({ noServer: true, maxPayload: limits.maxPayloadBytes, perMessageDeflate: false });
+		/** Contains reporting failures and keeps credentials out of transport diagnostics. */
+		const report = (error: unknown): void => { try { options.onError?.(error); } catch { /* Reporting cannot break cleanup. */ } };
+		let closing: Promise<void> | undefined;
+		/** Handles only owned paths; other upgrade listeners retain ownership of their paths. */
+		const upgrade = (request: IncomingMessage, stream: Duplex, head: Buffer): void => {
+			let pathname: string;
+			try { pathname = new URL(request.url ?? '/', 'http://localhost').pathname; } catch { stream.destroy(); return; }
+			const endpoint = endpoints.get(pathname);
+			if (!endpoint) {
+				if (server.listenerCount('upgrade') === 1) stream.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+				return;
+			}
+			if (closing || !request.headers.origin || !origins.has(request.headers.origin) || connections.size >= limits.maxConnections) {
+				stream.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+				return;
+			}
+			sockets.handleUpgrade(request, stream, head, ws => {
+				const connection = new WebSocketConnection(ws, request, this.app, endpoint, limits, report, () => {
+					for (const listener of this.#presenceListeners.get(pathname) ?? []) {
+						try { void Promise.resolve(this.app.requestContext.run(listener)).catch(report); } catch (error) { report(error); }
+					}
+				}, options.resolveToken);
+				connections.set(connection, pathname);
+				void connection.finished().then(() => connections.delete(connection));
+			});
+		};
+		server.on('upgrade', upgrade);
+		this.#close = () => closing ??= (async () => {
+			const current = [...connections.keys()];
+			for (const connection of current) connection.stop(1001);
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			try {
+				await Promise.race([Promise.all(current.map(connection => connection.finished())), new Promise<void>(resolve => { timer = setTimeout(resolve, limits.shutdownTimeoutMs); })]);
+			} finally {
+				clearTimeout(timer);
+				for (const connection of current) connection.ws.terminate();
+				connections.clear();
+				this.#presenceListeners.clear();
+				this.channels.clear();
+				server.off('upgrade', upgrade);
+				await new Promise<void>(resolve => sockets.close(() => resolve()));
+				this.#close = undefined;
+			}
+		})();
+	}
+
+	/** Stops accepting upgrades and bounds socket/application cleanup; safe to call repeatedly. */
+	async close(): Promise<void> { this.#closed = true; await this.#close?.(); }
+
+	/**
+	 * Lists distinct authenticated users connected to an exact endpoint in this process.
+	 * Application code must authorize disclosure; this is never exposed automatically.
+	 * Presence is approximate and excludes the other instance during blue/green overlap.
+	 * @param path - Registered endpoint path, excluding query parameters.
+	 * @returns Current user IDs and connection counts; no session tokens or profile data.
+	 */
+	presence(path: string): socket.WebSocketPresence[] {
+		const users = new Map<string, number>();
+		for (const [connection, endpoint] of this.#connections) {
+			const id = connection.userId;
+			if (endpoint === path && id) users.set(id, (users.get(id) ?? 0) + 1);
+		}
+		return [...users].map(([userId, connections]) => ({ userId, connections }));
+	}
+
+	/**
+	 * Subscribes to local presence changes on one exact endpoint, without exposing them to browsers.
+	 * Call presence(path) inside the listener to read current users. The listener has no Auth context
+	 * and does not serialize asynchronous listeners; connection.send() reauthenticates its recipient.
+	 * @param path - Exact endpoint whose authenticated connections should be observed.
+	 * @param listener - Application callback for connect, disconnect or revocation changes.
+	 * @returns Idempotent unsubscribe callback; register it on the owning connection's abort signal.
+	 */
+	onPresence(path: string, listener: () => void | Promise<void>): () => void {
+		let listeners = this.#presenceListeners.get(path);
+		if (!listeners) { listeners = new Set(); this.#presenceListeners.set(path, listeners); }
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+			if (!listeners.size && this.#presenceListeners.get(path) === listeners) this.#presenceListeners.delete(path);
+		};
+	}
+}

package/src/websocket/client/WebSocketClient.ts

@@ -0,0 +1,188 @@
+import type { ClientSocket, WebSocketClientOptions, WebSocketClientState, WebSocketClientChannel } from '../contracts/WebSocketClient';
+
+/** Browser-safe JSON transport with generation fencing, bounded reconnect and no offline message queue. */
+export class WebSocketClient {
+	#subscriptionQueue: string[] = [];
+	#subscribing: string | undefined;
+	readonly #channels = new Map<string, Map<string, Set<(data: unknown) => void>>>();
+	#state: WebSocketClientState = 'closed';
+	#socket: ClientSocket | undefined;
+	#generation = 0;
+	#attempt = 0;
+	#stopped = true;
+	#retry: ReturnType<typeof setTimeout> | undefined;
+	#deadline: ReturnType<typeof setTimeout> | undefined;
+	readonly #options: Required<Pick<WebSocketClientOptions, 'maxReconnectDelayMs' | 'connectTimeoutMs' | 'maxBufferedBytes'>> & WebSocketClientOptions;
+
+	/** Validates configuration without opening a connection, allowing safe SSR imports. */
+	constructor(options: WebSocketClientOptions) {
+		const url = new URL(options.url);
+		if (!['ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.hash) throw new Error('Use an absolute ws(s) URL without credentials or fragment.');
+		this.#options = { maxReconnectDelayMs: 30000, connectTimeoutMs: 10000, maxBufferedBytes: 65536, ...options };
+		for (const key of ['maxReconnectDelayMs', 'connectTimeoutMs', 'maxBufferedBytes'] as const) {
+			if (!Number.isSafeInteger(this.#options[key]) || this.#options[key] <= 0) throw new Error(`Invalid WebSocket client option: ${key}.`);
+		}
+	}
+
+	/** Current transport state; connected is set only after the server accepts the endpoint handshake. */
+	get state(): WebSocketClientState { return this.#state; }
+
+	/** Starts once, or explicitly retries after credentials/policy have been repaired. */
+	connect(): void {
+		if (!this.#stopped) return;
+		this.#stopped = false;
+		this.#attempt = 0;
+		void this.#open();
+	}
+
+	/** Closes the socket, cancels reconnect and fences late token/network results. */
+	close(): void {
+		this.#stopped = true;
+		this.#generation++;
+		clearTimeout(this.#retry);
+		clearTimeout(this.#deadline);
+		this.#socket?.close(1000);
+		this.#socket = undefined;
+		this.#subscriptionQueue = [];
+		this.#subscribing = undefined;
+		this.#setState('closed');
+	}
+
+	/** Sends JSON only while connected; rejected messages are never queued or replayed. */
+	send(data: unknown): boolean {
+		if (this.#state !== 'connected' || this.#socket?.readyState !== 1 || data === undefined) return false;
+		const frame = JSON.stringify({ type: 'message', data });
+		if (new TextEncoder().encode(frame).length + this.#socket.bufferedAmount > this.#options.maxBufferedBytes) return false;
+		this.#socket.send(frame);
+		return true;
+	}
+
+	/**
+	 * Returns a logical channel sharing this client's physical connection.
+	 * The first listener subscribes; removing the final listener unsubscribes.
+	 * @param name - Concrete resource channel; the server must independently authorize it.
+	 */
+	channel(name: string): WebSocketClientChannel {
+		if (name.length > 256 || !/^[a-zA-Z0-9_.-]+(?::[a-zA-Z0-9_.-]+)*$/.test(name)) throw new Error('Invalid channel name.');
+		return { on: (event, listener) => {
+			if (!event || event.length > 256) throw new Error('Invalid channel event.');
+			let events = this.#channels.get(name);
+			const subscribe = !events;
+			if (!events) { events = new Map(); this.#channels.set(name, events); }
+			let listeners = events.get(event);
+			if (!listeners) { listeners = new Set(); events.set(event, listeners); }
+			// Each registration owns its own cleanup, even when callbacks are identical.
+			const callback = (data: unknown) => listener(data);
+			listeners.add(callback);
+			if (subscribe && this.#state === 'connected') { this.#subscriptionQueue.push(name); this.#subscribeNext(); }
+			return () => {
+				if (!listeners.delete(callback)) return;
+				if (!listeners.size) events.delete(event);
+				if (!events.size) {
+					this.#channels.delete(name);
+					this.#subscriptionQueue = this.#subscriptionQueue.filter(channel => channel !== name);
+					this.send({ type: 'channel.unsubscribe', channel: name });
+				}
+			};
+		} };
+	}
+
+	/** Serializes subscriptions so a reconnect cannot flood the server's bounded action queue. */
+	#subscribeNext(): void {
+		if (this.#subscribing || this.#state !== 'connected') return;
+		const channel = this.#subscriptionQueue.shift();
+		if (!channel) return;
+		this.#subscribing = channel;
+		if (!this.send({ type: 'channel.subscribe', channel })) { this.#subscribing = undefined; this.#deny(); }
+	}
+
+	/** Dispatches reserved channel envelopes without exposing them as ordinary application messages. */
+	#message(data: any): void {
+		if (data && typeof data.channel === 'string' && typeof data.type === 'string' && data.type.startsWith('channel.')) {
+			if (['channel.subscribed', 'channel.denied'].includes(data.type) && this.#subscribing === data.channel) { this.#subscribing = undefined; this.#subscribeNext(); }
+			const events = this.#channels.get(data.channel);
+			if (!events) return;
+			if (data.type === 'channel.subscribed') this.#options.onSubscribed?.(data.channel);
+			else if (data.type === 'channel.denied') this.#options.onChannelDenied?.(data.channel);
+			else if (data.type === 'channel.event' && typeof data.event === 'string') {
+				for (const listener of [...events.get(data.event) ?? []]) listener(data.data);
+			}
+			return;
+		}
+		this.#options.onMessage?.(data);
+	}
+
+	/** Creates one attempt and ignores callbacks from replaced connections. */
+	async #open(): Promise<void> {
+		const generation = ++this.#generation;
+		this.#setState(this.#attempt ? 'reconnecting' : 'connecting');
+		this.#deadline = setTimeout(() => {
+			if (generation !== this.#generation || this.#stopped) return;
+			this.#generation++;
+			this.#socket?.close();
+			this.#retryLater();
+		}, this.#options.connectTimeoutMs);
+		try {
+			const auth = this.#options.auth ?? 'required';
+			const token = auth === 'required' ? await this.#options.token?.() : null;
+			if (generation !== this.#generation || this.#stopped) return;
+			if (auth === 'required' && !token) { this.#deny(); return; }
+			const factory = this.#options.createSocket ?? nativeSocket;
+			const ws = factory(this.#options.url);
+			this.#socket = ws;
+			ws.onopen = () => { if (generation === this.#generation && !this.#stopped) ws.send(JSON.stringify(auth === 'public' ? { type: 'connect' } : { type: 'authenticate', token })); };
+			ws.onmessage = event => {
+				if (generation !== this.#generation || this.#stopped) return;
+				let frame: any;
+				try { frame = JSON.parse(String(event.data)); } catch { this.#deny(); return; }
+				if (frame?.type === 'ready' && this.#state !== 'connected') {
+					clearTimeout(this.#deadline);
+					this.#attempt = 0;
+					this.#subscriptionQueue = [...this.#channels.keys()];
+					this.#subscribing = undefined;
+					this.#setState('connected');
+					this.#subscribeNext();
+				} else if (frame?.type === 'message' && this.#state === 'connected') this.#message(frame.data);
+				else this.#deny();
+			};
+			ws.onerror = () => { /* Native sockets report terminal failures through close. */ };
+			ws.onclose = event => {
+				if (generation !== this.#generation || this.#stopped) return;
+				this.#generation++;
+				clearTimeout(this.#deadline);
+				if ([4401, 4403, 1003, 1007, 1008, 1009].includes(event.code)) this.#deny();
+				else this.#retryLater();
+			};
+		} catch {
+			if (generation !== this.#generation || this.#stopped) return;
+			clearTimeout(this.#deadline);
+			this.#retryLater();
+		}
+	}
+
+	/** Stops retries on an authentication, policy or protocol failure until explicitly connected again. */
+	#deny(): void { this.close(); this.#setState('denied'); }
+
+	/** Retries transient failures with exponential backoff and jitter after blue/green shutdown. */
+	#retryLater(): void {
+		if (this.#stopped) return;
+		if (this.#options.reconnect === false) { this.close(); return; }
+		this.#setState('reconnecting');
+		const ceiling = Math.min(this.#options.maxReconnectDelayMs, 500 * 2 ** Math.min(this.#attempt++, 16));
+		this.#retry = setTimeout(() => void this.#open(), Math.max(1, Math.floor(ceiling * (0.5 + Math.random() * 0.5))));
+	}
+
+	/** Notifies state consumers only when the lifecycle actually changes. */
+	#setState(state: WebSocketClientState): void {
+		if (this.#state === state) return;
+		this.#state = state;
+		this.#options.onState?.(state);
+	}
+}
+
+/** Resolves the native browser constructor only when connecting, keeping imports SSR-safe. */
+function nativeSocket(url: string): ClientSocket {
+	const Constructor = (globalThis as unknown as { WebSocket: new (url: string) => ClientSocket }).WebSocket;
+	if (!Constructor) throw new Error('This runtime needs a WebSocket factory.');
+	return new Constructor(url);
+}

package/src/websocket/client/index.ts

@@ -0,0 +1,3 @@
+export { WebSocketClient } from './WebSocketClient';
+export type { ClientSocket, WebSocketClientOptions, WebSocketClientState } from '../contracts/WebSocketClient';
+export type { WebSocketClientChannel } from '../contracts/WebSocketClient';

package/src/websocket/contracts/WebSocketChannel.ts

@@ -0,0 +1,23 @@
+import type { WebSocketContext } from './WebSocketEndpoint';
+
+/** Current authenticated context and parameters extracted from a channel name. */
+export type WebSocketChannelContext = Omit<WebSocketContext, 'send' | 'close'> & {
+	/** Concrete requested channel, never trusted as proof of access. */
+	readonly channel: string;
+	/** Colon-delimited parameters matched by the server's definition. */
+	readonly params: Readonly<Record<string, string>>;
+};
+
+/** Application policy for a named resource channel. All subscriptions require authorization. */
+export interface WebSocketChannelDefinition {
+	/** Pattern such as website:{websiteId}:jobs. */
+	readonly pattern: string;
+	/** Pure access check, evaluated on subscription and before every delivery. */
+	authorize(context: WebSocketChannelContext): boolean | Promise<boolean>;
+}
+
+/** Server publisher for a concrete channel, including configured worker-to-API HTTP delivery. */
+export interface WebSocketChannelPublisher {
+	/** Returns accepted local sends, or zero after remote HTTP acceptance. Never a browser delivery receipt. */
+	publish(event: string, data: unknown): Promise<number>;
+}

package/src/websocket/contracts/WebSocketClient.ts

@@ -0,0 +1,48 @@
+/** Browser-visible lifecycle; connected means accepted under the endpoint's authentication policy. */
+export type WebSocketClientState = 'closed' | 'connecting' | 'connected' | 'reconnecting' | 'denied';
+
+/** Minimal native browser socket surface, also usable by Node integration clients. */
+export interface ClientSocket {
+	readonly readyState: number;
+	readonly bufferedAmount: number;
+	onopen: ((event: any) => void) | null;
+	/** Native implementations have different event types; the client reads only data. */
+	onmessage: ((event: any) => void) | null;
+	/** Native implementations have different event types; the client reads only code. */
+	onclose: ((event: any) => void) | null;
+	onerror: ((event: any) => void) | null;
+	send(data: string): void;
+	close(code?: number): void;
+}
+
+/** Options for the small JSON client. Incoming application data remains untrusted/unknown. */
+export interface WebSocketClientOptions {
+	/** Absolute ws(s) URL. Production applications must use wss. */
+	url: string;
+	/** Reads the existing bearer session afresh on every connection attempt. Never put it in the URL. */
+	token?(): string | null | Promise<string | null>;
+	/** Must match the endpoint: required (default), cookie (server token resolver), or public. */
+	auth?: 'required' | 'cookie' | 'public';
+	onMessage?(data: unknown): void;
+	/** Called after each successful subscription, including reconnect; reload durable state here. */
+	onSubscribed?(channel: string): void;
+	/** Called when a requested channel is unknown, ambiguous, denied or exceeds the subscription limit. */
+	onChannelDenied?(channel: string): void;
+	onState?(state: WebSocketClientState): void;
+	/** Defaults to true; authentication/policy denial and protocol failures never auto-retry. */
+	reconnect?: boolean;
+	/** Maximum delay between reconnect attempts. Default 30000 ms. */
+	maxReconnectDelayMs?: number;
+	/** Deadline including token acquisition, socket opening and server authentication. Default 10000 ms. */
+	connectTimeoutMs?: number;
+	/** Outgoing frame/queue limit. Default 64 KiB. */
+	maxBufferedBytes?: number;
+	/** Optional native-compatible factory for non-browser runtimes. */
+	createSocket?(url: string): ClientSocket;
+}
+
+/** Browser-side view of one logical channel on a shared connection. */
+export interface WebSocketClientChannel {
+	/** Adds a listener and subscribes on first use. Returns idempotent listener cleanup. Payloads require app validation. */
+	on(event: string, listener: (data: unknown) => void): () => void;
+}

package/src/websocket/contracts/WebSocketEndpoint.ts

@@ -0,0 +1,46 @@
+import type { WebSocketChannelDefinition } from './WebSocketChannel';
+import type { IncomingMessage } from 'node:http';
+import type { UserIdentity } from '../../auth';
+
+/** An accepted connection. Authenticated sends recheck the session; all sends recheck endpoint policy. */
+export interface WebSocketContext<TUser extends UserIdentity | null = UserIdentity> {
+	/** Stable connection identity for application-owned local subscriptions. */
+	readonly id: string;
+	/** Authenticated account ID, derived from framework Auth rather than client data. */
+	readonly userId: TUser extends UserIdentity ? string : null;
+	/** Fresh account model for this action. */
+	readonly user: TUser;
+	/** Original upgrade request; HTTP route hooks do not run for this transport. */
+	readonly request: IncomingMessage;
+	/** Aborted as soon as the connection closes or shutdown starts. */
+	readonly signal: AbortSignal;
+	/** Sends JSON after fresh authentication and endpoint policy checks. Optional resource guard uses that same fresh context; false means closed or denied. */
+	send(data: unknown, authorize?: (context: Omit<WebSocketContext<TUser>, 'send' | 'close'>) => boolean | Promise<boolean>): Promise<boolean>;
+	/** Ends the connection normally. */
+	close(): void;
+}
+
+/** Cleanup metadata; close handlers run without authenticated request context. */
+export interface WebSocketClosed {
+	id: string;
+	userId: string | null;
+	code: number;
+}
+
+/** Controller-style JSON endpoint. Authentication is required unless public access is explicit. */
+export interface WebSocketEndpoint<TMessage = unknown, TUser extends UserIdentity | null = UserIdentity> {
+	/** Authentication is required by default. Public endpoints explicitly opt out and always have null identity. */
+	auth?: TUser extends UserIdentity ? 'required' : 'public';
+	/** Additional resource/tenant authorization, rerun before each action and send. */
+	authorize?(context: Omit<WebSocketContext<TUser>, 'send' | 'close'>): boolean | Promise<boolean>;
+	/** Named channel policies on this shared endpoint. Anonymous endpoints cannot subscribe to private channels. */
+	channels?: readonly WebSocketChannelDefinition[];
+	/** Called once after authentication. May send initial application data. */
+	open?(context: WebSocketContext<TUser>): void | Promise<void>;
+	/** Validates untrusted JSON. Throwing closes with 1008; omitted messages remain unknown. */
+	parse?(data: unknown): TMessage | Promise<TMessage>;
+	/** Called sequentially for validated application messages in a fresh Auth context. */
+	message?(context: WebSocketContext<TUser>, data: TMessage): void | Promise<void>;
+	/** Releases application subscriptions. Must settle promptly and must not send data. */
+	close?(context: WebSocketClosed): void | Promise<void>;
+}