@zintrust/socket 0.4.58

package/README.md

@@ -0,0 +1,251 @@
+# @zintrust/socket
+
+Unified websocket runtime for ZinTrust across Node.js and Cloudflare Workers.
+
+This package gives you a Pusher-compatible socket surface without requiring you to hand-wire websocket upgrade routes into your app. On Node.js it handles raw `upgrade` requests directly in the core server. On Cloudflare Workers it uses a Durable Object hub so connected clients and publish requests share one coordination point instead of isolate-local memory.
+
+## What You Get
+
+- Automatic socket runtime registration through `@zintrust/socket/register`
+- Websocket upgrade endpoint at `GET {SOCKET_PATH}/:appKey`
+- Auth endpoint at `POST /broadcasting/auth`
+- Publish endpoint at `POST /apps/:appId/events`
+- Pusher-style events such as `pusher:connection_established`, `pusher:pong`, and `pusher_internal:subscription_succeeded`
+- Private and presence-channel auth signing via HMAC SHA-256
+- Node.js in-memory fan-out
+- Cloudflare Durable Object-backed fan-out via `ZT_SOCKET_HUB`
+
+## Install
+
+```bash
+npm i @zintrust/socket
+```
+
+If you are using official ZinTrust package auto-imports, installing the package is enough for runtime registration because core will attempt to import `@zintrust/socket/register` automatically.
+
+If you prefer an explicit local entrypoint in an app repository, you can still add one:
+
+```ts
+// src/socket-runtime.ts
+import '@zintrust/socket/register';
+```
+
+## Runtime Model
+
+### Node.js
+
+- ZinTrust core listens for HTTP `upgrade` events.
+- `@zintrust/socket` validates the app key and completes the websocket handshake.
+- Connected peers and channel memberships are stored in process memory.
+
+### Cloudflare Workers
+
+- ZinTrust core intercepts websocket upgrade requests before the normal HTTP adapter path.
+- The request is forwarded to the `ZT_SOCKET_HUB` Durable Object.
+- The Durable Object owns peer membership and publish fan-out for that app key.
+- Normal HTTP publish requests to `/apps/:appId/events` also forward into the same Durable Object, so websocket traffic and server-side publishes stay coordinated.
+
+## Minimum Env Setup
+
+```env
+SOCKET_ENABLED=true
+SOCKET_PATH=/app
+PUSHER_APP_ID=local-app
+PUSHER_APP_KEY=local-key
+PUSHER_APP_SECRET=local-secret
+```
+
+With that configuration your upgrade endpoint becomes:
+
+```text
+/app/local-key
+```
+
+## Supported Environment Variables
+
+The package supports multiple env aliases so you can keep existing Pusher/broadcast style naming.
+
+### Core toggles
+
+- `SOCKET_ENABLED`
+  Enables the unified socket runtime.
+- `SOCKET_TRANSPORT`
+  Allowed values: `auto`, `node`, `cloudflare`.
+  `auto` is the default.
+- `SOCKET_PATH`
+  Websocket upgrade base path. Default: `/app`.
+
+### App identity
+
+- `PUSHER_APP_ID`
+  Primary app identifier used by `/apps/:appId/events`.
+- `BROADCAST_APP_ID`
+  Fallback alias for app id.
+
+### Public auth key
+
+- `PUSHER_APP_KEY`
+  Primary public websocket/auth key.
+- `BROADCAST_AUTH_KEY`
+  Fallback alias for the public auth key.
+- `BROADCAST_APP_KEY`
+  Additional fallback alias for the public auth key.
+
+### Publish/auth secret
+
+- `PUSHER_APP_SECRET`
+  Primary signing secret for private/presence auth and publish authorization.
+- `BROADCAST_SECRET`
+  Fallback alias for the signing secret.
+- `BROADCAST_APP_SECRET`
+  Additional fallback alias for the signing secret.
+
+### Connection timing
+
+- `BROADCAST_ACTIVITY_TIMEOUT`
+  Activity timeout advertised to clients. Default: `120` seconds.
+
+### Cloudflare binding
+
+- `ZT_SOCKET_HUB`
+  Durable Object binding required for Cloudflare websocket coordination.
+
+## Cloudflare Worker Configuration
+
+Cloudflare support requires exporting the Durable Object class from the worker module and binding it in Wrangler.
+
+If your worker entry is `@zintrust/core/start` or ZinTrust's stock `src/functions/cloudflare.ts`, the `ZintrustSocketHub` export is already available.
+
+Add a binding like this to your Wrangler config:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "ZT_SOCKET_HUB",
+        "class_name": "ZintrustSocketHub",
+      },
+    ],
+  },
+  "migrations": [
+    {
+      "tag": "v1-zintrust-socket-hub",
+      "new_sqlite_classes": ["ZintrustSocketHub"],
+    },
+  ],
+}
+```
+
+## Example: Laravel Echo / Pusher-Style Client
+
+```ts
+import Echo from 'laravel-echo';
+import Pusher from 'pusher-js';
+
+const echo = new Echo({
+  broadcaster: 'pusher',
+  client: new Pusher('local-key', {
+    wsHost: '127.0.0.1',
+    wsPort: 7777,
+    wssPort: 443,
+    forceTLS: false,
+    enabledTransports: ['ws', 'wss'],
+    wsPath: '/app',
+    authEndpoint: '/broadcasting/auth',
+  }),
+});
+
+echo.private('orders').listen('.updated', (payload: unknown) => {
+  console.log(payload);
+});
+```
+
+For Cloudflare, keep the same client-side contract and only change the host/TLS settings for your deployed Worker domain.
+
+## Example: Publish From Server Code
+
+The package exposes an HTTP-compatible publish endpoint:
+
+```http
+POST /apps/local-app/events
+Authorization: Bearer local-secret
+Content-Type: application/json
+
+{
+  "event": "orders.updated",
+  "channel": "private-orders",
+  "data": {
+    "orderId": 42,
+    "status": "paid"
+  }
+}
+```
+
+Accepted publish authorization headers:
+
+- `Authorization: Bearer <secret>`
+- `x-zintrust-socket-secret: <secret>`
+
+You can also provide `channels` instead of `channel`, and `name` instead of `event`.
+
+## Example: Auth Request
+
+```http
+POST /broadcasting/auth
+Content-Type: application/json
+
+{
+  "socket_id": "123.456",
+  "channel_name": "private-orders",
+  "channel_data": "{\"user_id\":\"7\"}"
+}
+```
+
+Response shape:
+
+```json
+{
+  "auth": "local-key:<signature>",
+  "channel_data": "{\"user_id\":\"7\"}"
+}
+```
+
+## Endpoints Summary
+
+- `GET {SOCKET_PATH}/:appKey`
+  Returns `426 Upgrade Required` over HTTP and upgrades over websocket.
+- `POST /broadcasting/auth`
+  Signs private/presence subscriptions.
+- `POST /apps/:appId/events`
+  Publishes server-originated events to one or many channels.
+
+## Behavior Notes
+
+- Node.js fan-out is process-local. If you run multiple Node instances, use your own cross-node broadcast layer in front of this package.
+- Cloudflare fan-out is app-scoped through one Durable Object instance per socket app key.
+- If `SOCKET_TRANSPORT=node` is set, Cloudflare Durable Object forwarding is disabled intentionally.
+- If `SOCKET_ENABLED=true` on Cloudflare but `ZT_SOCKET_HUB` is missing, upgrade and publish requests return a `503` response explaining the missing binding.
+
+## Good Defaults For Local Development
+
+```env
+SOCKET_ENABLED=true
+SOCKET_TRANSPORT=auto
+SOCKET_PATH=/app
+PUSHER_APP_ID=local-app
+PUSHER_APP_KEY=local-key
+PUSHER_APP_SECRET=local-secret
+BROADCAST_ACTIVITY_TIMEOUT=45
+```
+
+## Troubleshooting
+
+- `404 Socket app key not found`:
+  Your client is connecting with a key that does not match the resolved app key env.
+- `403 Socket publish secret is invalid`:
+  The publish request secret does not match the resolved signing secret.
+- `503 socket_durable_object_missing`:
+  Cloudflare transport is active but Wrangler is missing the `ZT_SOCKET_HUB` binding.
+- `426 Upgrade Required` over HTTP:
+  You hit the websocket route with a normal HTTP request, which is expected for health/debug checks.

package/dist/build-manifest.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zintrust/socket",
+  "version": "0.4.58",
+  "buildDate": "2026-04-04T19:59:22.567Z",
+  "buildEnvironment": {
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "git": {
+    "commit": "99e4d331",
+    "branch": "release"
+  },
+  "package": {
+    "engines": {
+      "node": ">=20.0.0"
+    },
+    "dependencies": [],
+    "peerDependencies": [
+      "@zintrust/core"
+    ]
+  },
+  "files": {
+    "index.d.ts": {
+      "size": 932,
+      "sha256": "6432952783fd7eacfc46813fcbd6e96672ff94c73fb0bad8e2f20fc278c64377"
+    },
+    "index.js": {
+      "size": 28400,
+      "sha256": "972ccf9128c9915e3bbcf6f91f3332ab5d31e7aaa8ca828be838d231ef47eeb5"
+    },
+    "register.d.ts": {
+      "size": 16,
+      "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
+    },
+    "register.js": {
+      "size": 419,
+      "sha256": "e5c28fd549e3fd5dbee6a211608acb48fa4a8b4ef11b5823668510cde3d924c2"
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type IRouter, type SocketRouteRegistrar } from '@zintrust/core';
+declare const socketRuntime: any;
+declare const registerSocketRoutes: (router: IRouter) => void;
+declare const socketRouteRegistrar: SocketRouteRegistrar;
+export declare const SocketPackage: Readonly<{
+    runtime: any;
+    routeRegistrar: any;
+    publish: (channels: string[], event: string, data: unknown, excludeSocketId?: string) => number;
+    registerRoutes: (router: IRouter) => void;
+}>;
+export declare class ZintrustSocketHub {
+    private readonly settings;
+    private readonly state;
+    constructor(_state: unknown, env: unknown);
+    fetch(request: Request): Promise<Response>;
+    private handlePublishRequest;
+}
+export declare const publishSocketEvent: (channels: string[], event: string, data: unknown, excludeSocketId?: string) => number;
+export { registerSocketRoutes, socketRouteRegistrar, socketRuntime };
+export default SocketPackage;

package/dist/index.js

@@ -0,0 +1,746 @@
+import { Cloudflare, isArray, isNonEmptyString, Router, SocketFeature, } from '@zintrust/core';
+const encoder = new TextEncoder();
+const websocketGuid = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const socketHubBindingName = 'ZT_SOCKET_HUB';
+const socketInternalPublishPath = '/__zintrust/socket/publish';
+const jsonHeaders = Object.freeze({ 'content-type': 'application/json; charset=utf-8' });
+const createSocketState = () => {
+    return {
+        peers: new Map(),
+        channels: new Map(),
+    };
+};
+const getNodeSocketState = () => {
+    const globalSocketState = globalThis;
+    globalSocketState.__zintrustSocketState ??= createSocketState();
+    return globalSocketState.__zintrustSocketState;
+};
+const toEnvRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+const readEnvString = (source, key, fallback = '') => {
+    const value = source?.[key];
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    return String(value);
+};
+const readEnvBool = (source, key, fallback) => {
+    const raw = readEnvString(source, key, fallback ? 'true' : 'false')
+        .trim()
+        .toLowerCase();
+    if (raw === '')
+        return fallback;
+    return raw === 'true' || raw === '1' || raw === 'yes' || raw === 'on';
+};
+const readEnvInt = (source, key, fallback) => {
+    const raw = readEnvString(source, key, String(fallback)).trim();
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const normalizeSocketPath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed === '/')
+        return '/app';
+    const normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return normalized.length > 1 ? normalized.replace(/\/+$/, '') : normalized;
+};
+const pickFirstNonEmpty = (...values) => {
+    for (const value of values) {
+        if (value.trim() !== '') {
+            return value.trim();
+        }
+    }
+    return '';
+};
+const resolveTransport = (value) => {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'node' || normalized === 'cloudflare') {
+        return normalized;
+    }
+    return 'auto';
+};
+const getSocketRuntimeSettings = (envSource) => {
+    const source = toEnvRecord(envSource);
+    if (source === null) {
+        const settings = SocketFeature.getSettings();
+        return Object.freeze({
+            ...settings,
+            appId: settings.appId === '' ? 'local' : settings.appId,
+        });
+    }
+    return Object.freeze({
+        enabled: readEnvBool(source, 'SOCKET_ENABLED', false),
+        transport: resolveTransport(readEnvString(source, 'SOCKET_TRANSPORT', 'auto')),
+        path: normalizeSocketPath(readEnvString(source, 'SOCKET_PATH', '/app')),
+        appId: pickFirstNonEmpty(readEnvString(source, 'PUSHER_APP_ID', ''), readEnvString(source, 'BROADCAST_APP_ID', '')) || 'local',
+        appKey: pickFirstNonEmpty(readEnvString(source, 'PUSHER_APP_KEY', ''), readEnvString(source, 'BROADCAST_AUTH_KEY', ''), readEnvString(source, 'BROADCAST_APP_KEY', '')),
+        secret: pickFirstNonEmpty(readEnvString(source, 'PUSHER_APP_SECRET', ''), readEnvString(source, 'BROADCAST_SECRET', ''), readEnvString(source, 'BROADCAST_APP_SECRET', '')),
+        activityTimeout: readEnvInt(source, 'BROADCAST_ACTIVITY_TIMEOUT', 120),
+    });
+};
+const toJsonString = (value) => {
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value ?? {});
+};
+const createJsonResponse = (payload, status) => {
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: jsonHeaders,
+    });
+};
+const decodeText = (value) => {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof ArrayBuffer) {
+        return new TextDecoder().decode(value);
+    }
+    if (ArrayBuffer.isView(value)) {
+        return new TextDecoder().decode(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+    }
+    return '';
+};
+const getUpgradeHeader = (value) => {
+    if (Array.isArray(value))
+        return value[0] ?? '';
+    return value ?? '';
+};
+const getBearerToken = (value) => {
+    const normalized = value.trim();
+    if (!normalized.toLowerCase().startsWith('bearer '))
+        return '';
+    return normalized.slice('bearer '.length).trim();
+};
+const parseSocketPath = (pathname, settings) => {
+    const prefix = `${settings.path}/`;
+    if (!pathname.startsWith(prefix)) {
+        return null;
+    }
+    const remainder = pathname.slice(prefix.length);
+    if (remainder === '' || remainder.includes('/')) {
+        return null;
+    }
+    return decodeURIComponent(remainder);
+};
+const isWorkerUpgradeRequest = (request) => {
+    return request.headers.get('upgrade')?.trim().toLowerCase() === 'websocket';
+};
+const isNodeUpgradeRequest = (input, settings) => {
+    const pathname = new URL(input.request.url ?? '/', 'http://localhost').pathname;
+    return parseSocketPath(pathname, settings) !== null;
+};
+const toBase64 = (value) => {
+    const bytes = new Uint8Array(value);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCodePoint(byte);
+    }
+    return btoa(binary);
+};
+const toHex = (value) => {
+    return Array.from(new Uint8Array(value))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+};
+const sha1Base64 = async (value) => {
+    return toBase64(await globalThis.crypto.subtle.digest('SHA-1', encoder.encode(value)));
+};
+const hmacSha256Hex = async (secret, value) => {
+    const key = await globalThis.crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await globalThis.crypto.subtle.sign('HMAC', key, encoder.encode(value));
+    return toHex(signature);
+};
+const createSocketId = () => {
+    const token = globalThis.crypto.randomUUID().replaceAll('-', '').slice(0, 16);
+    const left = Number.parseInt(token.slice(0, 8), 16).toString();
+    const right = Number.parseInt(token.slice(8, 16), 16).toString();
+    return `${left}.${right}`;
+};
+const removeFromChannel = (state, channel, peerId) => {
+    const members = state.channels.get(channel);
+    if (members === undefined)
+        return;
+    members.delete(peerId);
+    if (members.size === 0) {
+        state.channels.delete(channel);
+    }
+};
+const detachPeer = (state, peer) => {
+    state.peers.delete(peer.id);
+    for (const channel of peer.subscriptions) {
+        removeFromChannel(state, channel, peer.id);
+    }
+    peer.subscriptions.clear();
+};
+const addPeerToChannel = (state, channel, peer) => {
+    const existing = state.channels.get(channel);
+    if (existing === undefined) {
+        state.channels.set(channel, new Set([peer.id]));
+    }
+    else {
+        existing.add(peer.id);
+    }
+    peer.subscriptions.add(channel);
+};
+const createEnvelope = (event, data, channel) => {
+    const payload = {
+        event,
+        data: toJsonString(data),
+    };
+    if (channel !== undefined) {
+        payload['channel'] = channel;
+    }
+    return JSON.stringify(payload);
+};
+const emitConnectionEstablished = (peer, settings) => {
+    peer.sendText(createEnvelope('pusher:connection_established', {
+        socket_id: peer.id,
+        activity_timeout: settings.activityTimeout,
+    }));
+};
+const emitSubscriptionSucceeded = (peer, channel) => {
+    peer.sendText(createEnvelope('pusher_internal:subscription_succeeded', {}, channel));
+};
+const emitPong = (peer) => {
+    peer.sendText(createEnvelope('pusher:pong', {}));
+};
+const getPublishSecret = (request) => {
+    const directHeader = request.getHeader('x-zintrust-socket-secret');
+    const authHeader = request.getHeader('authorization');
+    const fromDirect = getUpgradeHeader(typeof directHeader === 'string' ? directHeader : null).trim();
+    if (fromDirect !== '')
+        return fromDirect;
+    return getBearerToken(getUpgradeHeader(typeof authHeader === 'string' ? authHeader : null));
+};
+const validatePrivateChannelAuth = async (peer, channel, authValue, channelData, settings) => {
+    if (settings.secret.trim() === '' || settings.appKey.trim() === '') {
+        return false;
+    }
+    const [authKey, signature] = authValue.split(':');
+    if (authKey !== settings.appKey || !isNonEmptyString(signature)) {
+        return false;
+    }
+    const payload = channelData === undefined ? `${peer.id}:${channel}` : `${peer.id}:${channel}:${channelData}`;
+    return (await hmacSha256Hex(settings.secret, payload)) === signature;
+};
+const isPrivateChannel = (channel) => {
+    return channel.startsWith('private-') || channel.startsWith('presence-');
+};
+const publishToChannels = (state, channels, event, data, excludeSocketId) => {
+    const delivered = new Set();
+    for (const channel of channels) {
+        const members = state.channels.get(channel);
+        if (members === undefined)
+            continue;
+        for (const peerId of members) {
+            if (peerId === excludeSocketId)
+                continue;
+            const peer = state.peers.get(peerId);
+            if (peer === undefined)
+                continue;
+            peer.sendText(createEnvelope(event, data, channel));
+            delivered.add(peerId);
+        }
+    }
+    return delivered.size;
+};
+const parseJsonObject = (value) => {
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed === null || Array.isArray(parsed) || typeof parsed !== 'object') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+const handleSubscribe = async (state, peer, payload, settings) => {
+    const channel = isNonEmptyString(payload.channel) ? payload.channel.trim() : '';
+    if (channel === '') {
+        return;
+    }
+    if (isPrivateChannel(channel)) {
+        const auth = isNonEmptyString(payload.auth) ? payload.auth.trim() : '';
+        const channelData = isNonEmptyString(payload.channel_data) ? payload.channel_data : undefined;
+        if (!(await validatePrivateChannelAuth(peer, channel, auth, channelData, settings))) {
+            peer.sendText(createEnvelope('pusher:error', { message: 'Subscription auth failed.' }));
+            return;
+        }
+    }
+    addPeerToChannel(state, channel, peer);
+    emitSubscriptionSucceeded(peer, channel);
+};
+const handleClientMessage = async (state, peer, text, settings) => {
+    const payload = parseJsonObject(text);
+    if (payload === null) {
+        return;
+    }
+    const eventName = isNonEmptyString(payload['event']) ? payload['event'].trim() : '';
+    const dataRaw = payload['data'];
+    const data = typeof dataRaw === 'string' ? (parseJsonObject(dataRaw) ?? dataRaw) : dataRaw;
+    if (eventName === 'pusher:ping') {
+        emitPong(peer);
+        return;
+    }
+    if (eventName === 'pusher:subscribe' && data !== null && typeof data === 'object') {
+        await handleSubscribe(state, peer, data, settings);
+        return;
+    }
+    if (eventName === 'pusher:unsubscribe' && data !== null && typeof data === 'object') {
+        const candidate = data.channel;
+        const channel = isNonEmptyString(candidate) ? candidate.trim() : '';
+        if (channel !== '') {
+            peer.subscriptions.delete(channel);
+            removeFromChannel(state, channel, peer.id);
+        }
+    }
+};
+const encodeFrame = (opcode, payload) => {
+    const header = [0x80 | (opcode & 0x0f)];
+    if (payload.length < 126) {
+        header.push(payload.length);
+    }
+    else if (payload.length <= 0xffff) {
+        header.push(126, (payload.length >> 8) & 0xff, payload.length & 0xff);
+    }
+    else {
+        const high = Math.floor(payload.length / 2 ** 32);
+        const low = payload.length >>> 0;
+        header.push(127, (high >> 24) & 0xff, (high >> 16) & 0xff, (high >> 8) & 0xff, high & 0xff, (low >> 24) & 0xff, (low >> 16) & 0xff, (low >> 8) & 0xff, low & 0xff);
+    }
+    return Buffer.concat([Buffer.from(header), Buffer.from(payload)]);
+};
+const parseFrame = (buffer) => {
+    if (buffer.length < 2)
+        return null;
+    const second = buffer[1];
+    const opcode = buffer[0] & 0x0f;
+    const masked = (second & 0x80) !== 0;
+    let length = second & 0x7f;
+    let offset = 2;
+    if (length === 126) {
+        if (buffer.length < 4)
+            return null;
+        length = buffer.readUInt16BE(2);
+        offset = 4;
+    }
+    else if (length === 127) {
+        if (buffer.length < 10)
+            return null;
+        const high = buffer.readUInt32BE(2);
+        const low = buffer.readUInt32BE(6);
+        length = high * 2 ** 32 + low;
+        offset = 10;
+    }
+    const maskOffset = masked ? 4 : 0;
+    if (buffer.length < offset + maskOffset + length) {
+        return null;
+    }
+    const payload = buffer.subarray(offset + maskOffset, offset + maskOffset + length);
+    if (masked) {
+        const mask = buffer.subarray(offset, offset + 4);
+        const decoded = Buffer.alloc(length);
+        for (let index = 0; index < length; index += 1) {
+            decoded[index] = payload[index] ^ mask[index % 4];
+        }
+        return { opcode, payload: decoded, bytesConsumed: offset + 4 + length };
+    }
+    return { opcode, payload, bytesConsumed: offset + length };
+};
+const createNodePeer = (state, socket) => {
+    const peer = {
+        id: createSocketId(),
+        subscriptions: new Set(),
+        sendText(text) {
+            socket.write(encodeFrame(0x1, encoder.encode(text)));
+        },
+        close(code = 1000, reason = '') {
+            const body = Buffer.alloc(2 + Buffer.byteLength(reason));
+            body.writeUInt16BE(code, 0);
+            body.write(reason, 2);
+            socket.write(encodeFrame(0x8, body));
+            socket.end();
+        },
+    };
+    state.peers.set(peer.id, peer);
+    socket.on('close', () => detachPeer(state, peer));
+    socket.on('error', () => detachPeer(state, peer));
+    return peer;
+};
+const createWorkerPeer = (state, socket) => {
+    const peer = {
+        id: createSocketId(),
+        subscriptions: new Set(),
+        sendText(text) {
+            socket.send(text);
+        },
+        close(code = 1000, reason = '') {
+            socket.close(code, reason);
+        },
+    };
+    state.peers.set(peer.id, peer);
+    return peer;
+};
+const attachNodePeer = async (state, input, settings) => {
+    const key = input.request.headers['sec-websocket-key'];
+    const secKey = Array.isArray(key) ? key[0] : key;
+    if (!isNonEmptyString(secKey)) {
+        return false;
+    }
+    const acceptKey = await sha1Base64(`${secKey.trim()}${websocketGuid}`);
+    input.socket.write([
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${acceptKey}`,
+        '\r\n',
+    ].join('\r\n'));
+    const peer = createNodePeer(state, input.socket);
+    emitConnectionEstablished(peer, settings);
+    let frameBuffer = input.head.length > 0 ? Buffer.from(input.head) : Buffer.alloc(0);
+    const consumeFrames = async () => {
+        while (true) {
+            const frame = parseFrame(frameBuffer);
+            if (frame === null)
+                return;
+            frameBuffer = frameBuffer.subarray(frame.bytesConsumed);
+            if (frame.opcode === 0x8) {
+                peer.close();
+                return;
+            }
+            if (frame.opcode === 0x9) {
+                input.socket.write(encodeFrame(0xa, frame.payload));
+                continue;
+            }
+            if (frame.opcode === 0x1) {
+                // eslint-disable-next-line no-await-in-loop
+                await handleClientMessage(state, peer, frame.payload.toString('utf-8'), settings);
+            }
+        }
+    };
+    input.socket.on('data', (chunk) => {
+        frameBuffer = Buffer.concat([frameBuffer, chunk]);
+        void consumeFrames();
+    });
+    if (frameBuffer.length > 0) {
+        await consumeFrames();
+    }
+    return true;
+};
+const attachWorkerPeer = (state, socket, settings) => {
+    const peer = createWorkerPeer(state, socket);
+    emitConnectionEstablished(peer, settings);
+    socket.addEventListener('message', (event) => {
+        void handleClientMessage(state, peer, decodeText(event.data), settings);
+    });
+    socket.addEventListener('close', () => detachPeer(state, peer));
+    socket.addEventListener('error', () => detachPeer(state, peer));
+};
+const getSocketAppKey = (requestPath, settings) => {
+    return parseSocketPath(requestPath, settings);
+};
+const getSocketHubNamespace = (envSource) => {
+    const source = toEnvRecord(envSource) ?? Cloudflare.getWorkersEnv();
+    if (source === null) {
+        return null;
+    }
+    const candidate = source[socketHubBindingName];
+    if (typeof candidate !== 'object' || candidate === null) {
+        return null;
+    }
+    const namespace = candidate;
+    if (typeof namespace.getByName === 'function') {
+        return namespace;
+    }
+    if (typeof namespace.idFromName === 'function' && typeof namespace.get === 'function') {
+        return namespace;
+    }
+    return null;
+};
+const getSocketHubStub = (settings, envSource) => {
+    const namespace = getSocketHubNamespace(envSource);
+    if (namespace === null) {
+        return null;
+    }
+    const objectName = `socket-app:${settings.appId}:${settings.appKey}`;
+    if (typeof namespace.getByName === 'function') {
+        return namespace.getByName(objectName);
+    }
+    if (typeof namespace.idFromName === 'function' && typeof namespace.get === 'function') {
+        return namespace.get(namespace.idFromName(objectName));
+    }
+    return null;
+};
+const createMissingHubResponse = () => {
+    return createJsonResponse({
+        error: 'socket_durable_object_missing',
+        message: 'Cloudflare socket transport requires a Durable Object binding named ZT_SOCKET_HUB.',
+    }, 503);
+};
+const shouldUseCloudflareHub = (settings) => {
+    if (settings.transport === 'node') {
+        return false;
+    }
+    return Cloudflare.getWorkersEnv() !== null;
+};
+const parseJsonResponse = async (response) => {
+    try {
+        return (await response.clone().json());
+    }
+    catch {
+        try {
+            return await response.text();
+        }
+        catch {
+            return null;
+        }
+    }
+};
+const parsePublishPayload = (payload) => {
+    let event = '';
+    if (isNonEmptyString(payload.name)) {
+        event = payload.name.trim();
+    }
+    else if (isNonEmptyString(payload.event)) {
+        event = payload.event.trim();
+    }
+    let channels = [];
+    if (isArray(payload.channels)) {
+        channels = payload.channels.filter(isNonEmptyString).map((item) => item.trim());
+    }
+    else if (isNonEmptyString(payload.channel)) {
+        channels = [payload.channel.trim()];
+    }
+    if (event === '' || channels.length === 0) {
+        return null;
+    }
+    return {
+        channels,
+        event,
+        data: payload.data ?? {},
+        ...(isNonEmptyString(payload.socket_id) ? { socket_id: payload.socket_id.trim() } : {}),
+    };
+};
+const forwardPublishToHub = async (settings, payload, envSource) => {
+    const stub = getSocketHubStub(settings, envSource);
+    if (stub === null) {
+        return createMissingHubResponse();
+    }
+    return stub.fetch(new Request(`https://zintrust-socket.internal${socketInternalPublishPath}`, {
+        method: 'POST',
+        headers: jsonHeaders,
+        body: JSON.stringify(payload),
+    }));
+};
+const getWebSocketPairCtor = () => {
+    return globalThis.WebSocketPair;
+};
+const createSocketRuntime = () => {
+    const shouldEnable = () => {
+        const settings = getSocketRuntimeSettings();
+        return settings.enabled && settings.appKey.trim() !== '';
+    };
+    return Object.freeze({
+        name: '@zintrust/socket',
+        isEnabled: shouldEnable,
+        describe() {
+            const settings = getSocketRuntimeSettings();
+            const transport = typeof getWebSocketPairCtor() === 'function' ? 'cloudflare' : 'node';
+            return {
+                enabled: shouldEnable(),
+                transport,
+                path: settings.path,
+                appKeyConfigured: settings.appKey.trim() !== '',
+            };
+        },
+        canHandleNodeUpgrade(input) {
+            const settings = getSocketRuntimeSettings();
+            if (settings.transport === 'cloudflare')
+                return false;
+            return isNodeUpgradeRequest(input, settings);
+        },
+        async handleNodeUpgrade(input) {
+            const settings = getSocketRuntimeSettings();
+            const pathname = new URL(input.request.url ?? '/', 'http://localhost').pathname;
+            const appKey = getSocketAppKey(pathname, settings);
+            if (appKey === null || appKey !== settings.appKey) {
+                return false;
+            }
+            return attachNodePeer(getNodeSocketState(), input, settings);
+        },
+        canHandleWorkerRequest(request) {
+            const settings = getSocketRuntimeSettings();
+            if (settings.transport === 'node')
+                return false;
+            if (!isWorkerUpgradeRequest(request))
+                return false;
+            return getSocketAppKey(new URL(request.url).pathname, settings) !== null;
+        },
+        async handleWorkerRequest(request, context) {
+            const settings = getSocketRuntimeSettings(context.env);
+            const appKey = getSocketAppKey(new URL(request.url).pathname, settings);
+            if (appKey === null || appKey !== settings.appKey) {
+                return null;
+            }
+            const stub = getSocketHubStub(settings, context.env);
+            if (stub === null) {
+                return createMissingHubResponse();
+            }
+            return stub.fetch(request);
+        },
+    });
+};
+const socketRuntime = createSocketRuntime();
+const respondUpgradeRequired = (req, res) => {
+    const settings = getSocketRuntimeSettings();
+    const appKey = req.getParam('appKey');
+    if (!isNonEmptyString(appKey) || appKey.trim() !== settings.appKey) {
+        res.setStatus(404).json({ error: 'Socket app key not found.' });
+        return;
+    }
+    res.setStatus(426).json({
+        error: 'Upgrade Required',
+        message: 'Open this endpoint with a WebSocket upgrade request.',
+        path: `${settings.path}/${settings.appKey}`,
+    });
+};
+const authenticateSubscription = async (req, res) => {
+    const settings = getSocketRuntimeSettings();
+    if (settings.secret.trim() === '' || settings.appKey.trim() === '') {
+        res.setStatus(503).json({ error: 'Socket auth is not configured.' });
+        return;
+    }
+    const body = req.getBody();
+    const payload = body !== null && typeof body === 'object' ? body : {};
+    const socketId = isNonEmptyString(payload['socket_id']) ? payload['socket_id'].trim() : '';
+    const channelName = isNonEmptyString(payload['channel_name'])
+        ? payload['channel_name'].trim()
+        : '';
+    const channelData = isNonEmptyString(payload['channel_data'])
+        ? payload['channel_data'].trim()
+        : undefined;
+    if (socketId === '' || channelName === '') {
+        res.setStatus(400).json({ error: 'socket_id and channel_name are required.' });
+        return;
+    }
+    const signature = await hmacSha256Hex(settings.secret, channelData === undefined
+        ? `${socketId}:${channelName}`
+        : `${socketId}:${channelName}:${channelData}`);
+    res.json({
+        auth: `${settings.appKey}:${signature}`,
+        ...(channelData === undefined ? {} : { channel_data: channelData }),
+    });
+};
+const publishEvent = async (req, res) => {
+    const settings = getSocketRuntimeSettings();
+    const appId = req.getParam('appId');
+    if (!isNonEmptyString(appId) || appId.trim() !== settings.appId) {
+        res.setStatus(404).json({ error: 'Socket app id not found.' });
+        return;
+    }
+    if (settings.secret.trim() !== '') {
+        const providedSecret = getPublishSecret(req);
+        if (providedSecret !== settings.secret) {
+            res.setStatus(403).json({ error: 'Socket publish secret is invalid.' });
+            return;
+        }
+    }
+    const payload = req.getBody();
+    const body = payload !== null && typeof payload === 'object' ? payload : {};
+    const normalizedPayload = parsePublishPayload(body);
+    if (normalizedPayload === null) {
+        res.setStatus(400).json({ error: 'event/name and channel/channels are required.' });
+        return;
+    }
+    if (shouldUseCloudflareHub(settings)) {
+        const response = await forwardPublishToHub(settings, normalizedPayload, Cloudflare.getWorkersEnv());
+        const responseBody = await parseJsonResponse(response);
+        res.setStatus(response.status).json(responseBody);
+        return;
+    }
+    const deliveries = publishToChannels(getNodeSocketState(), normalizedPayload.channels, normalizedPayload.event, normalizedPayload.data, normalizedPayload.socket_id);
+    res.setStatus(202).json({
+        ok: true,
+        channels: normalizedPayload.channels,
+        event: normalizedPayload.event,
+        deliveries,
+    });
+};
+const registerSocketRoutes = (router) => {
+    const settings = getSocketRuntimeSettings();
+    Router.get(router, `${settings.path}/:appKey`, respondUpgradeRequired);
+    Router.post(router, '/broadcasting/auth', authenticateSubscription);
+    Router.post(router, '/apps/:appId/events', publishEvent);
+};
+const socketRouteRegistrar = Object.freeze({
+    registerRoutes: registerSocketRoutes,
+});
+export const SocketPackage = Object.freeze({
+    runtime: socketRuntime,
+    routeRegistrar: socketRouteRegistrar,
+    publish: (channels, event, data, excludeSocketId) => publishToChannels(getNodeSocketState(), channels, event, data, excludeSocketId),
+    registerRoutes: registerSocketRoutes,
+});
+// eslint-disable-next-line no-restricted-syntax -- Cloudflare Durable Objects require class exports.
+export class ZintrustSocketHub {
+    settings;
+    state;
+    constructor(_state, env) {
+        this.settings = getSocketRuntimeSettings(env);
+        this.state = createSocketState();
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === 'POST' && url.pathname === socketInternalPublishPath) {
+            return this.handlePublishRequest(request);
+        }
+        if (!isWorkerUpgradeRequest(request)) {
+            return createJsonResponse({
+                error: 'not_found',
+                message: 'Unknown socket Durable Object route.',
+            }, 404);
+        }
+        const appKey = getSocketAppKey(url.pathname, this.settings);
+        if (appKey === null || appKey !== this.settings.appKey) {
+            return createJsonResponse({ error: 'Socket app key not found.' }, 404);
+        }
+        const WebSocketPairRef = getWebSocketPairCtor();
+        if (typeof WebSocketPairRef !== 'function') {
+            return createJsonResponse({ error: 'WebSocketPair is unavailable in this runtime.' }, 501);
+        }
+        const pair = new WebSocketPairRef();
+        const client = pair[0];
+        const server = pair[1];
+        server.accept();
+        attachWorkerPeer(this.state, server, this.settings);
+        return new Response(null, { status: 101, webSocket: client });
+    }
+    async handlePublishRequest(request) {
+        const body = parseJsonObject(await request.text());
+        if (body === null) {
+            return createJsonResponse({ error: 'Invalid socket publish payload.' }, 400);
+        }
+        const payload = parsePublishPayload(body);
+        if (payload === null) {
+            return createJsonResponse({ error: 'event/name and channel/channels are required.' }, 400);
+        }
+        const deliveries = publishToChannels(this.state, payload.channels, payload.event, payload.data, payload.socket_id);
+        return createJsonResponse({
+            ok: true,
+            channels: payload.channels,
+            event: payload.event,
+            deliveries,
+        }, 202);
+    }
+}
+export const publishSocketEvent = (channels, event, data, excludeSocketId) => {
+    return publishToChannels(getNodeSocketState(), channels, event, data, excludeSocketId);
+};
+export { registerSocketRoutes, socketRouteRegistrar, socketRuntime };
+export default SocketPackage;

package/dist/register.d.ts

@@ -0,0 +1 @@
+export type {};

package/dist/register.js

@@ -0,0 +1,14 @@
+import { socketRouteRegistrar, socketRuntime } from './index.js';
+const importCore = async () => {
+    try {
+        return (await import('@zintrust/core'));
+    }
+    catch {
+        return {};
+    }
+};
+const core = await importCore();
+if (core.SocketRuntimeRegistry !== undefined) {
+    core.SocketRuntimeRegistry.registerRuntime(socketRuntime);
+    core.SocketRuntimeRegistry.registerRoutes(socketRouteRegistrar);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zintrust/socket",
+  "version": "0.4.58",
+  "description": "Unified socket runtime for ZinTrust.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@zintrust/core": "^0.4.58"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zintrust",
+    "socket",
+    "websocket",
+    "broadcast"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  }
+}