@holo-js/broadcast 0.1.8 → 0.2.0

package/dist/auth.d.ts

@@ -13,6 +13,7 @@ declare function matchPattern(pattern: string, channel: string): Readonly<Record
 declare function resolveChannelMatch(channel: string, definitions: LoadedChannelDefinitions): MatchedChannelDefinition | null;
 declare function resolveAuthDefinitions(override?: BroadcastChannelAuthRuntimeBindings): Promise<LoadedChannelDefinitions>;
 declare function authorizeBroadcastChannel(input: BroadcastChannelAuthRequest, channelAuth?: BroadcastChannelAuthRuntimeBindings): Promise<BroadcastChannelAuthResult>;
+declare function resolveBroadcastChannelGuard(input: Pick<BroadcastChannelAuthRequest, 'channel' | 'socketId'>, channelAuth?: BroadcastChannelAuthRuntimeBindings): Promise<string | undefined>;
 declare function resolveBroadcastWhisperSchema(channel: string, event: string, channelAuth?: BroadcastChannelAuthRuntimeBindings): Promise<{
     readonly channel: string;
     readonly event: string;
@@ -32,4 +33,4 @@ declare const broadcastAuthInternals: {
     reset(): void;
 };
 
-export { authorizeBroadcastChannel, broadcastAuthInternals, parseBroadcastAuthEndpointPayload, renderBroadcastAuthResponse, resolveBroadcastWhisperSchema, validateBroadcastWhisperPayload };
+export { authorizeBroadcastChannel, broadcastAuthInternals, parseBroadcastAuthEndpointPayload, renderBroadcastAuthResponse, resolveBroadcastChannelGuard, resolveBroadcastWhisperSchema, validateBroadcastWhisperPayload };

package/dist/auth.mjs

@@ -3,16 +3,18 @@ import {
   broadcastAuthInternals,
   parseBroadcastAuthEndpointPayload,
   renderBroadcastAuthResponse,
+  resolveBroadcastChannelGuard,
   resolveBroadcastWhisperSchema,
   validateBroadcastWhisperPayload
-} from "./chunk-I3KE6HDH.mjs";
-import "./chunk-QYXS4X72.mjs";
-import "./chunk-DHKMBH25.mjs";
+} from "./chunk-U5JDBKXC.mjs";
+import "./chunk-TTKGDABI.mjs";
+import "./chunk-HE6HN7ID.mjs";
 export {
   authorizeBroadcastChannel,
   broadcastAuthInternals,
   parseBroadcastAuthEndpointPayload,
   renderBroadcastAuthResponse,
+  resolveBroadcastChannelGuard,
   resolveBroadcastWhisperSchema,
   validateBroadcastWhisperPayload
 };

package/dist/{chunk-DHKMBH25.mjs → chunk-HE6HN7ID.mjs}

@@ -1,12 +1,52 @@
+// src/json.ts
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function isObjectRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeJsonValue(value, path, formatError, options = {}) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(formatError(path));
+    }
+    return value;
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`, formatError, options)));
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(formatError(path));
+  }
+  return Object.freeze(Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => {
+      options.validateKey?.(key, path);
+      return [key, normalizeJsonValue(entry, `${path}.${key}`, formatError, options)];
+    })
+  ));
+}
+function parseJsonObject(value, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error(`[@holo-js/broadcast] ${label} must be valid JSON.`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`[@holo-js/broadcast] ${label} must be a JSON object.`);
+  }
+  return parsed;
+}
+
 // src/contracts.ts
 var HOLO_BROADCAST_DEFINITION_MARKER = /* @__PURE__ */ Symbol.for("holo-js.broadcast.definition");
 var HOLO_CHANNEL_DEFINITION_MARKER = /* @__PURE__ */ Symbol.for("holo-js.broadcast.channel");
 function isReadonlyArray(value) {
   return Array.isArray(value);
 }
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
-}
 function normalizeOptionalString(value, label) {
   if (typeof value === "undefined") {
     return void 0;
@@ -32,37 +72,23 @@ function normalizeDelayValue(value) {
   }
   return value;
 }
-function normalizeJsonValue(value, path) {
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) {
-      throw new Error(`[Holo Broadcast] ${path} must be JSON-serializable.`);
-    }
-    return value;
-  }
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`)));
-  }
-  if (isPlainObject(value)) {
-    return Object.freeze(Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => {
-        if (!key.trim()) {
-          throw new Error(`[Holo Broadcast] ${path} must not include empty payload keys.`);
-        }
-        return [key, normalizeJsonValue(entry, `${path}.${key}`)];
-      })
-    ));
-  }
-  throw new Error(`[Holo Broadcast] ${path} must be JSON-serializable.`);
-}
 function normalizePayload(payload) {
   const resolved = typeof payload === "function" ? payload() : payload;
   if (!isPlainObject(resolved)) {
     throw new Error("[Holo Broadcast] Broadcast payload must be a plain object.");
   }
-  return normalizeJsonValue(resolved, "Broadcast payload");
+  return normalizeJsonValue(
+    resolved,
+    "Broadcast payload",
+    (path) => `[Holo Broadcast] ${path} must be JSON-serializable.`,
+    {
+      validateKey(key, path) {
+        if (!key.trim()) {
+          throw new Error(`[Holo Broadcast] ${path} must not include empty payload keys.`);
+        }
+      }
+    }
+  );
 }
 function normalizeQueueOptions(queue) {
   if (typeof queue === "boolean" || typeof queue === "undefined") {
@@ -237,6 +263,7 @@ function normalizeChannelDefinition(pattern, definition) {
   return {
     pattern: normalizeChannelPattern(pattern, "Channel pattern"),
     type: definition.type,
+    ...typeof definition.guard === "undefined" ? {} : { guard: definition.guard },
     authorize: definition.authorize,
     whispers: normalizeWhisperDefinitions(definition.whispers)
   };
@@ -280,6 +307,10 @@ var broadcastInternals = {
 };
 
 export {
+  isPlainObject,
+  isObjectRecord,
+  normalizeJsonValue,
+  parseJsonObject,
   extractChannelPatternParamNames,
   normalizeChannelPattern,
   formatChannelPattern,

package/dist/chunk-MEYUTXNP.mjs

@@ -0,0 +1,44 @@
+// src/client-config.ts
+function resolveDefaultHoloConnection(config) {
+  const connection = config.connections[config.default];
+  if (!connection || connection.driver !== "holo" || !("key" in connection) || !("options" in connection)) {
+    throw new Error('[@holo-js/broadcast] Broadcast client config requires the default broadcast connection to use the "holo" driver.');
+  }
+  return connection;
+}
+function resolveAuthEndpointPath(authEndpoint) {
+  const trimmed = authEndpoint.trim();
+  if (trimmed.length === 0) {
+    return trimmed;
+  }
+  try {
+    return new URL(trimmed).pathname;
+  } catch {
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  }
+}
+function resolveBroadcastClientConfig(config) {
+  const connection = resolveDefaultHoloConnection(config);
+  const publicHost = config.worker.publicHost ?? connection.options.host;
+  const publicPort = config.worker.publicHost ? config.worker.publicPort ?? connection.options.port : connection.options.port;
+  return Object.freeze({
+    key: connection.key,
+    host: publicHost,
+    port: publicPort,
+    path: config.worker.path,
+    scheme: config.worker.publicScheme,
+    ...typeof connection.clientOptions.authEndpoint === "string" ? { authEndpoint: resolveAuthEndpointPath(connection.clientOptions.authEndpoint) } : {}
+  });
+}
+function renderBroadcastClientConfigResponse(config) {
+  return Response.json(resolveBroadcastClientConfig(config), {
+    headers: {
+      "cache-control": "no-store"
+    }
+  });
+}
+
+export {
+  resolveBroadcastClientConfig,
+  renderBroadcastClientConfigResponse
+};

package/dist/{chunk-QYXS4X72.mjs → chunk-TTKGDABI.mjs}

@@ -1,8 +1,10 @@
 import {
   formatChannelPattern,
   isBroadcastDefinition,
-  normalizeBroadcastDefinition
-} from "./chunk-DHKMBH25.mjs";
+  isPlainObject,
+  normalizeBroadcastDefinition,
+  normalizeJsonValue
+} from "./chunk-HE6HN7ID.mjs";
 
 // src/runtime.ts
 import { randomUUID } from "crypto";
@@ -110,34 +112,11 @@ function normalizeDelayValue(value, label) {
   }
   return value;
 }
-function isRecord(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
-}
-function normalizeJsonValue(value, path) {
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) {
-      throw new Error(`[@holo-js/broadcast] ${path} must be JSON-serializable.`);
-    }
-    return value;
-  }
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`)));
-  }
-  if (!isRecord(value)) {
-    throw new Error(`[@holo-js/broadcast] ${path} must be JSON-serializable.`);
-  }
-  return Object.freeze(Object.fromEntries(
-    Object.entries(value).map(([key, entry]) => [key, normalizeJsonValue(entry, `${path}.${key}`)])
-  ));
-}
 function normalizePayload(payload) {
-  if (!isRecord(payload)) {
+  if (!isPlainObject(payload)) {
     throw new Error("[@holo-js/broadcast] Broadcast payload must be a plain object.");
   }
-  return normalizeJsonValue(payload, "Broadcast payload");
+  return normalizeJsonValue(payload, "Broadcast payload", (path) => `[@holo-js/broadcast] ${path} must be JSON-serializable.`);
 }
 function normalizeRawChannels(channels) {
   if (!Array.isArray(channels) || channels.length === 0) {
@@ -237,7 +216,7 @@ function createBaseResult(context, channels) {
 }
 function normalizeDriverResult(result, context, channels) {
   const publishedChannels = Array.isArray(result.publishedChannels) ? Object.freeze(result.publishedChannels.map((channel) => normalizeRequiredString(channel, "Published channel"))) : Object.freeze([...channels]);
-  const provider = result.provider && isRecord(result.provider) ? Object.freeze({ ...result.provider }) : void 0;
+  const provider = result.provider && isPlainObject(result.provider) ? Object.freeze({ ...result.provider }) : void 0;
   return Object.freeze({
     connection: normalizeOptionalString(result.connection, "Broadcast result connection") ?? context.connection,
     driver: normalizeOptionalString(result.driver, "Broadcast result driver") ?? context.driver,
@@ -477,12 +456,6 @@ function broadcast(definition) {
   return new PendingDispatch(async (options) => {
     const resolvedDefinition = resolveBroadcastDefinition(definition);
     const raw = createRawInputFromDefinition(resolvedDefinition, options.broadcaster);
-    const input = Object.freeze({
-      broadcast: resolvedDefinition,
-      raw,
-      options
-    });
-    void input;
     return await executeResolvedRawBroadcast(raw, resolvedDefinition, options);
   });
 }

package/dist/{chunk-I3KE6HDH.mjs → chunk-U5JDBKXC.mjs}

@@ -1,11 +1,14 @@
 import {
   getBroadcastRuntimeBindings
-} from "./chunk-QYXS4X72.mjs";
+} from "./chunk-TTKGDABI.mjs";
 import {
-  isChannelDefinition
-} from "./chunk-DHKMBH25.mjs";
+  isChannelDefinition,
+  isPlainObject,
+  normalizeJsonValue
+} from "./chunk-HE6HN7ID.mjs";
 
 // src/auth.ts
+import { createHmac } from "crypto";
 import { resolve } from "path";
 import { pathToFileURL } from "url";
 import { parse } from "@holo-js/validation";
@@ -14,9 +17,6 @@ function getRuntimeState() {
   runtime.__holoBroadcastAuthRuntime__ ??= {};
   return runtime.__holoBroadcastAuthRuntime__;
 }
-function isRecord(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
-}
 function normalizeRequiredString(value, label) {
   const normalized = value.trim();
   if (!normalized) {
@@ -40,31 +40,11 @@ function normalizeLookupChannel(channel, label) {
   }
   return normalized;
 }
-function normalizeJsonValue(value, path) {
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) {
-      throw new Error(`[@holo-js/broadcast] ${path} must be JSON-serializable.`);
-    }
-    return value;
-  }
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`)));
-  }
-  if (!isRecord(value)) {
-    throw new Error(`[@holo-js/broadcast] ${path} must be JSON-serializable.`);
-  }
-  return Object.freeze(Object.fromEntries(
-    Object.entries(value).map(([key, entry]) => [key, normalizeJsonValue(entry, `${path}.${key}`)])
-  ));
-}
 function normalizePresenceMember(value) {
-  if (!isRecord(value)) {
+  if (!isPlainObject(value)) {
     throw new Error("[@holo-js/broadcast] Presence authorization must return a serializable member object when allowed.");
   }
-  return normalizeJsonValue(value, "Broadcast presence member");
+  return normalizeJsonValue(value, "Broadcast presence member", (path) => `[@holo-js/broadcast] ${path} must be JSON-serializable.`);
 }
 function normalizeDefinitionMap(bindings) {
   const definitions = bindings.definitions;
@@ -102,6 +82,7 @@ function normalizeRegistryEntry(entry) {
     type: entry.type,
     params: Object.freeze([...entry.params]),
     whispers: Object.freeze([...entry.whispers]),
+    ...typeof entry.guard === "string" ? { guard: normalizeRequiredString(entry.guard, "Broadcast channel guard") } : {},
     ...typeof entry.exportName === "string" ? { exportName: normalizeRequiredString(entry.exportName, "Broadcast channel exportName") } : {}
   });
 }
@@ -113,7 +94,7 @@ async function importChannelDefinition(entry, bindings) {
   const importPath = resolve(registry.projectRoot, entry.sourcePath);
   const importer = bindings.importModule ?? (async (absolutePath) => await import(pathToFileURL(absolutePath).href));
   const moduleValue = await importer(importPath);
-  if (!isRecord(moduleValue)) {
+  if (!isPlainObject(moduleValue)) {
     throw new Error(`[@holo-js/broadcast] Broadcast channel module "${entry.sourcePath}" must export an object module namespace.`);
   }
   const exportName = entry.exportName ?? "default";
@@ -225,18 +206,26 @@ async function resolveAuthDefinitions(override) {
   }
   return await loadChannelDefinitions(bindings);
 }
-async function authorizeBroadcastChannel(input, channelAuth) {
-  const channel = normalizeRequiredString(input.channel, "Broadcast auth channel");
+async function resolveBroadcastChannelMatch(channel, channelAuth) {
   const definitions = await resolveAuthDefinitions(channelAuth);
-  const match = resolveChannelMatch(normalizeLookupChannel(channel, "Broadcast auth channel"), definitions);
-  if (!match) {
-    return Object.freeze({
-      ok: false,
+  return resolveChannelMatch(normalizeLookupChannel(channel, "Broadcast auth channel"), definitions);
+}
+async function resolveChannelGuard(channel, socketId, match) {
+  if (typeof match.definition.guard === "undefined") {
+    return void 0;
+  }
+  if (typeof match.definition.guard === "function") {
+    const context = {
       channel,
-      code: "not-found"
-    });
+      ...typeof socketId === "undefined" ? {} : { socketId },
+      params: match.params
+    };
+    return await match.definition.guard(context);
   }
-  const decision = await match.definition.authorize(input.user, match.params);
+  return match.definition.guard;
+}
+async function authorizeMatchedBroadcastChannel(channel, user, match) {
+  const decision = await match.definition.authorize(user, match.params);
   if (match.definition.type === "private") {
     if (decision !== true) {
       return Object.freeze({
@@ -271,6 +260,26 @@ async function authorizeBroadcastChannel(input, channelAuth) {
     whispers: Object.freeze(Object.keys(match.definition.whispers))
   });
 }
+async function authorizeBroadcastChannel(input, channelAuth) {
+  const channel = normalizeRequiredString(input.channel, "Broadcast auth channel");
+  const match = await resolveBroadcastChannelMatch(channel, channelAuth);
+  if (!match) {
+    return Object.freeze({
+      ok: false,
+      channel,
+      code: "not-found"
+    });
+  }
+  return await authorizeMatchedBroadcastChannel(channel, input.user, match);
+}
+async function resolveBroadcastChannelGuard(input, channelAuth) {
+  const channel = normalizeRequiredString(input.channel, "Broadcast auth channel");
+  const match = await resolveBroadcastChannelMatch(channel, channelAuth);
+  if (!match) {
+    return void 0;
+  }
+  return await resolveChannelGuard(channel, input.socketId, match);
+}
 async function resolveBroadcastWhisperSchema(channel, event, channelAuth) {
   const normalizedChannel = normalizeRequiredString(channel, "Broadcast whisper channel");
   const normalizedEvent = normalizeRequiredString(event, "Broadcast whisper event");
@@ -338,6 +347,10 @@ function jsonResponse(body, status) {
     }
   });
 }
+function signBroadcastAuth(appSecret, socketId, channel, channelData) {
+  const value = channelData ? `${socketId}:${channel}:${channelData}` : `${socketId}:${channel}`;
+  return createHmac("sha256", appSecret).update(value).digest("hex");
+}
 async function renderBroadcastAuthResponse(request, options = {}) {
   let payload;
   try {
@@ -357,7 +370,21 @@ async function renderBroadcastAuthResponse(request, options = {}) {
       message
     }, 400);
   }
-  const user = typeof options.resolveUser === "function" ? await options.resolveUser(request) : options.user;
+  const channel = normalizeRequiredString(payload.channel, "Broadcast auth channel");
+  const match = await resolveBroadcastChannelMatch(channel, options.channelAuth);
+  if (!match) {
+    return jsonResponse({
+      ok: false,
+      error: "not-found",
+      message: `No channel authorization rule matches "${channel}".`
+    }, 404);
+  }
+  const guard = await resolveChannelGuard(channel, payload.socketId, match);
+  const user = typeof options.resolveUser === "function" ? await options.resolveUser(request, {
+    channel,
+    ...typeof payload.socketId === "undefined" ? {} : { socketId: payload.socketId },
+    ...typeof guard === "undefined" ? {} : { guard }
+  }) : options.user;
   if (typeof user === "undefined" || user === null) {
     return jsonResponse({
       ok: false,
@@ -365,31 +392,29 @@ async function renderBroadcastAuthResponse(request, options = {}) {
       message: "Broadcast channel authorization requires an authenticated user."
     }, 401);
   }
-  const result = await authorizeBroadcastChannel({
-    channel: payload.channel,
-    socketId: payload.socketId,
-    user
-  }, options.channelAuth);
+  const result = await authorizeMatchedBroadcastChannel(channel, user, match);
   if (!result.ok) {
-    if (result.code === "not-found") {
-      return jsonResponse({
-        ok: false,
-        error: "not-found",
-        message: `No channel authorization rule matches "${result.channel}".`
-      }, 404);
-    }
     return jsonResponse({
       ok: false,
       error: "unauthorized",
       message: `Channel authorization denied for "${result.channel}".`
     }, 403);
   }
+  const channelData = JSON.stringify({
+    whispers: result.whispers,
+    ...result.type === "presence" ? { member: result.member } : {}
+  });
+  const signed = options.appKey && options.appSecret && payload.socketId ? {
+    auth: `${options.appKey}:${signBroadcastAuth(options.appSecret, payload.socketId, channel, channelData)}`,
+    channel_data: channelData
+  } : {};
   return jsonResponse({
     ok: true,
     channel: result.channel,
     type: result.type,
     params: result.params,
     whispers: result.whispers,
+    ...signed,
     ...result.type === "presence" ? { member: result.member } : {}
   }, 200);
 }
@@ -410,6 +435,7 @@ var broadcastAuthInternals = {
 
 export {
   authorizeBroadcastChannel,
+  resolveBroadcastChannelGuard,
   resolveBroadcastWhisperSchema,
   validateBroadcastWhisperPayload,
   parseBroadcastAuthEndpointPayload,

package/dist/client-config.d.ts

@@ -0,0 +1,14 @@
+import { LoadedHoloConfig } from '@holo-js/config';
+
+type BroadcastClientConfig = {
+    readonly key: string;
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    readonly scheme: 'http' | 'https';
+    readonly authEndpoint?: string;
+};
+declare function resolveBroadcastClientConfig(config: LoadedHoloConfig['broadcast']): BroadcastClientConfig;
+declare function renderBroadcastClientConfigResponse(config: LoadedHoloConfig['broadcast']): Response;
+
+export { type BroadcastClientConfig, renderBroadcastClientConfigResponse, resolveBroadcastClientConfig };

package/dist/client-config.mjs

@@ -0,0 +1,8 @@
+import {
+  renderBroadcastClientConfigResponse,
+  resolveBroadcastClientConfig
+} from "./chunk-MEYUTXNP.mjs";
+export {
+  renderBroadcastClientConfigResponse,
+  resolveBroadcastClientConfig
+};

package/dist/contracts.d.ts

@@ -1,6 +1,11 @@
 import { NormalizedHoloBroadcastConfig } from '@holo-js/config';
 import { ValidationSchema, InferSchemaData } from '@holo-js/validation';
 
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function normalizeJsonValue(value: unknown, path: string, formatError: (path: string) => string, options?: {
+    readonly validateKey?: (key: string, path: string) => void;
+}): BroadcastJsonValue;
+
 type BroadcastJsonPrimitive = string | number | boolean | null;
 type BroadcastJsonValue = BroadcastJsonPrimitive | readonly BroadcastJsonValue[] | BroadcastJsonObject;
 type BroadcastJsonObject = {
@@ -44,21 +49,40 @@ interface BroadcastDefinition<TName extends string = string, TPayload extends Br
     readonly queue: NormalizedBroadcastQueueOptions;
     readonly delay?: BroadcastDelayValue;
 }
-type ExportedBroadcastDefinition<TValue> = Extract<TValue, BroadcastDefinition> extends never ? BroadcastDefinition : Extract<TValue, BroadcastDefinition>;
+type ExportedBroadcastDefinition<TValue> = TValue extends (...args: infer _TArgs) => infer TResult ? ExportedBroadcastDefinition<TResult> : Extract<TValue, BroadcastDefinition> extends never ? BroadcastDefinition : Extract<TValue, BroadcastDefinition>;
 type BroadcastAuthorizeResult<TType extends BroadcastChannelType, TPresenceMember extends BroadcastJsonObject> = TType extends 'presence' ? false | TPresenceMember : boolean;
 type BroadcastWhisperSchema = ValidationSchema;
 type BroadcastWhisperDefinitions = Readonly<Record<string, BroadcastWhisperSchema>>;
 type InferBroadcastWhisperPayload<TSchema> = TSchema extends {
     readonly $data?: infer TData;
 } ? TData : never;
+declare global {
+    namespace HoloAuth {
+        interface TypeRegistry {
+            readonly __holoBroadcastAuthRegistry?: never;
+        }
+    }
+}
+type RegisteredAuthGuards = HoloAuth.TypeRegistry extends {
+    readonly guards: infer TGuards;
+} ? TGuards : Readonly<Record<string, 'session'>>;
+type BroadcastAuthGuardName = Extract<keyof RegisteredAuthGuards, string>;
+interface ChannelGuardResolverContext<TPattern extends string = string> {
+    readonly channel: string;
+    readonly socketId?: string;
+    readonly params: ChannelPatternParams<TPattern>;
+}
+type ChannelGuardResolver<TPattern extends string = string> = BroadcastAuthGuardName | ((context: ChannelGuardResolverContext<TPattern>) => BroadcastAuthGuardName | Promise<BroadcastAuthGuardName>);
 interface ChannelDefinitionInput<TPattern extends string = string, TType extends Extract<BroadcastChannelType, 'private' | 'presence'> = Extract<BroadcastChannelType, 'private' | 'presence'>, TUser = unknown, TPresenceMember extends BroadcastJsonObject = BroadcastJsonObject, TWhispers extends BroadcastWhisperDefinitions = BroadcastWhisperDefinitions> {
     readonly type: TType;
+    readonly guard?: ChannelGuardResolver<TPattern>;
     readonly authorize: (user: TUser, params: ChannelPatternParams<TPattern>) => BroadcastAuthorizeResult<TType, TPresenceMember> | Promise<BroadcastAuthorizeResult<TType, TPresenceMember>>;
     readonly whispers?: TWhispers;
 }
 interface ChannelDefinition<TPattern extends string = string, TType extends Extract<BroadcastChannelType, 'private' | 'presence'> = Extract<BroadcastChannelType, 'private' | 'presence'>, TUser = unknown, TPresenceMember extends BroadcastJsonObject = BroadcastJsonObject, TWhispers extends BroadcastWhisperDefinitions = BroadcastWhisperDefinitions> {
     readonly pattern: TPattern;
     readonly type: TType;
+    readonly guard?: ChannelGuardResolver<TPattern>;
     readonly authorize: ChannelDefinitionInput<TPattern, TType, TUser, TPresenceMember, TWhispers>['authorize'];
     readonly whispers: Readonly<TWhispers>;
 }
@@ -102,6 +126,34 @@ interface BroadcastRuntimeBindings {
     publish?(input: ResolvedRawBroadcastSendInput, context: BroadcastDriverExecutionContext): BroadcastSendResult | Promise<BroadcastSendResult>;
     readonly channelAuth?: BroadcastChannelAuthRuntimeBindings;
 }
+interface BroadcastRealtimeExecutionContext {
+    readonly headers: Headers;
+    readonly socketId: string;
+    readonly appId: string;
+    readonly connection: string;
+}
+interface BroadcastRealtimeExecutionResult<TResult = unknown> {
+    readonly name: string;
+    readonly data: TResult;
+    readonly dependencies: readonly string[];
+}
+interface BroadcastRealtimeSubscriptionSnapshot<TResult = unknown> extends BroadcastRealtimeExecutionResult<TResult> {
+    readonly version: number;
+}
+interface BroadcastRealtimeSubscription<TResult = unknown> {
+    readonly id: string;
+    readonly current: BroadcastRealtimeSubscriptionSnapshot<TResult>;
+    unsubscribe(): void;
+}
+interface BroadcastRealtimeRuntimeBindings {
+    query(name: string, args: Record<string, unknown>, context: BroadcastRealtimeExecutionContext): Promise<BroadcastRealtimeExecutionResult>;
+    mutate(name: string, args: Record<string, unknown>, context: BroadcastRealtimeExecutionContext): Promise<BroadcastRealtimeExecutionResult>;
+    subscribe(name: string, args: Record<string, unknown>, options: {
+        readonly context: BroadcastRealtimeExecutionContext;
+        readonly onData: (snapshot: BroadcastRealtimeSubscriptionSnapshot) => void | Promise<void>;
+        readonly onError: (error: unknown) => void | Promise<void>;
+    }): Promise<BroadcastRealtimeSubscription>;
+}
 interface BroadcastRuntimeFacade {
     broadcast(definition: BroadcastDefinition | BroadcastDefinitionInput): PendingBroadcastDispatch<BroadcastSendResult>;
     broadcastRaw(input: RawBroadcastSendInput): PendingBroadcastDispatch<BroadcastSendResult>;
@@ -150,6 +202,7 @@ interface GeneratedChannelAuthRegistryEntry {
     readonly sourcePath: string;
     readonly pattern: string;
     readonly exportName?: string;
+    readonly guard?: string;
     readonly type: 'private' | 'presence';
     readonly params: readonly string[];
     readonly whispers: readonly string[];
@@ -164,6 +217,7 @@ interface BroadcastChannelAuthRuntimeBindings {
         readonly headers: Headers;
         readonly socketId: string;
         readonly channel: string;
+        readonly guard?: string;
         readonly appId: string;
         readonly connection: string;
     }) => unknown | Promise<unknown>;
@@ -199,6 +253,8 @@ interface BroadcastAuthEndpointSuccessBody {
     readonly type: 'private' | 'presence';
     readonly params: Readonly<Record<string, string>>;
     readonly whispers: readonly string[];
+    readonly auth?: string;
+    readonly channel_data?: string;
     readonly member?: Readonly<BroadcastJsonObject>;
 }
 interface BroadcastAuthEndpointErrorBody {
@@ -208,8 +264,14 @@ interface BroadcastAuthEndpointErrorBody {
 }
 type BroadcastAuthEndpointBody = BroadcastAuthEndpointSuccessBody | BroadcastAuthEndpointErrorBody;
 interface BroadcastAuthEndpointOptions {
+    readonly appKey?: string;
+    readonly appSecret?: string;
     readonly user?: unknown;
-    readonly resolveUser?: (request: Request) => unknown | Promise<unknown>;
+    readonly resolveUser?: (request: Request, context: {
+        readonly channel: string;
+        readonly socketId?: string;
+        readonly guard?: string;
+    }) => unknown | Promise<unknown>;
     readonly channelAuth?: BroadcastChannelAuthRuntimeBindings;
 }
 interface BroadcastWhisperValidationResult<TPayload extends BroadcastJsonObject = BroadcastJsonObject> {
@@ -246,9 +308,7 @@ interface GeneratedBroadcastManifest {
     readonly channels: readonly GeneratedBroadcastManifestChannel[];
 }
 declare function isReadonlyArray(value: unknown): value is readonly unknown[];
-declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 declare function normalizeDelayValue(value: BroadcastDelayValue | undefined): BroadcastDelayValue | undefined;
-declare function normalizeJsonValue(value: unknown, path: string): BroadcastJsonValue;
 declare function normalizeQueueOptions(queue: boolean | BroadcastQueueOptions | undefined): NormalizedBroadcastQueueOptions;
 declare function extractChannelPatternParamNames(pattern: string): readonly string[];
 declare function normalizeChannelPattern(pattern: string, label?: string): string;
@@ -284,4 +344,4 @@ declare const broadcastInternals: {
     normalizeWhisperDefinitions: typeof normalizeWhisperDefinitions;
 };
 
-export { type BroadcastAuthEndpointBody, type BroadcastAuthEndpointErrorBody, type BroadcastAuthEndpointOptions, type BroadcastAuthEndpointPayload, type BroadcastAuthEndpointSuccessBody, type BroadcastAuthorizeResult, type BroadcastChannelAuthFailure, type BroadcastChannelAuthRequest, type BroadcastChannelAuthResult, type BroadcastChannelAuthRuntimeBindings, type BroadcastChannelAuthSuccess, type BroadcastChannelTarget, type BroadcastChannelType, type BroadcastChannelsFor, type BroadcastDefinition, type BroadcastDefinitionInput, type BroadcastDelayValue, type BroadcastDispatchOptions, type BroadcastDriver, type BroadcastDriverExecutionContext, type BroadcastDriverName, type BroadcastJsonObject, type BroadcastJsonPrimitive, type BroadcastJsonValue, type BroadcastPayloadFor, type BroadcastQueueOptions, type BroadcastRuntimeBindings, type BroadcastRuntimeFacade, type BroadcastSendInput, type BroadcastSendResult, type BroadcastTargetParamInput, type BroadcastWhisperDefinitions, type BroadcastWhisperSchema, type BroadcastWhisperValidationResult, type BuiltInBroadcastDriverRegistry, type ChannelDefinition, type ChannelDefinitionFor, type ChannelDefinitionInput, type ChannelPatternParams, type ChannelPresenceMemberFor, type ChannelWhisperPayloadFor, type ExportedBroadcastDefinition, type ExportedChannelDefinition, type GeneratedBroadcastManifest, type GeneratedBroadcastManifestChannel, type GeneratedBroadcastManifestEvent, type GeneratedChannelAuthRegistryEntry, type HoloBroadcastDriverRegistry, type HoloBroadcastRegistry, type HoloChannelRegistry, type InferBroadcastWhisperPayload, type InferChannelPresenceMember, type InferChannelWhisperPayload, type InferSchemaOutput, type NormalizedBroadcastQueueOptions, type PendingBroadcastDispatch, type RawBroadcastSendInput, type RegisterBroadcastDriverOptions, type RegisteredBroadcastDriver, type ResolvedRawBroadcastSendInput, broadcastInternals, channel, defineBroadcast, defineChannel, extractChannelPatternParamNames, formatChannelPattern, isBroadcastChannelTarget, isBroadcastDefinition, isChannelDefinition, normalizeBroadcastDefinition, normalizeChannelDefinition, normalizeChannelPattern, presenceChannel, privateChannel };
+export { type BroadcastAuthEndpointBody, type BroadcastAuthEndpointErrorBody, type BroadcastAuthEndpointOptions, type BroadcastAuthEndpointPayload, type BroadcastAuthEndpointSuccessBody, type BroadcastAuthGuardName, type BroadcastAuthorizeResult, type BroadcastChannelAuthFailure, type BroadcastChannelAuthRequest, type BroadcastChannelAuthResult, type BroadcastChannelAuthRuntimeBindings, type BroadcastChannelAuthSuccess, type BroadcastChannelTarget, type BroadcastChannelType, type BroadcastChannelsFor, type BroadcastDefinition, type BroadcastDefinitionInput, type BroadcastDelayValue, type BroadcastDispatchOptions, type BroadcastDriver, type BroadcastDriverExecutionContext, type BroadcastDriverName, type BroadcastJsonObject, type BroadcastJsonPrimitive, type BroadcastJsonValue, type BroadcastPayloadFor, type BroadcastQueueOptions, type BroadcastRealtimeExecutionContext, type BroadcastRealtimeExecutionResult, type BroadcastRealtimeRuntimeBindings, type BroadcastRealtimeSubscription, type BroadcastRealtimeSubscriptionSnapshot, type BroadcastRuntimeBindings, type BroadcastRuntimeFacade, type BroadcastSendInput, type BroadcastSendResult, type BroadcastTargetParamInput, type BroadcastWhisperDefinitions, type BroadcastWhisperSchema, type BroadcastWhisperValidationResult, type BuiltInBroadcastDriverRegistry, type ChannelDefinition, type ChannelDefinitionFor, type ChannelDefinitionInput, type ChannelGuardResolver, type ChannelGuardResolverContext, type ChannelPatternParams, type ChannelPresenceMemberFor, type ChannelWhisperPayloadFor, type ExportedBroadcastDefinition, type ExportedChannelDefinition, type GeneratedBroadcastManifest, type GeneratedBroadcastManifestChannel, type GeneratedBroadcastManifestEvent, type GeneratedChannelAuthRegistryEntry, type HoloBroadcastDriverRegistry, type HoloBroadcastRegistry, type HoloChannelRegistry, type InferBroadcastWhisperPayload, type InferChannelPresenceMember, type InferChannelWhisperPayload, type InferSchemaOutput, type NormalizedBroadcastQueueOptions, type PendingBroadcastDispatch, type RawBroadcastSendInput, type RegisterBroadcastDriverOptions, type RegisteredBroadcastDriver, type ResolvedRawBroadcastSendInput, broadcastInternals, channel, defineBroadcast, defineChannel, extractChannelPatternParamNames, formatChannelPattern, isBroadcastChannelTarget, isBroadcastDefinition, isChannelDefinition, normalizeBroadcastDefinition, normalizeChannelDefinition, normalizeChannelPattern, presenceChannel, privateChannel };

package/dist/contracts.mjs

@@ -13,7 +13,7 @@ import {
   normalizeChannelPattern,
   presenceChannel,
   privateChannel
-} from "./chunk-DHKMBH25.mjs";
+} from "./chunk-HE6HN7ID.mjs";
 export {
   broadcastInternals,
   channel,

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { BroadcastChannelAuthRuntimeBindings, BroadcastRuntimeBindings, BroadcastDriver, RegisteredBroadcastDriver, RegisterBroadcastDriverOptions, channel, defineBroadcast, defineChannel, presenceChannel, privateChannel } from './contracts.js';
-export { BroadcastAuthEndpointBody, BroadcastAuthEndpointErrorBody, BroadcastAuthEndpointOptions, BroadcastAuthEndpointPayload, BroadcastAuthEndpointSuccessBody, BroadcastAuthorizeResult, BroadcastChannelAuthFailure, BroadcastChannelAuthRequest, BroadcastChannelAuthResult, BroadcastChannelAuthSuccess, BroadcastChannelTarget, BroadcastChannelType, BroadcastChannelsFor, BroadcastDefinition, BroadcastDefinitionInput, BroadcastDelayValue, BroadcastDispatchOptions, BroadcastDriverExecutionContext, BroadcastDriverName, BroadcastJsonObject, BroadcastJsonPrimitive, BroadcastJsonValue, BroadcastPayloadFor, BroadcastQueueOptions, BroadcastRuntimeFacade, BroadcastSendInput, BroadcastSendResult, BroadcastTargetParamInput, BroadcastWhisperDefinitions, BroadcastWhisperSchema, BroadcastWhisperValidationResult, BuiltInBroadcastDriverRegistry, ChannelDefinition, ChannelDefinitionFor, ChannelDefinitionInput, ChannelPatternParams, ChannelPresenceMemberFor, ChannelWhisperPayloadFor, ExportedBroadcastDefinition, ExportedChannelDefinition, GeneratedBroadcastManifest, GeneratedBroadcastManifestChannel, GeneratedBroadcastManifestEvent, GeneratedChannelAuthRegistryEntry, HoloBroadcastDriverRegistry, HoloBroadcastRegistry, HoloChannelRegistry, InferBroadcastWhisperPayload, InferChannelPresenceMember, InferChannelWhisperPayload, InferSchemaOutput, PendingBroadcastDispatch, RawBroadcastSendInput, ResolvedRawBroadcastSendInput, broadcastInternals, isBroadcastDefinition, isChannelDefinition } from './contracts.js';
-import { authorizeBroadcastChannel, parseBroadcastAuthEndpointPayload, renderBroadcastAuthResponse, resolveBroadcastWhisperSchema, validateBroadcastWhisperPayload } from './auth.js';
+import { BroadcastChannelAuthRuntimeBindings, BroadcastRealtimeRuntimeBindings, BroadcastRuntimeBindings, BroadcastDriver, RegisteredBroadcastDriver, RegisterBroadcastDriverOptions, channel, defineBroadcast, defineChannel, presenceChannel, privateChannel } from './contracts.js';
+export { BroadcastAuthEndpointBody, BroadcastAuthEndpointErrorBody, BroadcastAuthEndpointOptions, BroadcastAuthEndpointPayload, BroadcastAuthEndpointSuccessBody, BroadcastAuthGuardName, BroadcastAuthorizeResult, BroadcastChannelAuthFailure, BroadcastChannelAuthRequest, BroadcastChannelAuthResult, BroadcastChannelAuthSuccess, BroadcastChannelTarget, BroadcastChannelType, BroadcastChannelsFor, BroadcastDefinition, BroadcastDefinitionInput, BroadcastDelayValue, BroadcastDispatchOptions, BroadcastDriverExecutionContext, BroadcastDriverName, BroadcastJsonObject, BroadcastJsonPrimitive, BroadcastJsonValue, BroadcastPayloadFor, BroadcastQueueOptions, BroadcastRealtimeExecutionContext, BroadcastRealtimeExecutionResult, BroadcastRealtimeSubscription, BroadcastRealtimeSubscriptionSnapshot, BroadcastRuntimeFacade, BroadcastSendInput, BroadcastSendResult, BroadcastTargetParamInput, BroadcastWhisperDefinitions, BroadcastWhisperSchema, BroadcastWhisperValidationResult, BuiltInBroadcastDriverRegistry, ChannelDefinition, ChannelDefinitionFor, ChannelDefinitionInput, ChannelPatternParams, ChannelPresenceMemberFor, ChannelWhisperPayloadFor, ExportedBroadcastDefinition, ExportedChannelDefinition, GeneratedBroadcastManifest, GeneratedBroadcastManifestChannel, GeneratedBroadcastManifestEvent, GeneratedChannelAuthRegistryEntry, HoloBroadcastDriverRegistry, HoloBroadcastRegistry, HoloChannelRegistry, InferBroadcastWhisperPayload, InferChannelPresenceMember, InferChannelWhisperPayload, InferSchemaOutput, PendingBroadcastDispatch, RawBroadcastSendInput, ResolvedRawBroadcastSendInput, broadcastInternals, isBroadcastDefinition, isChannelDefinition } from './contracts.js';
+import { authorizeBroadcastChannel, parseBroadcastAuthEndpointPayload, renderBroadcastAuthResponse, resolveBroadcastChannelGuard, resolveBroadcastWhisperSchema, validateBroadcastWhisperPayload } from './auth.js';
 export { broadcastAuthInternals } from './auth.js';
+import { renderBroadcastClientConfigResponse, resolveBroadcastClientConfig } from './client-config.js';
+export { BroadcastClientConfig } from './client-config.js';
 import { NormalizedHoloBroadcastConfig, NormalizedHoloQueueConfig, NormalizedHoloRedisConfig } from '@holo-js/config';
 export { HoloBroadcastConfig, NormalizedHoloBroadcastConfig, defineBroadcastConfig } from '@holo-js/config';
 import { broadcast, broadcastRaw, configureBroadcastRuntime, getBroadcastRuntime, getBroadcastRuntimeBindings, resetBroadcastRuntime } from './runtime.js';
@@ -34,6 +36,7 @@ type PresenceMember = Readonly<Record<string, unknown>>;
 type WorkerRuntimeOptions = {
     readonly config: NormalizedHoloBroadcastConfig;
     readonly channelAuth?: BroadcastChannelAuthRuntimeBindings;
+    readonly realtime?: BroadcastRealtimeRuntimeBindings;
     readonly fetch?: typeof fetch;
     readonly now?: () => number;
     readonly scaling?: BroadcastWorkerScalingRuntime;
@@ -123,6 +126,7 @@ declare function createRedisScalingAdapter(connection: BroadcastRedisScalingConn
 declare function buildWorkerApps(config: NormalizedHoloBroadcastConfig): Readonly<Record<string, BroadcastWorkerApp>>;
 declare function createBroadcastWorkerRuntime(options: WorkerRuntimeOptions): BroadcastWorkerRuntime;
 declare function startBroadcastWorker(runtimeBindings: Pick<BroadcastRuntimeBindings, 'config' | 'channelAuth'> & {
+    readonly realtime?: BroadcastRealtimeRuntimeBindings;
     readonly queue?: NormalizedHoloQueueConfig;
     readonly redis?: NormalizedHoloRedisConfig;
     readonly nodeId?: string;
@@ -168,12 +172,15 @@ declare const broadcastPackage: Readonly<{
     parseBroadcastAuthEndpointPayload: typeof parseBroadcastAuthEndpointPayload;
     presenceChannel: typeof presenceChannel;
     privateChannel: typeof privateChannel;
+    renderBroadcastClientConfigResponse: typeof renderBroadcastClientConfigResponse;
     renderBroadcastAuthResponse: typeof renderBroadcastAuthResponse;
     resetBroadcastRuntime: typeof resetBroadcastRuntime;
+    resolveBroadcastClientConfig: typeof resolveBroadcastClientConfig;
+    resolveBroadcastChannelGuard: typeof resolveBroadcastChannelGuard;
     resolveBroadcastWhisperSchema: typeof resolveBroadcastWhisperSchema;
     startBroadcastWorker: typeof startBroadcastWorker;
     validateBroadcastWhisperPayload: typeof validateBroadcastWhisperPayload;
     createBroadcastWorkerRuntime: typeof createBroadcastWorkerRuntime;
 }>;
 
-export { BroadcastChannelAuthRuntimeBindings, BroadcastDriver, BroadcastRuntimeBindings, type BroadcastWorkerRuntime, type BroadcastWorkerStats, RegisterBroadcastDriverOptions, RegisteredBroadcastDriver, type StartedBroadcastWorker, authorizeBroadcastChannel, broadcast, broadcastRaw, broadcastRegistryInternals, channel, configureBroadcastRuntime, createBroadcastWorkerRuntime, broadcastPackage as default, defineBroadcast, defineChannel, getBroadcastRuntime, getBroadcastRuntimeBindings, getRegisteredBroadcastDriver, listRegisteredBroadcastDrivers, parseBroadcastAuthEndpointPayload, presenceChannel, privateChannel, registerBroadcastDriver, renderBroadcastAuthResponse, resetBroadcastDriverRegistry, resetBroadcastRuntime, resolveBroadcastWhisperSchema, startBroadcastWorker, validateBroadcastWhisperPayload, workerInternals };
+export { BroadcastChannelAuthRuntimeBindings, BroadcastDriver, BroadcastRealtimeRuntimeBindings, BroadcastRuntimeBindings, type BroadcastWorkerRuntime, type BroadcastWorkerStats, RegisterBroadcastDriverOptions, RegisteredBroadcastDriver, type StartedBroadcastWorker, authorizeBroadcastChannel, broadcast, broadcastRaw, broadcastRegistryInternals, channel, configureBroadcastRuntime, createBroadcastWorkerRuntime, broadcastPackage as default, defineBroadcast, defineChannel, getBroadcastRuntime, getBroadcastRuntimeBindings, getRegisteredBroadcastDriver, listRegisteredBroadcastDrivers, parseBroadcastAuthEndpointPayload, presenceChannel, privateChannel, registerBroadcastDriver, renderBroadcastAuthResponse, renderBroadcastClientConfigResponse, resetBroadcastDriverRegistry, resetBroadcastRuntime, resolveBroadcastChannelGuard, resolveBroadcastClientConfig, resolveBroadcastWhisperSchema, startBroadcastWorker, validateBroadcastWhisperPayload, workerInternals };

package/dist/index.mjs

@@ -3,9 +3,14 @@ import {
   broadcastAuthInternals,
   parseBroadcastAuthEndpointPayload,
   renderBroadcastAuthResponse,
+  resolveBroadcastChannelGuard,
   resolveBroadcastWhisperSchema,
   validateBroadcastWhisperPayload
-} from "./chunk-I3KE6HDH.mjs";
+} from "./chunk-U5JDBKXC.mjs";
+import {
+  renderBroadcastClientConfigResponse,
+  resolveBroadcastClientConfig
+} from "./chunk-MEYUTXNP.mjs";
 import {
   broadcast,
   broadcastRaw,
@@ -19,7 +24,7 @@ import {
   registerBroadcastDriver,
   resetBroadcastDriverRegistry,
   resetBroadcastRuntime
-} from "./chunk-QYXS4X72.mjs";
+} from "./chunk-TTKGDABI.mjs";
 import {
   broadcastInternals,
   channel,
@@ -27,9 +32,12 @@ import {
   defineChannel,
   isBroadcastDefinition,
   isChannelDefinition,
+  isObjectRecord,
+  isPlainObject,
+  parseJsonObject,
   presenceChannel,
   privateChannel
-} from "./chunk-DHKMBH25.mjs";
+} from "./chunk-HE6HN7ID.mjs";
 
 // src/worker.ts
 import { createHash, createHmac, randomInt, randomUUID, timingSafeEqual } from "crypto";
@@ -45,29 +53,46 @@ function normalizeRequiredString(value, label) {
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function parseJsonObject(value, label) {
-  let parsed;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw new Error(`[@holo-js/broadcast] ${label} must be valid JSON.`);
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`[@holo-js/broadcast] ${label} must be a JSON object.`);
-  }
-  return parsed;
-}
 function parseSocketMessage(rawMessage) {
   const message = parseJsonObject(rawMessage, "Websocket message");
   const event = normalizeRequiredString(String(message.event ?? ""), "Websocket event");
   const channel2 = typeof message.channel === "string" ? normalizeRequiredString(message.channel, "Websocket channel") : void 0;
-  const data = typeof message.data === "string" ? parseJsonObject(message.data, "Websocket message data") : message.data && typeof message.data === "object" && !Array.isArray(message.data) ? message.data : {};
+  const data = typeof message.data === "string" ? parseJsonObject(message.data, "Websocket message data") : isPlainObject(message.data) ? message.data : {};
   return Object.freeze({
     event,
     ...typeof channel2 === "undefined" ? {} : { channel: channel2 },
     data
   });
 }
+function normalizeRealtimeAction(value) {
+  if (value === "query" || value === "mutation" || value === "subscribe" || value === "unsubscribe") {
+    return value;
+  }
+  throw new Error("[@holo-js/broadcast] Realtime action is invalid.");
+}
+function normalizeRealtimeArgs(value) {
+  if (!isPlainObject(value)) {
+    return {};
+  }
+  return value;
+}
+function isRecord(value) {
+  return isObjectRecord(value);
+}
+function parseRealtimeSocketMessage(data) {
+  const id = normalizeRequiredString(String(data.id ?? ""), "Realtime request id");
+  const action = normalizeRealtimeAction(data.action);
+  const name = typeof data.name === "string" ? normalizeRequiredString(data.name, "Realtime definition name") : void 0;
+  if (action !== "unsubscribe" && !name) {
+    throw new Error("[@holo-js/broadcast] Realtime definition name is required.");
+  }
+  return Object.freeze({
+    id,
+    action,
+    ...typeof name === "undefined" ? {} : { name },
+    args: normalizeRealtimeArgs(data.args)
+  });
+}
 function normalizePublishBody(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error("[@holo-js/broadcast] Publish payload must be a JSON object.");
@@ -120,6 +145,60 @@ function logSocketCleanupError(socketId, channel2, error) {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`[@holo-js/broadcast] Socket cleanup failed for socket "${socketId}" on "${channel2}": ${message}`);
 }
+function logRealtimeSubscriptionCleanupError(socketId, subscriptionId, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[@holo-js/broadcast] Realtime subscription cleanup failed for socket "${socketId}" on "${subscriptionId}": ${message}`);
+}
+function safeEqual(left, right) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function signChannelAuth(secret, socketId, channel2, channelData) {
+  const value = channelData ? `${socketId}:${channel2}:${channelData}` : `${socketId}:${channel2}`;
+  return createHmac("sha256", secret).update(value).digest("hex");
+}
+function parseClientChannelAuth(data) {
+  if (typeof data.auth !== "string") {
+    return void 0;
+  }
+  return Object.freeze({
+    auth: normalizeRequiredString(data.auth, "Subscription auth"),
+    ...typeof data.channel_data === "string" ? { channelData: data.channel_data } : {}
+  });
+}
+function parseSignedChannelData(value) {
+  if (!value) {
+    return Object.freeze({
+      whispers: Object.freeze([])
+    });
+  }
+  const data = parseJsonObject(value, "Subscription channel data");
+  const whispers = Array.isArray(data.whispers) ? Object.freeze(data.whispers.map((item) => normalizeRequiredString(String(item), "Auth whisper"))) : Object.freeze([]);
+  const member = data.member && typeof data.member === "object" && !Array.isArray(data.member) ? Object.freeze(data.member) : void 0;
+  return Object.freeze({
+    whispers,
+    ...typeof member === "undefined" ? {} : { member }
+  });
+}
+function verifyClientChannelAuth(app, socketId, channel2, clientAuth) {
+  const [key, signature] = clientAuth.auth.split(":", 2);
+  if (key !== app.key || !signature) {
+    throw new Error("[@holo-js/broadcast] Channel authorization signature is invalid.");
+  }
+  const expected = signChannelAuth(app.secret, socketId, channel2, clientAuth.channelData ?? "");
+  if (!safeEqual(signature, expected)) {
+    throw new Error("[@holo-js/broadcast] Channel authorization signature is invalid.");
+  }
+  return parseSignedChannelData(clientAuth.channelData);
+}
+function unsubscribeRealtimeSubscription(socket, id, subscription) {
+  try {
+    subscription.unsubscribe();
+  } catch (error) {
+    logRealtimeSubscriptionCleanupError(socket.socketId, id, error);
+  }
+}
 function parseChannelKind(channel2) {
   if (channel2.startsWith("private-")) {
     return Object.freeze({
@@ -423,13 +502,16 @@ function pusherEvent(event, data, channel2) {
     data: typeof data === "string" ? data : JSON.stringify(data)
   });
 }
-async function authenticateSubscription(app, connection, channel2, channelAuth, fetcher) {
+async function authenticateSubscription(app, connection, channel2, clientAuth, channelAuth, fetcher) {
   const { kind, canonical } = parseChannelKind(channel2);
   if (kind === "public") {
     return Object.freeze({
       whispers: Object.freeze([])
     });
   }
+  if (clientAuth) {
+    return verifyClientChannelAuth(app, connection.socketId, channel2, clientAuth);
+  }
   if (app.authEndpoint && fetcher) {
     const authRequest = new Request(app.authEndpoint, {
       method: "POST",
@@ -456,10 +538,15 @@ async function authenticateSubscription(app, connection, channel2, channelAuth,
       ...typeof member === "undefined" ? {} : { member }
     });
   }
+  const guard = await resolveBroadcastChannelGuard({
+    channel: canonical,
+    socketId: connection.socketId
+  }, channelAuth);
   const resolvedUser = typeof channelAuth?.resolveUser === "function" ? await channelAuth.resolveUser({
     headers: connection.headers,
     socketId: connection.socketId,
     channel: canonical,
+    ...typeof guard === "undefined" ? {} : { guard },
     appId: app.appId,
     connection: app.connection
   }) : null;
@@ -655,6 +742,130 @@ function createBroadcastWorkerRuntime(options) {
       excludeSocketId
     );
   }
+  function sendRealtimeMessage(socket, event, data) {
+    socket.send(pusherEvent(event, data));
+  }
+  function resolveRealtimeErrorStatus(error) {
+    if (!isRecord(error)) {
+      return void 0;
+    }
+    const decision = isRecord(error.decision) ? error.decision : void 0;
+    const status = decision?.status ?? error.status ?? error.statusCode;
+    if (typeof status === "number" && Number.isInteger(status) && status >= 400 && status <= 599) {
+      return status;
+    }
+    const name = typeof error.name === "string" ? error.name : "";
+    if (name === "RealtimeUnauthorizedError") {
+      return 401;
+    }
+    if (name === "RealtimeForbiddenError") {
+      return 403;
+    }
+    return void 0;
+  }
+  function resolveRealtimeErrorCode(error) {
+    if (!isRecord(error)) {
+      return void 0;
+    }
+    const decision = isRecord(error.decision) ? error.decision : void 0;
+    const code = decision?.code ?? error.code;
+    return typeof code === "string" ? code : void 0;
+  }
+  function resolveRealtimeErrorKind(error, status) {
+    if (!isRecord(error)) {
+      return "runtime";
+    }
+    const name = typeof error.name === "string" ? error.name : "";
+    if (name === "AuthorizationError" || name === "RealtimeUnauthorizedError" || name === "RealtimeForbiddenError" || status === 401 || status === 403 || status === 404) {
+      return "authorization";
+    }
+    return name === "RealtimeAuthUnavailableError" ? "transport" : "runtime";
+  }
+  function sendRealtimeError(socket, id, error) {
+    const status = resolveRealtimeErrorStatus(error);
+    const code = resolveRealtimeErrorCode(error);
+    const name = error instanceof Error ? error.name : void 0;
+    const kind = resolveRealtimeErrorKind(error, status);
+    sendRealtimeMessage(socket, "holo:realtime:error", {
+      id,
+      message: error instanceof Error ? error.message : String(error),
+      kind,
+      ...typeof name === "undefined" ? {} : { name },
+      ...typeof status === "undefined" ? {} : { status },
+      ...typeof code === "undefined" ? {} : { code }
+    });
+  }
+  function createRealtimeExecutionContext(socket) {
+    return Object.freeze({
+      headers: socket.headers,
+      socketId: socket.socketId,
+      appId: socket.app.appId,
+      connection: socket.app.connection
+    });
+  }
+  async function handleRealtimeMessage(socket, data) {
+    const realtime = options.realtime;
+    const request = parseRealtimeSocketMessage(data);
+    if (!realtime) {
+      sendRealtimeError(socket, request.id, new Error('[@holo-js/broadcast] Realtime requires broadcast worker support. Run "holo broadcast:work" from a project with @holo-js/realtime installed.'));
+      return;
+    }
+    if (request.action === "unsubscribe") {
+      const subscription = socket.realtimeSubscriptions.get(request.id);
+      if (subscription) {
+        unsubscribeRealtimeSubscription(socket, request.id, subscription);
+      }
+      socket.realtimeSubscriptions.delete(request.id);
+      sendRealtimeMessage(socket, "holo:realtime:unsubscribed", {
+        id: request.id
+      });
+      return;
+    }
+    const context = createRealtimeExecutionContext(socket);
+    try {
+      if (request.action === "query") {
+        const result = await realtime.query(request.name, request.args, context);
+        sendRealtimeMessage(socket, "holo:realtime:result", {
+          id: request.id,
+          action: request.action,
+          snapshot: {
+            ...result,
+            version: 1
+          }
+        });
+        return;
+      }
+      if (request.action === "mutation") {
+        const result = await realtime.mutate(request.name, request.args, context);
+        sendRealtimeMessage(socket, "holo:realtime:result", {
+          id: request.id,
+          action: request.action,
+          result
+        });
+        return;
+      }
+      const previousSubscription = socket.realtimeSubscriptions.get(request.id);
+      if (previousSubscription) {
+        unsubscribeRealtimeSubscription(socket, request.id, previousSubscription);
+        socket.realtimeSubscriptions.delete(request.id);
+      }
+      const subscription = await realtime.subscribe(request.name, request.args, {
+        context,
+        onData(snapshot) {
+          sendRealtimeMessage(socket, "holo:realtime:snapshot", {
+            id: request.id,
+            snapshot
+          });
+        },
+        onError(error) {
+          sendRealtimeError(socket, request.id, error);
+        }
+      });
+      socket.realtimeSubscriptions.set(request.id, subscription);
+    } catch (error) {
+      sendRealtimeError(socket, request.id, error);
+    }
+  }
   async function publishScalingEvent(body) {
     if (!scaling) {
       return;
@@ -766,9 +977,9 @@ function createBroadcastWorkerRuntime(options) {
       }
     }
   }
-  async function handleSubscribe(socket, rawChannel) {
+  async function handleSubscribe(socket, rawChannel, clientAuth) {
     const channel2 = normalizeRequiredString(rawChannel, "Subscription channel");
-    const authorization = await authenticateSubscription(socket.app, socket, channel2, options.channelAuth, options.fetch);
+    const authorization = await authenticateSubscription(socket.app, socket, channel2, clientAuth, options.channelAuth, options.fetch);
     if (!socket.active || connectedSockets.get(socket.socketId) !== socket) {
       return;
     }
@@ -931,8 +1142,7 @@ function createBroadcastWorkerRuntime(options) {
     try {
       publishBody = normalizePublishBody(parseJsonObject(bodyText, "Publish body"));
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Invalid publish payload";
-      return new Response(message, { status: 400 });
+      return new Response(error.message, { status: 400 });
     }
     let result;
     try {
@@ -992,6 +1202,7 @@ function createBroadcastWorkerRuntime(options) {
         send: connection.send,
         close: connection.close,
         subscribedChannels: /* @__PURE__ */ new Set(),
+        realtimeSubscriptions: /* @__PURE__ */ new Map(),
         active: true,
         pendingMessage: Promise.resolve()
       });
@@ -1015,7 +1226,7 @@ function createBroadcastWorkerRuntime(options) {
           return;
         }
         if (message.event === "pusher:subscribe") {
-          await handleSubscribe(socket, String(message.data.channel ?? ""));
+          await handleSubscribe(socket, String(message.data.channel ?? ""), parseClientChannelAuth(message.data));
           return;
         }
         if (message.event === "pusher:unsubscribe") {
@@ -1024,6 +1235,10 @@ function createBroadcastWorkerRuntime(options) {
         }
         if (message.event.startsWith("client-")) {
           await handleClientEvent(socket, message);
+          return;
+        }
+        if (message.event === "holo:realtime") {
+          await handleRealtimeMessage(socket, message.data);
         }
       });
       socket.pendingMessage = task.catch(() => {
@@ -1040,6 +1255,10 @@ function createBroadcastWorkerRuntime(options) {
       }
       socket.active = false;
       connectedSockets.delete(socketId);
+      for (const [subscriptionId, subscription] of socket.realtimeSubscriptions) {
+        unsubscribeRealtimeSubscription(socket, subscriptionId, subscription);
+      }
+      socket.realtimeSubscriptions.clear();
       const channelsToCleanup = [...socket.subscribedChannels];
       const scalingCleanupTasks = channelsToCleanup.map((channel2) => {
         const removedPresenceMember = removeSubscriptionLocal(socket.app.appId, socket.socketId, channel2);
@@ -1184,6 +1403,7 @@ async function startBroadcastWorker(runtimeBindings) {
   const runtime = createBroadcastWorkerRuntime({
     config,
     channelAuth: runtimeBindings.channelAuth,
+    realtime: runtimeBindings.realtime,
     fetch: runtimeBindings.fetch ?? fetch,
     scaling: scalingConfig,
     scalingAutoSubscribe: false,
@@ -1409,8 +1629,11 @@ var broadcastPackage = Object.freeze({
   parseBroadcastAuthEndpointPayload,
   presenceChannel,
   privateChannel,
+  renderBroadcastClientConfigResponse,
   renderBroadcastAuthResponse,
   resetBroadcastRuntime,
+  resolveBroadcastClientConfig,
+  resolveBroadcastChannelGuard,
   resolveBroadcastWhisperSchema,
   startBroadcastWorker,
   validateBroadcastWhisperPayload,
@@ -1443,8 +1666,11 @@ export {
   privateChannel,
   registerBroadcastDriver,
   renderBroadcastAuthResponse,
+  renderBroadcastClientConfigResponse,
   resetBroadcastDriverRegistry,
   resetBroadcastRuntime,
+  resolveBroadcastChannelGuard,
+  resolveBroadcastClientConfig,
   resolveBroadcastWhisperSchema,
   startBroadcastWorker,
   validateBroadcastWhisperPayload,

package/dist/runtime.mjs

@@ -6,8 +6,8 @@ import {
   getBroadcastRuntime,
   getBroadcastRuntimeBindings,
   resetBroadcastRuntime
-} from "./chunk-QYXS4X72.mjs";
-import "./chunk-DHKMBH25.mjs";
+} from "./chunk-TTKGDABI.mjs";
+import "./chunk-HE6HN7ID.mjs";
 export {
   broadcast,
   broadcastRaw,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/broadcast",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Holo-JS Framework - broadcast contracts, channel definitions, and driver registration seams",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,11 @@
       "import": "./dist/auth.mjs",
       "default": "./dist/auth.mjs"
     },
+    "./client-config": {
+      "types": "./dist/client-config.d.ts",
+      "import": "./dist/client-config.mjs",
+      "default": "./dist/client-config.mjs"
+    },
     "./contracts": {
       "types": "./dist/contracts.d.ts",
       "import": "./dist/contracts.mjs",
@@ -38,8 +43,8 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/config": "^0.1.8",
-    "@holo-js/validation": "^0.1.8",
+    "@holo-js/config": "^0.2.0",
+    "@holo-js/validation": "^0.2.0",
     "ws": "^8.18.3"
   },
   "peerDependencies": {