@zintrust/socket 0.4.58 → 0.4.59

package/README.md

@@ -189,6 +189,50 @@ Accepted publish authorization headers:
 
 You can also provide `channels` instead of `channel`, and `name` instead of `event`.
 
+## Example: Core-Owned Policy Hooks
+
+Projects can keep the transport routes owned by core while still supplying business rules through `config/broadcast.ts`.
+
+```ts
+export default {
+  default: 'inmemory',
+  socket: {
+    authMiddleware: ['auth', 'jwt'],
+    async authorize(_request, context) {
+      if (context.channelName.startsWith('private-')) {
+        return {
+          authorized: context.user !== null && context.user !== undefined,
+        };
+      }
+
+      if (context.channelName.startsWith('public-')) {
+        return {
+          authorized: true,
+        };
+      }
+
+      return {
+        authorized: false,
+      };
+    },
+    async publish(_request, context) {
+      if (context.event.startsWith('admin.')) {
+        return {
+          allowed: context.user !== null && context.user !== undefined,
+          message: 'Admin publish requires an authenticated user.',
+        };
+      }
+
+      return {
+        allowed: true,
+      };
+    },
+  },
+};
+```
+
+The publish hook may also rewrite the outgoing event, channels, data, or `socketId` before the framework fans the event out.
+
 ## Example: Auth Request
 
 ```http

package/dist/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@zintrust/socket",
-  "version": "0.4.58",
-  "buildDate": "2026-04-04T19:59:22.567Z",
+  "version": "0.4.59",
+  "buildDate": "2026-04-04T22:09:08.837Z",
   "buildEnvironment": {
     "node": "v22.22.1",
     "platform": "darwin",
@@ -21,21 +21,25 @@
     ]
   },
   "files": {
+    "build-manifest.json": {
+      "size": 947,
+      "sha256": "2e619502513f9b465881fdb6cb9cda78bb082e6df9bc20d4f1d62a1f7173174b"
+    },
     "index.d.ts": {
       "size": 932,
       "sha256": "6432952783fd7eacfc46813fcbd6e96672ff94c73fb0bad8e2f20fc278c64377"
     },
     "index.js": {
-      "size": 28400,
-      "sha256": "972ccf9128c9915e3bbcf6f91f3332ab5d31e7aaa8ca828be838d231ef47eeb5"
+      "size": 35358,
+      "sha256": "6a43f6cdc1591b1dc7304e5ccd66be1e41aaa7419546eb0258a280b8ea9b8642"
     },
     "register.d.ts": {
       "size": 16,
       "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
     },
     "register.js": {
-      "size": 419,
-      "sha256": "e5c28fd549e3fd5dbee6a211608acb48fa4a8b4ef11b5823668510cde3d924c2"
+      "size": 744,
+      "sha256": "a3233333a9dfc2357a198aac093cc4dfa1a3e83bb4285c52fce639f0ab1364ad"
     }
   }
 }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Cloudflare, isArray, isNonEmptyString, Router, SocketFeature, } from '@zintrust/core';
+import { Cloudflare, broadcastConfig, ErrorFactory, isArray, isNonEmptyString, Logger, middlewareConfig, Router, SocketFeature, } from '@zintrust/core';
 const encoder = new TextEncoder();
 const websocketGuid = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 const socketHubBindingName = 'ZT_SOCKET_HUB';
@@ -502,6 +502,114 @@ const parseJsonResponse = async (response) => {
         }
     }
 };
+const isSocketAuthorizerHandler = (value) => {
+    return typeof value === 'function';
+};
+const isSocketAuthorizer = (value) => {
+    const candidate = value;
+    return typeof value === 'object' && value !== null && typeof candidate?.authorize === 'function';
+};
+const createDefaultSocketAuthorizer = () => {
+    return Object.freeze({
+        async authorize(_request, context) {
+            if (context.channelName.startsWith('private-') ||
+                context.channelName.startsWith('presence-')) {
+                return {
+                    authorized: context.user !== null && context.user !== undefined,
+                };
+            }
+            return {
+                authorized: false,
+            };
+        },
+    });
+};
+const resolveSocketAuthorizer = () => {
+    const configured = broadcastConfig.socket.authorize;
+    if (configured === undefined) {
+        return createDefaultSocketAuthorizer();
+    }
+    if (isSocketAuthorizerHandler(configured)) {
+        return Object.freeze({
+            authorize: configured,
+        });
+    }
+    if (isSocketAuthorizer(configured)) {
+        return configured;
+    }
+    throw ErrorFactory.createConfigError('broadcastConfig.socket.authorize must be a function or an object with an authorize(request, context) method.');
+};
+const isSocketPublishPolicyHandler = (value) => {
+    return typeof value === 'function';
+};
+const isSocketPublishPolicy = (value) => {
+    const candidate = value;
+    return typeof value === 'object' && value !== null && typeof candidate?.authorize === 'function';
+};
+const createDefaultSocketPublishPolicy = () => {
+    return Object.freeze({
+        async authorize() {
+            return {
+                allowed: true,
+            };
+        },
+    });
+};
+const resolveSocketPublishPolicy = () => {
+    const configured = broadcastConfig.socket.publish;
+    if (configured === undefined) {
+        return createDefaultSocketPublishPolicy();
+    }
+    if (isSocketPublishPolicyHandler(configured)) {
+        return Object.freeze({
+            authorize: configured,
+        });
+    }
+    if (isSocketPublishPolicy(configured)) {
+        return configured;
+    }
+    throw ErrorFactory.createConfigError('broadcastConfig.socket.publish must be a function or an object with an authorize(request, context) method.');
+};
+const resolveSocketAuthMiddleware = () => {
+    const configured = broadcastConfig.socket.authMiddleware
+        .filter(isNonEmptyString)
+        .map((value) => value.trim())
+        .filter((value) => value !== '');
+    const middleware = configured.length > 0 ? configured : ['auth'];
+    const known = new Set(Object.keys(middlewareConfig.route));
+    const unknown = middleware.filter((value) => !known.has(value));
+    if (unknown.length > 0) {
+        throw ErrorFactory.createConfigError(`Unknown socket auth middleware configured: ${unknown.join(', ')}`);
+    }
+    return middleware;
+};
+const isSocketAuthRouteOverrideEnabled = () => {
+    return broadcastConfig.socket.allowAuthRouteOverride === true;
+};
+const routeExists = (router, method, path) => {
+    return router.routes.some((route) => route.method === method && route.path === path);
+};
+const assertReservedSocketRouteAvailable = (router, method, path, options) => {
+    if (!routeExists(router, method, path)) {
+        return;
+    }
+    if (options?.allowOverride === true && isSocketAuthRouteOverrideEnabled()) {
+        return;
+    }
+    throw ErrorFactory.createConfigError(`Socket compatibility route ${method} ${path} is reserved while sockets are enabled.`);
+};
+const createSocketAuthPayload = async (settings, socketId, channelName, channelData) => {
+    if (settings.secret.trim() === '' || settings.appKey.trim() === '') {
+        throw ErrorFactory.createConfigError('Socket auth is not configured.');
+    }
+    const signature = await hmacSha256Hex(settings.secret, channelData === undefined
+        ? `${socketId}:${channelName}`
+        : `${socketId}:${channelName}:${channelData}`);
+    return {
+        auth: `${settings.appKey}:${signature}`,
+        ...(channelData === undefined ? {} : { channel_data: channelData }),
+    };
+};
 const parsePublishPayload = (payload) => {
     let event = '';
     if (isNonEmptyString(payload.name)) {
@@ -527,6 +635,29 @@ const parsePublishPayload = (payload) => {
         ...(isNonEmptyString(payload.socket_id) ? { socket_id: payload.socket_id.trim() } : {}),
     };
 };
+const normalizePublishDecisionPayload = (payload, decision) => {
+    const event = isNonEmptyString(decision.event) ? decision.event.trim() : payload.event;
+    const channels = isArray(decision.channels)
+        ? decision.channels.filter(isNonEmptyString).map((item) => item.trim())
+        : payload.channels;
+    if (event === '' || channels.length === 0) {
+        return null;
+    }
+    return {
+        channels,
+        event,
+        data: decision.data === undefined ? payload.data : decision.data,
+        ...(() => {
+            if (isNonEmptyString(decision.socketId)) {
+                return { socket_id: decision.socketId.trim() };
+            }
+            if (payload.socket_id === undefined) {
+                return {};
+            }
+            return { socket_id: payload.socket_id };
+        })(),
+    };
+};
 const forwardPublishToHub = async (settings, payload, envSource) => {
     const stub = getSocketHubStub(settings, envSource);
     if (stub === null) {
@@ -612,10 +743,6 @@ const respondUpgradeRequired = (req, res) => {
 };
 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() : '';
@@ -629,13 +756,28 @@ const authenticateSubscription = async (req, res) => {
         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 authorizer = resolveSocketAuthorizer();
+    const decision = await authorizer.authorize(req, {
+        channelName,
+        socketId,
+        user: req.user ?? null,
+        channelData,
     });
+    if (decision.authorized !== true) {
+        res.setStatus(403).json({ message: 'Forbidden' });
+        return;
+    }
+    const resolvedChannelData = isNonEmptyString(decision.channelData)
+        ? decision.channelData.trim()
+        : channelData;
+    if (isNonEmptyString(decision.auth)) {
+        res.json({
+            auth: decision.auth.trim(),
+            ...(resolvedChannelData === undefined ? {} : { channel_data: resolvedChannelData }),
+        });
+        return;
+    }
+    res.json(await createSocketAuthPayload(settings, socketId, channelName, resolvedChannelData));
 };
 const publishEvent = async (req, res) => {
     const settings = getSocketRuntimeSettings();
@@ -658,24 +800,66 @@ const publishEvent = async (req, res) => {
         res.setStatus(400).json({ error: 'event/name and channel/channels are required.' });
         return;
     }
+    const publishPolicy = resolveSocketPublishPolicy();
+    const decision = await publishPolicy.authorize(req, {
+        appId: appId.trim(),
+        channels: normalizedPayload.channels,
+        event: normalizedPayload.event,
+        data: normalizedPayload.data,
+        socketId: normalizedPayload.socket_id,
+        user: req.user ?? null,
+    });
+    if (decision.allowed !== true) {
+        res.setStatus(decision.statusCode ?? 403).json({
+            message: decision.message ?? 'Forbidden',
+        });
+        return;
+    }
+    const allowedPayload = normalizePublishDecisionPayload(normalizedPayload, decision);
+    if (allowedPayload === null) {
+        res
+            .setStatus(400)
+            .json({ error: 'publish policy must return a non-empty event and channels.' });
+        return;
+    }
     if (shouldUseCloudflareHub(settings)) {
-        const response = await forwardPublishToHub(settings, normalizedPayload, Cloudflare.getWorkersEnv());
+        const response = await forwardPublishToHub(settings, allowedPayload, 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);
+    const deliveries = publishToChannels(getNodeSocketState(), allowedPayload.channels, allowedPayload.event, allowedPayload.data, allowedPayload.socket_id);
     res.setStatus(202).json({
         ok: true,
-        channels: normalizedPayload.channels,
-        event: normalizedPayload.event,
+        channels: allowedPayload.channels,
+        event: allowedPayload.event,
         deliveries,
     });
 };
 const registerSocketRoutes = (router) => {
     const settings = getSocketRuntimeSettings();
+    const allowAuthRouteOverride = isSocketAuthRouteOverrideEnabled();
+    assertReservedSocketRouteAvailable(router, 'GET', `${settings.path}/:appKey`);
+    assertReservedSocketRouteAvailable(router, 'POST', '/broadcasting/auth', {
+        allowOverride: true,
+    });
+    assertReservedSocketRouteAvailable(router, 'POST', '/apps/:appId/events');
     Router.get(router, `${settings.path}/:appKey`, respondUpgradeRequired);
-    Router.post(router, '/broadcasting/auth', authenticateSubscription);
+    if (allowAuthRouteOverride) {
+        if (!routeExists(router, 'POST', '/broadcasting/auth')) {
+            Logger.warn('SOCKET_ALLOW_AUTH_ROUTE_OVERRIDE=true but POST /broadcasting/auth is not registered by the application.');
+        }
+    }
+    else {
+        Router.post(router, '/broadcasting/auth', authenticateSubscription, {
+            middleware: resolveSocketAuthMiddleware(),
+            meta: {
+                summary: 'Socket broadcast authorization',
+                tags: ['Sockets'],
+                responseStatus: 200,
+            },
+        });
+    }
     Router.post(router, '/apps/:appId/events', publishEvent);
 };
 const socketRouteRegistrar = Object.freeze({

package/dist/register.js

@@ -1,4 +1,12 @@
 import { socketRouteRegistrar, socketRuntime } from './index.js';
+const registerViaGlobalFallback = () => {
+    const globalRegistry = globalThis;
+    globalRegistry.__zintrustSocketRuntimeRegistry = {
+        ...globalRegistry.__zintrustSocketRuntimeRegistry,
+        runtime: socketRuntime,
+        routeRegistrar: socketRouteRegistrar,
+    };
+};
 const importCore = async () => {
     try {
         return (await import('@zintrust/core'));
@@ -8,7 +16,10 @@ const importCore = async () => {
     }
 };
 const core = await importCore();
-if (core.SocketRuntimeRegistry !== undefined) {
+if (core.SocketRuntimeRegistry === undefined) {
+    registerViaGlobalFallback();
+}
+else {
     core.SocketRuntimeRegistry.registerRuntime(socketRuntime);
     core.SocketRuntimeRegistry.registerRoutes(socketRouteRegistrar);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/socket",
-  "version": "0.4.58",
+  "version": "0.4.59",
   "description": "Unified socket runtime for ZinTrust.",
   "private": false,
   "type": "module",
@@ -23,7 +23,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.58"
+    "@zintrust/core": "^0.4.59"
   },
   "publishConfig": {
     "access": "public"