stitchkit 0.52.0 → 0.53.0

package/README.md

@@ -221,7 +221,7 @@ const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEv
   cors: { origin: 'https://app.example.com' },
 })
 
-socket.io.on('connection', (s) => { /* rooms, handshake auth — your domain logic */ })
+socket.io.on('connection', (s) => { /* rooms — your domain logic; typed handshake auth via `handshake` */ })
 
 createServer({
   services: [service],

package/dist/browser/http.d.ts

@@ -61,6 +61,13 @@ export interface HttpClientConfig {
      * Default `false`.
      */
     trace?: boolean;
+    /**
+     * Dial a unix domain socket instead of TCP (Bun runtime only — other
+     * runtimes ignore the option and dial `baseUrl` over TCP). `baseUrl` stays
+     * required as the path/prefix source; its host is ignored by the socket
+     * transport, so `baseUrl: 'http://localhost'` is the idiomatic pairing.
+     */
+    unix?: string;
 }
 type ParamValue = string | number | boolean | undefined;
 type ParamArrayValue = Array<string | number>;

package/dist/browser/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/browser/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/browser/http.ts"],"names":[],"mappings":"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"}

package/dist/browser/socket-io.d.ts

@@ -91,6 +91,34 @@ export interface SocketIOClientConfig<TServerEvents extends SocketEventMap = Soc
      * cycle. Only the first emitted argument of an event is retained.
      */
     retain?: Array<keyof TServerEvents & string>;
+    /**
+     * Observe handshake/connection failures (`connect_error`). `terminal: true`
+     * means socket.io will NOT retry on its own — that is how a server-side
+     * handshake gate rejection (`io.use` middleware / the stitchkit `handshake`
+     * option, `data.code === 'handshake_rejected'`) arrives, unlike a
+     * transport-level failure which keeps retrying. On a terminal error the
+     * client resets its connection intent, so a later `connect()` starts a fresh
+     * attempt and re-reads a function-form `auth` — the recovery path after
+     * rotating a rejected token. For transport-level failures (server down) the
+     * hook fires once **per retry attempt** — debounce before wiring it to
+     * user-facing alerts.
+     */
+    onConnectError?: (error: {
+        message: string;
+        data?: unknown;
+        terminal: boolean;
+    }) => void;
+    /**
+     * Observe every emit dropped because the socket was disconnected (the
+     * central alternative to guarding each call with `connected`). Receives the
+     * **wire** arguments — for a validated `RealtimeClient` that is the
+     * Zod-parsed values plus the wrapped ack callback, not the caller's original
+     * arguments. The drop itself is also reported by `emit` returning `false`.
+     */
+    onDroppedEmit?: (dropped: {
+        event: string;
+        args: unknown[];
+    }) => void;
 }
 export interface SocketIOClient<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> {
     /** Create the socket (if absent) and connect. Idempotent. */
@@ -105,8 +133,16 @@ export interface SocketIOClient<TServerEvents extends SocketEventMap, TClientEve
      * survives a `disconnect()` / `connect()` cycle.
      */
     on<E extends keyof TServerEvents & string>(event: E, handler: TServerEvents[E]): () => void;
-    /** Emit a client → server event. No-op while disconnected. */
-    emit<E extends keyof TClientEvents & string>(event: E, ...args: Parameters<TClientEvents[E]>): void;
+    /**
+     * Emit a client → server event. Returns `true` when the event was handed to
+     * the transport (not a delivery guarantee) and `false` when it was dropped
+     * because the socket is disconnected — including the window while the lazy
+     * peer is still loading right after `connect()`. A drop also fires the
+     * `onDroppedEmit` hook. The default stays a drop (no buffering): after a
+     * reconnect the durable subscriptions replay state deterministically instead
+     * of an unordered backlog of stale emits.
+     */
+    emit<E extends keyof TClientEvents & string>(event: E, ...args: Parameters<TClientEvents[E]>): boolean;
     /**
      * Subscribe to connection up/down changes. Returns an unsubscribe. On a
      * disconnect the listener also receives the Socket.IO **reason** (e.g.

package/dist/browser/socket-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/browser/socket-io.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/browser/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AA0D5B;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,oBAAoB,CAAC,aAAa,SAAS,cAAc,GAAG,cAAc;IACzF,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,IAAI,CAAC,EACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACvE,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACzF;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,cAAc,CAC7B,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;IAChB,+CAA+C;IAC/C,UAAU,IAAI,IAAI,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC5F;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC;IACX;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,CAC7C,SAAQ,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC;IACjE,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzF;AAED,MAAM,WAAW,qBAAqB,CAAC,eAAe,SAAS,qBAAqB,CAClF,SAAQ,oBAAoB,CAAC;KAC1B,MAAM,IAAI,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI;CAChE,CAAC;IACF,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EAEnD,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,EAAE,qBAAqB,CAAC,eAAe,CAAC,GACxE,cAAc,CAAC,eAAe,EAAE,eAAe,CAAC,CAiClD;AAED,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,CAAC,aAAa,CAAC,GAAG,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAuL3F"}

package/dist/{index-d6jj3cp5.js → index-6jngw7hw.js}

@@ -27,7 +27,8 @@ import {
   __require,
   isRecord,
   parseTrailingWildcard,
-  resolveTraceContext
+  resolveTraceContext,
+  transportResult
 } from "./index-bmnhqtya.js";
 
 // src/server/multipart.ts
@@ -1913,7 +1914,7 @@ function createValidatedRealtimeSocket({
           acknowledgement(ack.data);
         });
       }
-      emitTarget(event, ...wireArgs);
+      return emitTarget(event, ...wireArgs) !== false;
     }
   };
 }
@@ -2035,6 +2036,43 @@ async function importPeer(load, pkg) {
     throw err;
   }
 }
+function handshakeRejection(message) {
+  const error = new Error(message);
+  error.data = { code: "handshake_rejected" };
+  return error;
+}
+function handshakeMiddleware(handshake) {
+  return (socket, next) => {
+    let parsed;
+    try {
+      parsed = handshake.schema.safeParse(socket.handshake.auth);
+    } catch (error) {
+      console.error("[stitchkit] handshake schema threw — use a synchronous schema", error);
+      next(handshakeRejection("handshake auth failed validation"));
+      return;
+    }
+    if (!parsed.success) {
+      next(handshakeRejection("handshake auth failed validation"));
+      return;
+    }
+    const verify = handshake.verify;
+    Promise.resolve().then(() => {
+      if (verify)
+        return verify(parsed.data, { handshake: socket.handshake });
+      return transportResult(parsed.data);
+    }).then((identity) => {
+      if (identity === null || identity === undefined) {
+        next(handshakeRejection("handshake rejected"));
+        return;
+      }
+      socket.data = identity;
+      next();
+    }, (error) => {
+      console.error("[stitchkit] handshake verify rejected", error);
+      next(handshakeRejection("handshake rejected"));
+    });
+  };
+}
 async function createSocketIOServer(config) {
   const path = config.path ?? "/socket.io/";
   const onBun = "Bun" in globalThis;
@@ -2084,6 +2122,8 @@ async function createSocketIOServer(config) {
     pingInterval,
     allowRequest
   });
+  if (config.handshake)
+    io.use(handshakeMiddleware(config.handshake));
   const lifecycle = {
     beginShutdown() {
       accepting = false;

package/dist/index.js

@@ -397,19 +397,21 @@ function parseApiErrorBody(body) {
     hint: typeof error.hint === "string" ? error.hint : undefined
   };
 }
-function createRetryAwareFetch() {
+function createRetryAwareFetch(unix) {
   const runtimeFetch = globalThis.fetch.bind(globalThis);
   let attempt = 0;
   return (input, init) => {
     attempt += 1;
-    if (attempt === 1) {
+    if (unix === undefined && attempt === 1) {
       return runtimeFetch(input, init);
     }
-    if (!(input instanceof Request))
-      return runtimeFetch(input, init);
+    if (!(input instanceof Request)) {
+      return runtimeFetch(input, unix === undefined ? init : { ...init, unix });
+    }
     const streamedBody = input.body ? { body: input.body, duplex: "half" } : {};
     return runtimeFetch(input.url, {
       ...init,
+      ...unix !== undefined && { unix },
       method: input.method,
       headers: input.headers,
       ...streamedBody,
@@ -490,7 +492,7 @@ function createHttpClient(config) {
   async function request(method, url, data, options = {}) {
     const cancellation = createRequestCancellation(options.signal, options.timeout ?? config.timeout ?? 30000);
     const kyOptions = {
-      fetch: createRetryAwareFetch(),
+      fetch: createRetryAwareFetch(config.unix),
       timeout: false,
       signal: cancellation.signal
     };
@@ -991,7 +993,7 @@ function createValidatedRealtimeSocket({
           acknowledgement(ack.data);
         });
       }
-      emitTarget(event, ...wireArgs);
+      return emitTarget(event, ...wireArgs) !== false;
     }
   };
 }
@@ -1128,6 +1130,16 @@ function createSocketIOClient(config) {
     socket.io.on("reconnect_failed", () => {
       desiredConnected = false;
     });
+    socket.on("connect_error", (error) => {
+      const terminal = socket !== null && !socket.active;
+      if (terminal)
+        desiredConnected = false;
+      config.onConnectError?.({
+        message: error.message,
+        data: Reflect.get(error, "data"),
+        terminal
+      });
+    });
     if (retained) {
       for (const name of retainNames) {
         socket.on(name, (payload) => retained.record(name, payload));
@@ -1181,10 +1193,13 @@ function createSocketIOClient(config) {
       };
     },
     emit(event, ...args) {
-      if (!socket?.connected)
-        return;
       const name = event;
+      if (!socket?.connected) {
+        config.onDroppedEmit?.({ event: name, args });
+        return false;
+      }
       socket.emit(name, ...args);
+      return true;
     },
     onConnectionChange(listener) {
       connectionListeners.add(listener);

package/dist/node.d.ts

@@ -12,6 +12,6 @@ export { type NodeRuntimeServer, type NodeServerConfig, type NodeServerHandle, t
 export { bindProcessSignals, type ProcessSignalName, type ProcessSignalsBinding, type ProcessSignalsErrorPhase, type ProcessSignalsOptions, type ShutdownTarget, type SignalSource, } from './server/process-signals';
 export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './server/realtime';
 export { type ManagedServerHandle, type ShutdownOptions, ShutdownOptionsSchema, type ShutdownResult, ShutdownResultSchema, type ShutdownState, ShutdownStateSchema, type ShutdownStatus, ShutdownStatusSchema, } from './server/shutdown';
-export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIORequestPolicy, type SocketIOServerConfig, } from './server/socket-io-node';
+export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIOHandshakeConfig, type SocketIORequestPolicy, type SocketIOServerConfig, } from './server/socket-io-node';
 export type { EffectiveScope, FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ScopeContexts, ScopedHandlers, ServiceDef, } from './server/types';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,EAC3B,SAAS,EACT,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,cAAc,EACd,UAAU,GACX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,EAC3B,SAAS,EACT,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,cAAc,EACd,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/node.js

@@ -8,7 +8,7 @@ import {
   createHandler,
   createServerLifecycle,
   createSocketIOServer
-} from "./index-d6jj3cp5.js";
+} from "./index-6jngw7hw.js";
 import {
   createImplement,
   createImplementRegistry,

package/dist/realtime/socket.d.ts

@@ -23,7 +23,14 @@ export declare const REALTIME_TARGET_FORMS: ({
 })[];
 export interface ValidatedRealtimeSocket<TInbound extends RealtimeEventRegistry, TOutbound extends RealtimeEventRegistry> {
     on<TEvent extends keyof TInbound & string>(event: TEvent, handler: RealtimeEventHandler<TInbound[TEvent]>): () => void;
-    emit<TEvent extends keyof TOutbound & string>(event: TEvent, ...args: RealtimeEmitArguments<TOutbound[TEvent]>): void;
+    /**
+     * Emit a validated event. Three outcomes, in order: a local contract
+     * violation **throws** (validation runs even while disconnected); an emit a
+     * disconnected browser transport drops returns `false`; otherwise `true` —
+     * accepted by the transport, which is not a delivery guarantee. Server
+     * targets always return `true` (an empty room is not a drop).
+     */
+    emit<TEvent extends keyof TOutbound & string>(event: TEvent, ...args: RealtimeEmitArguments<TOutbound[TEvent]>): boolean;
 }
 export declare function createValidatedRealtimeSocket<const TInbound extends RealtimeEventRegistry, const TOutbound extends RealtimeEventRegistry>({ target, inbound, outbound, inboundDirection, outboundDirection, onRejected, logger, subscribe, }: ValidatedRealtimeSocketOptions<TInbound, TOutbound>): ValidatedRealtimeSocket<TInbound, TOutbound>;
 export {};

package/dist/realtime/socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,qBAAqB,EAErB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EAEvB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,UAAU,8BAA8B,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,iBAAiB,EAAE,uBAAuB,CAAC;IAC3C,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAClF;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB;;;;;;;;;IAOhC,CAAC;AAEH,MAAM,WAAW,uBAAuB,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,EAAE,CAAC,MAAM,SAAS,MAAM,QAAQ,GAAG,MAAM,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAC9C,MAAM,IAAI,CAAC;IACd,IAAI,CAAC,MAAM,SAAS,MAAM,SAAS,GAAG,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,GAAG,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAChD,IAAI,CAAC;CACT;AA+DD,wBAAgB,6BAA6B,CAC3C,KAAK,CAAC,QAAQ,SAAS,qBAAqB,EAC5C,KAAK,CAAC,SAAS,SAAS,qBAAqB,EAC7C,EACA,MAAM,EACN,OAAO,EACP,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,MAAM,EACN,SAAS,GACV,EAAE,8BAA8B,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,uBAAuB,CAC9E,QAAQ,EACR,SAAS,CACV,CA0HA"}
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,qBAAqB,EAErB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EAEvB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,UAAU,8BAA8B,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,iBAAiB,EAAE,uBAAuB,CAAC;IAC3C,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAClF;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB;;;;;;;;;IAOhC,CAAC;AAEH,MAAM,WAAW,uBAAuB,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,EAAE,CAAC,MAAM,SAAS,MAAM,QAAQ,GAAG,MAAM,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAC9C,MAAM,IAAI,CAAC;IACd;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,SAAS,MAAM,SAAS,GAAG,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,GAAG,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAChD,OAAO,CAAC;CACZ;AA+DD,wBAAgB,6BAA6B,CAC3C,KAAK,CAAC,QAAQ,SAAS,qBAAqB,EAC5C,KAAK,CAAC,SAAS,SAAS,qBAAqB,EAC7C,EACA,MAAM,EACN,OAAO,EACP,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,MAAM,EACN,SAAS,GACV,EAAE,8BAA8B,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,uBAAuB,CAC9E,QAAQ,EACR,SAAS,CACV,CA+HA"}

package/dist/server/bun.d.ts

@@ -14,10 +14,29 @@ type BunDevelopmentOptions = BunServeOptions extends {
     development?: infer T;
 } ? T : never;
 export type ServerPassthrough = Omit<BunServeOptions, 'fetch' | 'port' | 'hostname' | 'unix' | 'routes' | 'websocket' | 'development'>;
+/**
+ * Unix domain socket listener. The plain-string form binds the path as-is;
+ * the object form additionally tightens the socket file mode after listen —
+ * `mode: 0o600` is the right choice when access to the socket IS the
+ * credential (a local daemon whose only auth is filesystem permission).
+ */
+export type UnixListenConfig = string | {
+    path: string;
+    mode?: number;
+};
 /** Bun-specific server config layered over the Fetch-clean handler config. */
 export interface BunServerConfig extends BunHandlerConfig, BunFetchComposition {
     port?: number;
     hostname?: string;
+    /**
+     * Listen on a unix domain socket instead of a TCP port. Mutually exclusive
+     * with `port`/`hostname`. A stale socket file left by a killed process is
+     * reclaimed (probe-then-unlink, best-effort against concurrent starts); a
+     * path answered by a live listener — or one this process may not probe —
+     * fails loudly. Not compatible with the Socket.IO lifecycle (`socket`):
+     * socket.io clients cannot dial a unix socket.
+     */
+    unix?: UnixListenConfig;
     websocket?: BunWebSocketHandlers;
     /** Full Stitchkit Socket.IO lifecycle; route and default websocket are mounted automatically. */
     socket?: SocketIOServerLifecycle;

package/dist/server/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAE7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAyIrE"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAyD7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA6LrE"}

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
 export { AppError, appError, badRequest, conflict, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from '../contract';
 export { errorCode, formatZodError, normalizeError, type ZodIssueSummary, zodIssues, } from '../internal/errors';
 export { isWithinDir } from '../internal/within-dir';
-export { type BunFetchComposition as FetchComposition, type BunFetchHandler as FetchHandler, type BunHandlerConfig as HandlerConfig, type BunRawRoute as RawRoute, type BunRawRouteContext as RawRouteContext, type BunServer, type BunServerConfig, type BunServerHandle, createServer, type ServerPassthrough, } from './bun';
+export { type BunFetchComposition as FetchComposition, type BunFetchHandler as FetchHandler, type BunHandlerConfig as HandlerConfig, type BunRawRoute as RawRoute, type BunRawRouteContext as RawRouteContext, type BunServer, type BunServerConfig, type BunServerHandle, createServer, type ServerPassthrough, type UnixListenConfig, } from './bun';
 export { type CacheOptions, cacheHeaders, createCache } from './cache';
 export { createHandler } from './create';
 export { createErrorHook, type ErrorHookConfig, type ResolvedError, } from './error-hook';
@@ -21,7 +21,7 @@ export { errorResponse, parseBody, respondJson } from './raw';
 export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './realtime';
 export { type ClientIpOptions, extractIp, generateTraceId, getClientInfo, resolveSocketIp, resolveTraceId, } from './request';
 export { type ManagedServerHandle, type ShutdownOptions, ShutdownOptionsSchema, type ShutdownResult, ShutdownResultSchema, type ShutdownState, ShutdownStateSchema, type ShutdownStatus, ShutdownStatusSchema, } from './shutdown';
-export type { SocketIORequestPolicy, SocketIOServerConfig, SocketIOServerHandle, SocketIOServerLifecycle, } from './socket-io';
+export type { SocketIOHandshakeConfig, SocketIORequestPolicy, SocketIOServerConfig, SocketIOServerHandle, SocketIOServerLifecycle, } from './socket-io';
 export { createSocketIOServer, socketIoLane } from './socket-io';
 export { type ParseSSEOptions, parseSSE, streamSSE } from './stream';
 export type { AuthorizationContext, EffectiveScope, EndpointHandlerContext, Handlers, LifecycleHooks, LoggingConfig, LogOutcome, MethodDef, MultipartFileMetadata, MultipartReceiver, MultipartReceiverResult, OperationIdentity, RouteGroup, ScopeContexts, ScopedHandlers, ServiceDef, StitchLogger, StreamingMultipartImplementation, } from './types';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -12,7 +12,7 @@ import {
   parseMultipart,
   socketIoLane,
   webSocketLane
-} from "../index-d6jj3cp5.js";
+} from "../index-6jngw7hw.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -75,6 +75,39 @@ import {
   parseTrailingWildcard
 } from "../index-bmnhqtya.js";
 // src/server/bun.ts
+import { chmodSync, statSync, unlinkSync } from "node:fs";
+function reclaimStaleUnixSocket(path) {
+  const stats = statSync(path, { throwIfNoEntry: false });
+  if (stats === undefined)
+    return;
+  if (!stats.isSocket()) {
+    throw new Error(`[stitchkit] createServer: "${path}" exists and is not a socket — refusing to remove it`);
+  }
+  if (typeof process.getuid === "function" && stats.uid !== process.getuid()) {
+    throw new Error(`[stitchkit] createServer: unix socket "${path}" is owned by another user — refusing to reclaim it`);
+  }
+  const standalone = Bun.main.startsWith("/$bunfs/");
+  const interpreter = standalone ? Bun.which("bun") : process.execPath;
+  if (!interpreter) {
+    throw new Error(`[stitchkit] createServer: unix socket "${path}" already exists and no \`bun\` binary is on PATH to probe it from this compiled executable — remove the file manually if the previous process is dead`);
+  }
+  const probe = Bun.spawnSync({
+    cmd: [
+      interpreter,
+      "-e",
+      'try { const socket = await Bun.connect({ unix: Bun.env.STITCHKIT_UNIX_PROBE ?? "", socket: { data() { return undefined; } } }); socket.end(); process.exit(0); } catch (error) { process.exit(error && typeof error === "object" && "code" in error && error.code === "EACCES" ? 2 : 1); }'
+    ],
+    env: { ...process.env, STITCHKIT_UNIX_PROBE: path },
+    timeout: 2000
+  });
+  if (probe.exitedDueToTimeout) {
+    throw new Error(`[stitchkit] createServer: liveness probe for unix socket "${path}" timed out — refusing to reclaim; remove the file manually if the previous process is dead`);
+  }
+  if (probe.exitCode === 0 || probe.exitCode === 2) {
+    throw new Error(`[stitchkit] createServer: unix socket "${path}" is already in use${probe.exitCode === 2 ? " (connect permission denied)" : " by a live listener"}`);
+  }
+  unlinkSync(path);
+}
 function createServer(config) {
   const {
     websocket: configuredWebSocket,
@@ -84,6 +117,19 @@ function createServer(config) {
     port = 3000,
     hostname
   } = config;
+  const unixPath = typeof config.unix === "string" ? config.unix : config.unix?.path;
+  const unixMode = typeof config.unix === "string" ? undefined : config.unix?.mode;
+  if (unixPath !== undefined) {
+    if (unixPath.length === 0) {
+      throw new Error("[stitchkit] createServer: `unix` must be a non-empty socket path");
+    }
+    if (config.port !== undefined || config.hostname !== undefined) {
+      throw new Error("[stitchkit] createServer: `unix` is mutually exclusive with `port`/`hostname`");
+    }
+    if (socket) {
+      throw new Error("[stitchkit] createServer: the Socket.IO lifecycle cannot listen on a unix socket — socket.io clients dial TCP only");
+    }
+  }
   const socketRoutePrefix = socket?.route.path.replace(/\*socketPath$/, "");
   const websocket = configuredWebSocket ?? socket?.websocket;
   const openSockets = new Set;
@@ -176,24 +222,43 @@ function createServer(config) {
     }
     return admittedFetch(request, server2);
   };
-  runtime = trackedWebSocket ? Bun.serve({
-    ...bunExtra,
-    ...development && { development },
-    port,
-    hostname,
-    websocket: trackedWebSocket,
-    fetch
-  }) : Bun.serve({
-    ...bunExtra,
-    ...development && { development },
-    port,
-    hostname,
-    fetch
-  });
+  if (unixPath !== undefined) {
+    reclaimStaleUnixSocket(unixPath);
+    const { reusePort, ipv6Only, http3, http1, idleTimeout, ...unixExtra } = bunExtra ?? {};
+    runtime = trackedWebSocket ? Bun.serve({
+      ...unixExtra,
+      ...development && { development },
+      unix: unixPath,
+      websocket: trackedWebSocket,
+      fetch
+    }) : Bun.serve({
+      ...unixExtra,
+      ...development && { development },
+      unix: unixPath,
+      fetch
+    });
+    if (unixMode !== undefined)
+      chmodSync(unixPath, unixMode);
+  } else {
+    runtime = trackedWebSocket ? Bun.serve({
+      ...bunExtra,
+      ...development && { development },
+      port,
+      hostname,
+      websocket: trackedWebSocket,
+      fetch
+    }) : Bun.serve({
+      ...bunExtra,
+      ...development && { development },
+      port,
+      hostname,
+      fetch
+    });
+  }
   const server = runtime;
   return {
     url: server.url.toString().replace(/\/$/, ""),
-    port: server.port ?? port,
+    port: server.port ?? (unixPath !== undefined ? 0 : port),
     runtime: server,
     get status() {
       return lifecycle.status;

package/dist/server/realtime.d.ts

@@ -1,24 +1,28 @@
-import type { Socket, Server as SocketIOServer } from 'socket.io';
+import type { DefaultEventsMap, Socket, Server as SocketIOServer } from 'socket.io';
 import type { SocketEventMap } from '../browser/socket-io';
 import type { StitchLogger } from '../logger';
 import type { RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook } from '../realtime/contract';
 import { type ValidatedRealtimeSocket } from '../realtime/socket';
-export interface RealtimeServerConnection<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> {
-    /** Raw Socket.IO socket for handshake auth, rooms and application-owned delivery policy. */
-    raw: Socket;
+export interface RealtimeServerConnection<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry, TData = any> {
+    /**
+     * Raw Socket.IO socket for rooms and application-owned delivery policy.
+     * `raw.data` carries the typed handshake identity when the server was
+     * created with a `handshake` gate.
+     */
+    raw: Socket<SocketEventMap, SocketEventMap, DefaultEventsMap, TData>;
     events: ValidatedRealtimeSocket<TClientToServer, TServerToClient>;
     to(room: string): Pick<ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>, 'emit'>;
 }
-export interface RealtimeServer<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> {
-    onConnection(handler: (connection: RealtimeServerConnection<TServerToClient, TClientToServer>) => void | Promise<void>): () => void;
+export interface RealtimeServer<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry, TData = any> {
+    onConnection(handler: (connection: RealtimeServerConnection<TServerToClient, TClientToServer, TData>) => void | Promise<void>): () => void;
     emit: ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>['emit'];
     to(room: string): Pick<ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>, 'emit'>;
 }
-export interface RealtimeServerHandle {
-    io: SocketIOServer<SocketEventMap, SocketEventMap>;
+export interface RealtimeServerHandle<TData = any> {
+    io: SocketIOServer<SocketEventMap, SocketEventMap, DefaultEventsMap, TData>;
 }
-export declare function bindRealtimeServer<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, handle: RealtimeServerHandle, options?: {
+export declare function bindRealtimeServer<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry, TData = any>(contract: RealtimeContract<TServerToClient, TClientToServer>, handle: RealtimeServerHandle<TData>, options?: {
     onRejected?: RealtimeRejectedEventHook;
     logger?: StitchLogger;
-}): RealtimeServer<TServerToClient, TClientToServer>;
+}): RealtimeServer<TServerToClient, TClientToServer, TData>;
 //# sourceMappingURL=realtime.d.ts.map

package/dist/server/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/server/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB,CACvC,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB;IAE7C,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClE,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB;IAE7C,YAAY,CACV,OAAO,EAAE,CACP,UAAU,EAAE,wBAAwB,CAAC,eAAe,EAAE,eAAe,CAAC,KACnE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,MAAM,IAAI,CAAC;IACd,IAAI,EAAE,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EAEnD,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC9E,cAAc,CAAC,eAAe,EAAE,eAAe,CAAC,CAsClD"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/server/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB,CACvC,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACrE,MAAM,EAAE,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClE,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX,YAAY,CACV,OAAO,EAAE,CACP,UAAU,EAAE,wBAAwB,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,KAC1E,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,MAAM,IAAI,CAAC;IACd,IAAI,EAAE,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,GAAG;IAC/C,EAAE,EAAE,cAAc,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;CAC7E;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,GAAG,GAAG,EAEX,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC9E,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,CAwCzD"}

package/dist/server/socket-io-config.d.ts

@@ -1,8 +1,42 @@
 /** Runtime-neutral Socket.IO configuration shared by Bun and Node adapters. */
-import type { ServerOptions } from 'socket.io';
+import type { ServerOptions, Socket } from 'socket.io';
+import type { z } from 'zod';
 /** Runtime-neutral Engine.IO handshake policy, evaluated before shutdown admission. */
 export type SocketIORequestPolicy = (request: Request) => boolean | Promise<boolean>;
-export interface SocketIOServerConfig {
+/**
+ * Typed identity gate for the Socket.IO handshake. `schema` validates
+ * `socket.handshake.auth` (the structured channel — `query` values are strings
+ * on the wire); an optional `verify` turns the parsed payload into the
+ * connection identity. Returning `null` or throwing rejects the handshake
+ * **before** the connection handler and before any event validation; the
+ * accepted identity is written to `socket.data`, typed end-to-end through
+ * `createSocketIOServer` and `bindRealtimeServer`.
+ *
+ * A rejected handshake is terminal for socket.io-client — it does **not**
+ * retry (unlike a transport-level denial). The stitchkit client surfaces it
+ * via `onConnectError` with `terminal: true`; recovery is an explicit
+ * `connect()`, which re-reads a function-form `auth`.
+ */
+export interface SocketIOHandshakeConfig<TParsed, TData = TParsed> {
+    /** Zod schema for `socket.handshake.auth`. */
+    schema: z.ZodType<TParsed>;
+    /**
+     * Turn the schema-validated payload into the connection identity (may be
+     * async — the wrapper awaits it safely; socket.io itself would leak an
+     * unhandled rejection from a raw async middleware). Return `null` or throw
+     * to reject; a thrown error is logged server-side and the peer sees only
+     * the generic `handshake rejected` — raw error text never crosses to an
+     * unauthenticated client. When omitted, the parsed payload itself is the
+     * identity (when passing `TData` explicitly with `TData ≠ TParsed`,
+     * `verify` is therefore mandatory — without it the runtime stores the
+     * schema output). The `schema` must be synchronous (no async
+     * refine/transform).
+     */
+    verify?: (parsed: TParsed, context: {
+        handshake: Socket['handshake'];
+    }) => TData | null | Promise<TData | null>;
+}
+export interface SocketIOServerConfig<TParsed = any, TData = TParsed> {
     /** CORS — the browser origin(s) allowed to open a socket. */
     cors: {
         origin: string | string[];
@@ -18,6 +52,15 @@ export interface SocketIOServerConfig {
     pingInterval?: number;
     /** Runtime-neutral policy for accepting a new Engine.IO handshake. */
     allowRequest?: SocketIORequestPolicy;
+    /**
+     * Typed identity gate — Zod-validate the handshake and put the result into
+     * `socket.data`. Registered as the **first** `io.use()` middleware, so app
+     * middlewares added later see the typed identity already in place. Type
+     * inference works on calls without explicit event generics (the
+     * `bindRealtimeServer` lane); with explicit generics, pass the identity
+     * types explicitly: `createSocketIOServer<S, C, Parsed, Data>`.
+     */
+    handshake?: SocketIOHandshakeConfig<TParsed, TData>;
     /** Typed Socket.IO options not owned by this wrapper. */
     serverOptions?: Omit<Partial<ServerOptions>, 'allowRequest'>;
 }

package/dist/server/socket-io-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io-config.d.ts","sourceRoot":"","sources":["../../src/server/socket-io-config.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,uFAAuF;AACvF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,yDAAyD;IACzD,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC,CAAC;CAC9D"}
+{"version":3,"file":"socket-io-config.d.ts","sourceRoot":"","sources":["../../src/server/socket-io-config.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,uFAAuF;AACvF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO,EAAE,KAAK,GAAG,OAAO;IAC/D,8CAA8C;IAC9C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,CACP,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;KAAE,KACxC,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,GAAG,OAAO;IAClE,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpD,yDAAyD;IACzD,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC,CAAC;CAC9D"}

package/dist/server/socket-io-node.d.ts

@@ -1,17 +1,17 @@
 /** Node-facing Socket.IO surface without Bun engine declarations. */
 import type { Server as HttpServer } from 'node:http';
-import type { Server as SocketIOServer } from 'socket.io';
+import type { DefaultEventsMap, Server as SocketIOServer } from 'socket.io';
 import type { SocketEventMap } from '../browser/socket-io';
 import type { SocketIOServerConfig } from './socket-io-config';
-export type { SocketIORequestPolicy, SocketIOServerConfig } from './socket-io-config';
+export type { SocketIOHandshakeConfig, SocketIORequestPolicy, SocketIOServerConfig, } from './socket-io-config';
 /** The runtime-neutral part of a Socket.IO handle used by `serveNode`. */
-export interface NodeSocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> {
-    io: SocketIOServer<TClientEvents, TServerEvents>;
+export interface NodeSocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap, TData = any> {
+    io: SocketIOServer<TClientEvents, TServerEvents, DefaultEventsMap, TData>;
     attach(server: HttpServer): void;
     beginShutdown(): void;
     close(): Promise<void>;
     connections(): number;
 }
 /** Create a Socket.IO handle typed only for the Node capabilities it exposes. */
-export declare function createNodeSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOServerConfig): Promise<NodeSocketIOServerHandle<TServerEvents, TClientEvents>>;
+export declare function createNodeSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap, TParsed = any, TData = TParsed>(config: SocketIOServerConfig<TParsed, TData>): Promise<NodeSocketIOServerHandle<TServerEvents, TClientEvents, TData>>;
 //# sourceMappingURL=socket-io-node.d.ts.map

package/dist/server/socket-io-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io-node.d.ts","sourceRoot":"","sources":["../../src/server/socket-io-node.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB,CACvC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACjD,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,aAAa,IAAI,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,iFAAiF;AACjF,wBAAsB,wBAAwB,CAC5C,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EAEpC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAEjE"}
+{"version":3,"file":"socket-io-node.d.ts","sourceRoot":"","sources":["../../src/server/socket-io-node.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,YAAY,EACV,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB,CACvC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,KAAK,GAAG,GAAG;IAEX,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IAC1E,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,aAAa,IAAI,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,iFAAiF;AACjF,wBAAsB,wBAAwB,CAC5C,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EAGpC,OAAO,GAAG,GAAG,EACb,KAAK,GAAG,OAAO,EAEf,MAAM,EAAE,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,GAC3C,OAAO,CAAC,wBAAwB,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC,CAExE"}

package/dist/server/socket-io.d.ts

@@ -17,13 +17,13 @@
  */
 import type { Server as HttpServer } from 'node:http';
 import type { Server as BunEngine } from '@socket.io/bun-engine';
-import type { Server as SocketIOServer } from 'socket.io';
+import type { DefaultEventsMap, Server as SocketIOServer } from 'socket.io';
 import type { SocketEventMap } from '../browser/socket-io';
 import type { BunServer } from './bun';
 import type { SocketIOServerConfig } from './socket-io-config';
 import type { RawRoute } from './types';
 import { type ComposedLane } from './websocket';
-export type { SocketIORequestPolicy, SocketIOServerConfig } from './socket-io-config';
+export type { SocketIOHandshakeConfig, SocketIORequestPolicy, SocketIOServerConfig, } from './socket-io-config';
 export interface SocketIOServerLifecycle {
     /**
      * WebSocket handler for `Bun.serve({ websocket })`. Real on Bun; on Node it is
@@ -52,11 +52,11 @@ export interface SocketIOServerLifecycle {
     /** Current Engine.IO client count, when the engine has been bound. */
     connections(): number;
 }
-export interface SocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> extends SocketIOServerLifecycle {
+export interface SocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap, TData = any> extends SocketIOServerLifecycle {
     /** The typed Socket.IO server — attach `io.on('connection', ...)` handlers. */
-    io: SocketIOServer<TClientEvents, TServerEvents>;
+    io: SocketIOServer<TClientEvents, TServerEvents, DefaultEventsMap, TData>;
 }
-export declare function createSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOServerConfig): Promise<SocketIOServerHandle<TServerEvents, TClientEvents>>;
+export declare function createSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap, TParsed = any, TData = TParsed>(config: SocketIOServerConfig<TParsed, TData>): Promise<SocketIOServerHandle<TServerEvents, TClientEvents, TData>>;
 /**
  * Wrap a Socket.IO handle's `websocket` as a catch-all {@link ComposedLane} for
  * {@link composeWebSocketHandlers} — when a second, raw WebSocket lane shares

package/dist/server/socket-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/server/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EACV,MAAM,IAAI,SAAS,EAEpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,MAAM,IAAI,cAAc,EAEzB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,aAAa,CAAC;AAE/D,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzD;;;;;OAKG;IACH,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,6EAA6E;IAC7E,aAAa,IAAI,IAAI,CAAC;IACtB,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,sEAAsE;IACtE,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CACnC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,CACpC,SAAQ,uBAAuB;IAC/B,+EAA+E;IAC/E,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;CAClD;AAuCD,wBAAsB,oBAAoB,CACxC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAyI3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,oBAAoB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,WAAW,CAAC,GAC3E,YAAY,CAMd"}
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/server/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EACV,MAAM,IAAI,SAAS,EAEpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,gBAAgB,EAChB,MAAM,IAAI,cAAc,EAGzB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAA2B,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,aAAa,CAAC;AAE/D,YAAY,EACV,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzD;;;;;OAKG;IACH,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,6EAA6E;IAC7E,aAAa,IAAI,IAAI,CAAC;IACtB,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,sEAAsE;IACtE,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CACnC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,KAAK,GAAG,GAAG,CACX,SAAQ,uBAAuB;IAC/B,+EAA+E;IAC/E,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;CAC3E;AA8GD,wBAAsB,oBAAoB,CACxC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EAKpC,OAAO,GAAG,GAAG,EACb,KAAK,GAAG,OAAO,EAEf,MAAM,EAAE,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,GAC3C,OAAO,CAAC,oBAAoB,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC,CA6IpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,oBAAoB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,WAAW,CAAC,GAC3E,YAAY,CAMd"}

package/llms-full.txt

@@ -851,6 +851,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `rawRoutes` | non-contract routes (see below) |
 | `maxJsonBodyBytes` | optional JSON body cap (bytes); per-route value overrides; unset preserves existing behaviour |
 | `port` / `hostname` | listen address — port defaults to `3000` |
+| `unix` | listen on a unix domain socket instead of TCP — `'/run/app.sock'` or `{ path, mode }` (see below) |
 | `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }`. `origin` is **required** when `cors` is present: pass an explicit origin (or list), or `'*'` to deliberately allow every origin — an origin-less config is a construction error, never a silent wildcard. Omit `cors` entirely to emit no CORS headers. |
 | `hooks` | lifecycle hooks (see below) |
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
@@ -864,6 +865,41 @@ Native Bun `routes` are intentionally not accepted: Bun matches them before
 `fetch`, so they could bypass shutdown admission. Use `rawRoutes`; they retain
 the Fetch `Request → Response` model and participate in lifecycle tracking.
 
+### Local daemon over a unix socket
+
+A local daemon whose door is a socket file needs no TCP port at all:
+
+```ts
+const server = createServer({
+  services,
+  unix: { path: '/run/my-daemon.sock', mode: 0o600 },
+})
+```
+
+`unix` is mutually exclusive with `port`/`hostname` (construction error). The
+handle stays honest: `server.url` is `unix:///run/my-daemon.sock` — an
+identifier, **not** a fetchable address (dial the path with
+`createHttpClient({ unix })`, [client guide](client.md#unix-domain-sockets)) —
+and `server.port` is `0`.
+
+Socket-file hygiene is built in. A stale file left by a killed process is
+reclaimed automatically: the path is probed, and only a socket that is owned by
+the current user **and** answers no live listener is removed before binding
+(best-effort — two processes racing the same path resolve through the loud
+bind error of the loser). A regular file at the path, another user's socket, or
+a live listener each fail with a specific error instead of being unlinked. A
+clean `server.shutdown()` removes the file.
+
+`mode` tightens the socket file permissions after listen. Bun creates the file
+`0755` under a normal umask — since `connect(2)` requires *write* permission
+that is already owner-only in practice — but when access to the socket **is**
+the credential, set `mode: 0o600` explicitly and let the filesystem be the
+policy. The Socket.IO lifecycle (`socket`) cannot mount on a unix listener
+(socket.io clients dial TCP only — construction error); Bun's own WebSocket
+client cannot dial a unix path either. Unix listeners are Bun-only: `srvx`
+resolves a numeric port unconditionally, so `stitchkit/node` does not offer
+`unix` (no half-support).
+
 ### Managed shutdown
 
 ```ts
@@ -1678,6 +1714,7 @@ without repeating transport configuration.
 | `suppressUnauthorizedFor` | `[]` | exact contract-derived operation matchers whose expected 401 does not emit `unauthorized` |
 | `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
 | `trace` | `false` | emit a W3C `traceparent` header on every request |
+| `unix` | — | dial a unix domain socket instead of TCP (Bun only, see below) |
 
 `headers` as a function is the hook for runtime tokens — a bearer token or any
 short-lived credential — re-evaluated on every request.
@@ -1691,6 +1728,26 @@ compile the prefix structure without a concrete tenant id. Matching is exact by
 path segments, including params and trailing wildcards — a shared prefix never
 suppresses a neighbouring protected endpoint.
 
+### Unix domain sockets
+
+The same typed client dials a local daemon's socket file
+([server side](server.md#local-daemon-over-a-unix-socket)):
+
+```ts
+const http = createHttpClient({
+  baseUrl: 'http://localhost', // required prefix source; its host is ignored
+  unix: '/run/my-daemon.sock',
+})
+const daemon = createClient(daemonContract, http)
+```
+
+`baseUrl` stays required — it supplies the path prefix and the `Host` header,
+while the connection itself goes through the socket file. Bun runtime only:
+other runtimes ignore the option and dial `baseUrl` over TCP (Node's fetch
+would need an undici dispatcher — out of scope). A missing socket file
+surfaces as a normal `ApiError` and is not retried (transport retry stays
+connection-refused-only).
+
 `trace: true` mints a fresh root trace per request. The stitchkit server
 [continues an inbound `traceparent`](./observability.md#trace-context), so the
 browser call, the HTTP handler and every nested tool call share one trace id
@@ -3286,8 +3343,11 @@ export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
 | `beginShutdown()` / `connections()` | lifecycle surface consumed by the managed server |
 
 `SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout`,
-`pingInterval` and a runtime-neutral `allowRequest(Request)` handshake policy.
-The policy is composed with managed-shutdown admission on both Bun and Node.
+`pingInterval`, a runtime-neutral `allowRequest(Request)` handshake policy and
+the typed **`handshake`** identity gate (schema + verify →
+[typed `socket.data`](#handshake-auth--cookie-or-token)). `allowRequest` is the
+transport gate (composed with managed-shutdown admission on both Bun and Node);
+`handshake` is the identity gate that runs after it.
 For anything else socket.io's `ServerOptions` exposes, use the
 typed **`serverOptions`** passthrough — most often `maxHttpBufferSize` to lift the
 1 MB default for large emits:
@@ -3337,7 +3397,40 @@ subscribe once; reconnection is the wrapper's problem, not yours.
 
 `SocketIOClientConfig` takes `url`, `path`, `withCredentials` (cookies on the
 handshake — default `true`), `auth`, `query`, `extraHeaders`, `transports`,
-`reconnectionAttempts`, `reconnectionDelay` and `retain` (below).
+`reconnectionAttempts`, `reconnectionDelay`, `retain` (below), `onConnectError`
+(handshake/connection failures — see the auth section) and `onDroppedEmit`
+(observability for emits dropped while disconnected — see below).
+
+### Honest emit — what happens while disconnected
+
+`emit` has exactly three outcomes, in order:
+
+1. **A local contract violation throws** (validated `RealtimeClient` only) —
+   validation runs before the connection guard, even while disconnected.
+2. **Disconnected → the emit is dropped**: `emit` returns `false` and the
+   `onDroppedEmit` hook fires with the event name and wire arguments. This
+   includes the short window right after `connect()` while the socket.io peer
+   is still loading.
+3. **Otherwise `emit` returns `true`** — handed to the transport, which is
+   *not* a delivery guarantee.
+
+The default is deliberately a drop, not a buffer: after a reconnect, durable
+subscriptions and [sticky events](#sticky-events) replay current state
+deterministically, instead of the server receiving an unordered backlog of
+stale emits. What changed is that the drop is now observable — assert it
+per-call (`if (!client.emit(...)) …`) or centrally:
+
+```ts
+const client = createSocketIOClient({
+  url,
+  onDroppedEmit: ({ event }) => metrics.count('realtime.dropped_emit', { event }),
+})
+```
+
+Server-side emits (`realtime.emit`, `to(room).emit`, `connection.events.emit`)
+always return `true` — a broadcast into an empty room is not a drop, and the
+server has no disconnected state of this kind. For state that must survive
+gaps, see [durability](#durability--idempotent--replay).
 
 ### Sticky events
 
@@ -3392,32 +3485,71 @@ const socket = createRealtimeClient(realtimeContract, {
 ```
 
 ```ts
-// server — the gate is your logic, on socket.handshake.auth
+// server — the typed identity gate: Zod-validate handshake.auth, verify,
+// and the result lands in socket.data — typed all the way to onConnection.
 import { verifyJwt } from 'stitchkit/server'
 
-socket.io.use(async (s, next) => {
-  const token = s.handshake.auth.token
-  if (typeof token !== 'string') return next(new Error('unauthorized'))
-  try {
-    s.data.user = await verifyJwt(token, secret)
-    next()
-  } catch {
-    next(new Error('unauthorized'))
-  }
+const socket = await createSocketIOServer({
+  cors: { origin: 'https://app.example.com' },
+  handshake: {
+    schema: z.object({ token: z.string() }),
+    verify: async ({ token }) => ({ user: await verifyJwt(token, secret) }),
+  },
+})
+
+const realtime = bindRealtimeServer(realtimeContract, socket)
+realtime.onConnection(({ raw }) => {
+  raw.data.user // typed — no String(...) coercions, no casts
 })
 ```
 
+`verify` may be async (the wrapper runs it inside a settled promise chain —
+raw async `io.use` middleware would leak an unhandled rejection); throwing or
+returning `null` rejects the handshake **before** the connection handler and
+before any event validation. A thrown error's raw message is logged
+server-side and never reaches the unauthenticated peer — the wire always
+carries the generic `handshake rejected` (the same never-leak policy as the
+HTTP error normalizer). The schema itself must be synchronous (no async
+refine/transform). Omit `verify` and the schema output itself is the
+identity. The gate registers as the **first** middleware, so `socket.io.use(…)`
+middlewares you add afterwards see the typed `socket.data` already in place.
+Raw `io.use` remains available for anything beyond identity.
+
+Type inference works on calls without explicit event generics (the
+`bindRealtimeServer` lane above). With explicit generics TypeScript cannot
+partially infer — pass the identity types too:
+`createSocketIOServer<S, C, z.infer<typeof schema>, Identity>`.
+
 A static object (`auth: { token }`) works too, but only the function form
 re-reads on reconnect — prefer it for rotating tokens. `query` adds handshake
-URL params (`socket.handshake.query`); `extraHeaders` adds handshake headers,
-but in a browser those apply to the **polling** transport only (a WebSocket
-upgrade cannot set request headers) — for browser WebSocket auth use `auth`.
-If an auth producer throws or rejects, the wrapper sends an empty auth object so
-the server gate can reject it instead of leaving the handshake waiting forever.
+URL params (`socket.handshake.query`) — note its values are **strings** on the
+wire, which is why the schema gate reads `auth`; `extraHeaders` adds handshake
+headers, but in a browser those apply to the **polling** transport only (a
+WebSocket upgrade cannot set request headers) — for browser WebSocket auth use
+`auth`.
+
+**A gate rejection is terminal for the client.** Unlike a transport-level
+failure (which socket.io retries indefinitely), a middleware/handshake-gate
+rejection stops the client: socket.io destroys its retry path and will not
+reconnect on its own. The stitchkit client surfaces this through
+**`onConnectError`** with `terminal: true` (and `data.code ===
+'handshake_rejected'` for the built-in gate) and resets its connection intent —
+so recovery is explicit: rotate the credential, call `connect()`, and the
+function-form `auth` is re-read:
+
+```ts
+const client = createRealtimeClient(realtimeContract, {
+  url: 'https://api.example.com',
+  auth: () => ({ token: getAccessToken() }),
+  onConnectError: ({ terminal }) => {
+    if (terminal) refreshTokenThen(() => client.connect())
+  },
+})
+```
 
-On a hard auth failure Socket.IO emits `connect_error` and keeps retrying
-(`reconnectionAttempts` defaults to `Infinity`) — set a finite value if a
-rejected token should stop hammering the server.
+If an auth producer throws or rejects, the wrapper sends an empty auth object —
+the server gate then rejects it visibly (via `onConnectError`) instead of
+leaving the handshake waiting forever.
 
 ## Cache bridge
 
@@ -5277,6 +5409,28 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides
@@ -6208,7 +6362,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
-| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default — [details](../guide/client.md#createhttpclient) |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `unix` dials a unix domain socket (Bun only) — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -6224,8 +6378,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `SocketIOClient` | _type_ | the client handle |
-| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`) |
+| `SocketIOClient` | _type_ | the client handle; `emit` returns `false` for an emit dropped while disconnected |
+| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
 | `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
@@ -6239,7 +6393,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeRejectDirection` | _type_ | server/client inbound/outbound rejection direction |
 | `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
 | `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
-| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries |
+| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
@@ -6393,7 +6547,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
-| `BunServerConfig` | _type_ | config for `createServer` (Bun) |
+| `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |
 | `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | one graceful budget, bounded forced-completion timeout, retry hint and optional external abort signal |
@@ -6469,9 +6624,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `bindRealtimeServer` | function | inferred, runtime-validated connection and broadcast boundary |
 | `RealtimeServer` | _type_ | validated broadcast and connection API inferred from a realtime contract |
 | `RealtimeServerConnection` | _type_ | one validated connection with raw socket access for auth and rooms |
-| `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer` |
+| `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer`; carries the handshake identity type through to `connection.raw.data` |
 | `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
-| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
+| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer`; `handshake` is the typed identity gate — [guide](../guide/realtime.md#handshake-auth--cookie-or-token) |
+| `SocketIOHandshakeConfig` | _type_ | the `handshake` gate — Zod `schema` over `handshake.auth` plus optional async `verify`; the result lands typed in `socket.data` |
 | `SocketIOServerHandle` | _type_ | typed Socket.IO server plus Bun mount fields and idempotent lifecycle |
 | `SocketIOServerLifecycle` | _type_ | non-generic Bun mount/shutdown portion accepted by `createServer` |
 | `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",