@h-ai/serv 0.1.0-alpha.33 → 0.1.0-alpha.35

package/README.md

@@ -10,6 +10,7 @@
 - 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
 - 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页、可选内部 RPC endpoint
 - 可选传输加密：`serv.createApp({ transport: { crypto } })` 自动挂载密钥协商与请求/响应加解密
+- 可选语音入口：`serv.createApp({ audio: { ai } })` 在 `${apiPrefix}/ai/audio` 挂载统一语音 WebSocket，基于 `ai.audio` 提供非实时/实时的语音识别与合成（复用 `iam` 令牌校验鉴权，`serv.listen` 自动完成 WS 升级注入）
 
 > 生命周期说明：`@h-ai/serv` 本身是无状态 HTTP App 装配器，不需要 `init()` / `close()`；请在创建 app 前初始化 `iam` / `storage` / `ai` / `crypto` 等依赖，并在 `serv.listen(..., { onClose })` 中反向释放它们。`serv.createApp()` 遇到启动期配置错误（例如 transport manager 创建失败）会 fail-fast 抛出，便于进程启动阶段暴露问题。
 

package/dist/features/ai.d.ts

@@ -3,7 +3,7 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import * as _orpc_server from '@orpc/server';
 import { AIFunctions } from '@h-ai/ai';
-import { S as ServContext } from '../serv-context-CwewduFi.js';
+import { a as ServContext } from '../serv-context-CatIx8r-.js';
 import '@h-ai/core';
 
 /** AI 默认 procedures 依赖。 */

package/dist/features/iam.d.ts

@@ -4,7 +4,7 @@ import * as zod from 'zod';
 import * as _orpc_server from '@orpc/server';
 import { IamFunctions } from '@h-ai/iam';
 export { TokenPair } from '@h-ai/iam';
-import { S as ServContext } from '../serv-context-CwewduFi.js';
+import { a as ServContext } from '../serv-context-CatIx8r-.js';
 import '@h-ai/core';
 
 /** IAM 默认 procedures 依赖。 */

package/dist/features/storage.d.ts

@@ -3,7 +3,7 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import * as _orpc_server from '@orpc/server';
 import { StorageFunctions } from '@h-ai/storage';
-import { S as ServContext } from '../serv-context-CwewduFi.js';
+import { a as ServContext } from '../serv-context-CatIx8r-.js';
 import '@h-ai/core';
 
 /** Storage 默认 procedures 依赖。 */

package/dist/index.d.ts

@@ -2,14 +2,38 @@ import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, ValidationFormError } from '@h-ai/core';
 import { Router, implement } from '@orpc/server';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
+import { AIFunctions } from '@h-ai/ai';
+import { S as ServSession, a as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-CatIx8r-.js';
+export { d as CreateServContextInput, e as RefreshTokenPair } from './serv-context-CatIx8r-.js';
 import { MiddlewareHandler } from 'hono';
-import { S as ServContext, a as ServIam, R as RefreshCookieConfig, b as ServSession, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-CwewduFi.js';
-export { d as CreateServContextInput, e as RefreshTokenPair } from './serv-context-CwewduFi.js';
 import { z, ZodType } from 'zod';
 import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
 import { ServerType } from '@hono/node-server';
 import { AddressInfo } from 'node:net';
 
+/**
+ * @h-ai/serv — 统一语音 WebSocket 接入
+ *
+ * 基于 `@h-ai/ai` 的 `ai.audio` 提供开箱即用的语音 WebSocket 端点，同时支持非实时 / 实时
+ * 的语音识别与语音合成。传输细节（WebSocket 帧、二进制/JSON 编解码）在此内部完成，
+ * 客户端只使用统一的领域协议，不接触任何厂商原生事件。
+ * @module features/serv-feature-audio
+ */
+
+/** 语音 WebSocket 接入依赖。 */
+interface AudioWsDeps {
+    /** AI 服务对象的语音能力（`ai.audio`）。 */
+    readonly ai: Pick<AIFunctions, 'audio'>;
+    /** 访问令牌校验（提供后连接必须携带有效令牌；未提供则不做鉴权）。 */
+    readonly verifyToken?: (token: string) => Promise<HaiResult<ServSession>>;
+    /** 单条消息字节上限（默认 1 MiB，防止内存放大）。 */
+    readonly maxMessageBytes?: number;
+    /** 单连接累计接收音频字节上限（默认 10 MiB，防止非流式缓冲无限增长）。 */
+    readonly maxBufferedBytes?: number;
+    /** 单连接最长持续时间（毫秒，默认 5 分钟，防止恶意长连接）。 */
+    readonly maxSessionMs?: number;
+}
+
 /**
  * @h-ai/serv — Pipeline 共享类型
  *
@@ -311,6 +335,33 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
      * ```
      */
     readonly transport?: ServTransportConfig;
+    /**
+     * 启用统一语音 WebSocket 入口（opt-in）。提供后 serv 自动：
+     * 1. 在 `${apiPrefix}/ai/audio`（可自定义 `path`）注册语音 WebSocket 路由
+     * 2. 基于 `ai.audio` 提供非实时 / 实时的语音识别与合成
+     * 3. 复用同一套令牌校验（iam / verifyToken）对 WebSocket 连接鉴权
+     *
+     * 需配合 `serv.listen()`（Node 适配器会自动完成 WebSocket 升级注入）。
+     *
+     * @example
+     * ```ts
+     * serv.createApp({ contract, procedures, iam, audio: { ai } })
+     * ```
+     */
+    readonly audio?: ServAudioConfig;
+}
+/** `serv.createApp()` 的语音 WebSocket 接入配置。 */
+interface ServAudioConfig {
+    /** AI 服务对象（提供 `ai.audio` 领域能力）。 */
+    readonly ai: AudioWsDeps['ai'];
+    /** 语音入口路径（相对 apiPrefix，默认 `/ai/audio`）。 */
+    readonly path?: string;
+    /** 单条消息字节上限（默认 1 MiB）。 */
+    readonly maxMessageBytes?: number;
+    /** 单连接累计接收音频字节上限（默认 10 MiB）。 */
+    readonly maxBufferedBytes?: number;
+    /** 单连接最长持续时间（毫秒，默认 5 分钟）。 */
+    readonly maxSessionMs?: number;
 }
 /**
  * 创建并装配 HTTP API app。
@@ -684,4 +735,4 @@ declare const serv: {
     m: (key: "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationStringMin" | "serv_validationStringMax" | "serv_validationNumberMin" | "serv_validationNumberMax" | "serv_validationArrayMin" | "serv_validationArrayMax" | "serv_validationTooSmall" | "serv_validationTooBig" | "serv_validationEmail" | "serv_validationUrl" | "serv_validationUuid" | "serv_validationEnum" | "serv_errorUnauthorized" | "serv_errorForbidden" | "serv_errorInternal" | "serv_storageKeyRequired" | "serv_storageKeyTooLong" | "serv_storageKeyIllegalChars" | "serv_storageKeyDotSegments" | "serv_iamCannotDeleteCurrentUser" | "serv_transportInvalidPayload" | "serv_transportUnknownClient" | "serv_transportClientIdRequired" | "serv_transportClientKeyNotFound" | "serv_transportDecryptFailed" | "serv_transportEncryptFailed" | "serv_transportKeyExchangeFailed", options?: _h_ai_core.MessageOptions) => string;
 };
 
-export { type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServDocsHttpConfig, type ServFetchHandler, type ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, ServSession, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+export { type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServDocsHttpConfig, type ServFetchHandler, type ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, ServSession, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -1,12 +1,15 @@
 import { WILDCARD_PERMISSION, requirePermission } from './chunk-YQV2OMQK.js';
 import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody } from './chunk-4QBF4PUG.js';
 import { implement } from '@orpc/server';
-import process from 'process';
+import process2 from 'process';
 import { serve } from '@hono/node-server';
-import { core, err, HaiCommonError, ok } from '@h-ai/core';
+import { AUDIO_WS_PATH } from '@h-ai/ai';
+import { core, ok, err, HaiCommonError } from '@h-ai/core';
+import { createNodeWebSocket } from '@hono/node-ws';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
 import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
+import { Buffer } from 'buffer';
 import { z } from 'zod';
 import { IAM_AUTH_ROUTES } from '@h-ai/api-contract';
 import { getCookie } from 'hono/cookie';
@@ -23,55 +26,301 @@ function toFetch(app) {
   };
   return handler;
 }
-var DEFAULT_SERV_HOST = "127.0.0.1";
-var DEFAULT_SERV_PORT = 3e3;
-function listen(app, options = {}) {
-  const host = options.host ?? process.env.HOST ?? DEFAULT_SERV_HOST;
-  const port = options.port ?? (process.env.PORT ? Number(process.env.PORT) : DEFAULT_SERV_PORT);
-  const server = serve(
-    { fetch: app.fetch, hostname: host, port },
-    options.onListening
-  );
-  const handle = {
-    server,
-    address: { host, port },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error)
-          reject(error);
-        else resolve();
+var logger = core.logger.child({ module: "serv", scope: "audio-ws" });
+var DEFAULT_MAX_MESSAGE_BYTES = 1048576;
+var DEFAULT_MAX_BUFFERED_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_SESSION_MS = 5 * 60 * 1e3;
+function registerAudioWsRoute(app, path, upgradeWebSocket, deps) {
+  const maxMessageBytes = deps.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+  const maxBufferedBytes = deps.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  const maxSessionMs = deps.maxSessionMs ?? DEFAULT_MAX_SESSION_MS;
+  app.get(path, upgradeWebSocket((c) => {
+    const token = c.req.query("access_token") ?? c.req.header("authorization")?.replace(/^Bearer\s+/i, "");
+    const conn = new AudioConnection(deps, token, maxMessageBytes, maxBufferedBytes);
+    let sessionTimer;
+    return {
+      onOpen(_evt, ws) {
+        sessionTimer = setTimeout(() => {
+          conn.fail(ws, "hai:ai:057", "audio session timeout");
+        }, maxSessionMs);
+      },
+      onMessage(evt, ws) {
+        conn.handleMessage(ws, evt.data).catch((error) => {
+          logger.debug("audio ws message handling failed", { error: error instanceof Error ? error.message : String(error) });
+        });
+      },
+      onClose() {
+        if (sessionTimer)
+          clearTimeout(sessionTimer);
+        conn.dispose();
+      },
+      onError() {
+        if (sessionTimer)
+          clearTimeout(sessionTimer);
+        conn.dispose();
+      }
+    };
+  }));
+}
+var AsyncQueue = class {
+  items = [];
+  waiting = null;
+  ended = false;
+  push(item) {
+    if (this.ended)
+      return;
+    if (this.waiting) {
+      const w = this.waiting;
+      this.waiting = null;
+      w({ value: item, done: false });
+    } else {
+      this.items.push(item);
+    }
+  }
+  end() {
+    if (this.ended)
+      return;
+    this.ended = true;
+    if (this.waiting) {
+      const w = this.waiting;
+      this.waiting = null;
+      w({ value: void 0, done: true });
+    }
+  }
+  async *iterate() {
+    while (true) {
+      if (this.items.length > 0) {
+        yield this.items.shift();
+        continue;
+      }
+      if (this.ended)
+        return;
+      const next = await new Promise((res) => {
+        this.waiting = res;
       });
-    })
-  };
-  if (options.onClose) {
-    const onClose = options.onClose;
-    let shuttingDown = false;
-    const shutdown = async () => {
-      if (shuttingDown)
+      if (next.done)
+        return;
+      yield next.value;
+    }
+  }
+};
+var AudioConnection = class {
+  constructor(deps, token, maxMessageBytes, maxBufferedBytes) {
+    this.deps = deps;
+    this.token = token;
+    this.maxMessageBytes = maxMessageBytes;
+    this.maxBufferedBytes = maxBufferedBytes;
+  }
+  started = false;
+  start;
+  audioQueue = new AsyncQueue();
+  textQueue = new AsyncQueue();
+  audioBuffer = [];
+  receivedBytes = 0;
+  controller = new AbortController();
+  closed = false;
+  async handleMessage(ws, data) {
+    if (this.closed)
+      return;
+    const bytes = toBytes(data);
+    if (bytes) {
+      if (!this.started) {
+        this.fail(ws, "hai:ai:050", "audio frame before start");
         return;
-      shuttingDown = true;
-      try {
-        await handle.close();
-      } catch {
       }
-      try {
-        await onClose();
-      } catch {
+      if (bytes.length > this.maxMessageBytes) {
+        this.fail(ws, "hai:ai:058", "audio frame too large");
+        return;
       }
-    };
-    process.once("SIGINT", () => void shutdown());
-    process.once("SIGTERM", () => void shutdown());
+      this.receivedBytes += bytes.length;
+      if (this.receivedBytes > this.maxBufferedBytes) {
+        this.fail(ws, "hai:ai:058", "buffered audio exceeds limit");
+        return;
+      }
+      if (this.start?.stream)
+        this.audioQueue.push(bytes);
+      else
+        this.audioBuffer.push(bytes);
+      return;
+    }
+    if (typeof data !== "string")
+      return;
+    if (data.length > this.maxMessageBytes) {
+      this.fail(ws, "hai:ai:058", "message too large");
+      return;
+    }
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      this.fail(ws, "hai:ai:050", "invalid json message");
+      return;
+    }
+    if (message.type === "start") {
+      await this.onStart(ws, message);
+    } else if (!this.started) {
+      this.fail(ws, "hai:ai:050", "message before start");
+    } else if (message.type === "text") {
+      this.textQueue.push(message.text);
+    } else if (message.type === "done") {
+      this.audioQueue.end();
+      this.textQueue.end();
+      if (this.start && !this.start.stream && this.start.operation === "transcribe")
+        await this.runBufferedTranscribe(ws);
+    }
   }
-  return handle;
+  async onStart(ws, message) {
+    if (this.started) {
+      this.fail(ws, "hai:ai:050", "session already started");
+      return;
+    }
+    this.started = true;
+    this.start = message;
+    if (this.deps.verifyToken) {
+      if (!this.token) {
+        this.fail(ws, "hai:ai:054", "missing access token");
+        return;
+      }
+      const auth = await this.deps.verifyToken(this.token);
+      if (!auth.success) {
+        this.fail(ws, "hai:ai:054", "unauthorized");
+        return;
+      }
+    }
+    if (message.operation === "synthesize")
+      void this.runSynthesize(ws, message);
+    else if (message.operation === "transcribe" && message.stream)
+      void this.runStreamTranscribe(ws, message);
+  }
+  /** 流式识别：桥接持续音频输入，流式返回临时/最终结果与语音起止事件 */
+  async runStreamTranscribe(ws, start) {
+    try {
+      const stream = this.deps.ai.audio.transcribeStream({
+        audio: {
+          chunks: this.audioQueue.iterate(),
+          format: start.format ?? "pcm16",
+          sampleRate: start.sampleRate ?? 16e3,
+          channels: start.channels
+        },
+        language: start.language,
+        contextHints: start.contextHints,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      for await (const event of stream) {
+        if (event.type === "transcript")
+          this.send(ws, { type: "transcript", text: event.text, final: event.final });
+        else if (event.type === "speech_started")
+          this.send(ws, { type: "speech_started" });
+        else if (event.type === "speech_stopped")
+          this.send(ws, { type: "speech_stopped" });
+      }
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  /** 非流式识别：缓冲完整音频后返回单条最终结果 */
+  async runBufferedTranscribe(ws) {
+    const start = this.start;
+    if (!start)
+      return;
+    try {
+      const result = await this.deps.ai.audio.transcribe({
+        audio: {
+          data: concat(this.audioBuffer),
+          format: start.format ?? "wav",
+          sampleRate: start.sampleRate,
+          channels: start.channels
+        },
+        language: start.language,
+        contextHints: start.contextHints,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      if (!result.success) {
+        this.fail(ws, String(result.error.code), result.error.message);
+        return;
+      }
+      this.send(ws, { type: "transcript", text: result.data.text, final: true });
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  /** 语音合成：桥接文本输入，流式返回音频二进制帧 */
+  async runSynthesize(ws, start) {
+    try {
+      const stream = this.deps.ai.audio.synthesizeStream({
+        text: this.textQueue.iterate(),
+        voice: start.voice,
+        instruction: start.instruction,
+        format: start.format,
+        sampleRate: start.sampleRate,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      for await (const audio of stream)
+        ws.send(toArrayBuffer(audio));
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  fail(ws, code, message) {
+    this.send(ws, { type: "error", code, message });
+    this.dispose();
+    ws.close();
+  }
+  failFromError(ws, error) {
+    const hai = error;
+    const code = typeof hai?.code === "string" ? hai.code : "hai:ai:054";
+    const message = error instanceof Error ? error.message : String(error);
+    this.fail(ws, code, message);
+  }
+  end(ws) {
+    this.send(ws, { type: "end" });
+    this.dispose();
+    ws.close();
+  }
+  send(ws, message) {
+    if (!this.closed)
+      ws.send(JSON.stringify(message));
+  }
+  dispose() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.audioQueue.end();
+    this.textQueue.end();
+    this.controller.abort();
+  }
+};
+function toBytes(data) {
+  if (typeof data === "string")
+    return void 0;
+  if (data instanceof ArrayBuffer)
+    return new Uint8Array(data);
+  if (ArrayBuffer.isView(data))
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (Buffer.isBuffer(data))
+    return new Uint8Array(data);
+  return void 0;
 }
-var WILDCARD_ROLE = "*";
-function requireRole(role, handler) {
-  return requireAuth(async (options) => {
-    const roles = options.context.session?.roles ?? [];
-    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
-      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
-    return handler(options);
-  });
+function concat(chunks) {
+  const total = chunks.reduce((sum, c) => sum + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+function toArrayBuffer(data) {
+  const buffer = new ArrayBuffer(data.length);
+  new Uint8Array(buffer).set(data);
+  return buffer;
 }
 var DEFAULT_LOCALE = "zh-CN";
 function resolveRequestLocale(headers) {
@@ -293,7 +542,7 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
   return {
     cookieName: config.cookieName ?? "hai_refresh_token",
     maxAge: config.maxAge ?? 30 * 24 * 3600,
-    isSecure: config.secure ?? process.env.NODE_ENV === "production",
+    isSecure: config.secure ?? process2.env.NODE_ENV === "production",
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_ROUTES.refresh}`,
     onRefresh
   };
@@ -479,7 +728,7 @@ function readScalarBrowserEntry(packageInfo) {
   const browser = packageInfo.browser;
   return typeof browser === "string" ? browser : void 0;
 }
-var logger = core.logger.child({ module: "serv", scope: "transport" });
+var logger2 = core.logger.child({ module: "serv", scope: "transport" });
 var MAX_ENCRYPTED_BODY = 1048576;
 var ENCRYPTABLE_RESPONSE_CONTENT_TYPES = ["application/json"];
 function createTransportMiddleware(manager, keyExchangePath, excludePaths = []) {
@@ -520,7 +769,7 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [])
     try {
       bodyText = await response.clone().text();
     } catch (cause) {
-      logger.warn("Failed to read response body for encryption", { error: cause });
+      logger2.warn("Failed to read response body for encryption", { error: cause });
       c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
       return;
     }
@@ -532,7 +781,7 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [])
     }
     const encResult = await manager.encryptResponse(clientId, bodyText);
     if (!encResult.success) {
-      logger.warn("Failed to encrypt response", { error: encResult.error });
+      logger2.warn("Failed to encrypt response", { error: encResult.error });
       c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
       return;
     }
@@ -564,7 +813,7 @@ async function handleKeyExchange(request, manager) {
       headers: { "Content-Type": "application/json; charset=utf-8" }
     });
   } catch (cause) {
-    logger.error("Key exchange failed", { error: cause });
+    logger2.error("Key exchange failed", { error: cause });
     return jsonError(servM("serv_transportKeyExchangeFailed"), 500);
   }
 }
@@ -582,7 +831,7 @@ async function decryptRequestInPlace(c, manager) {
     return jsonError(servM("serv_transportInvalidPayload"), 400);
   const decResult = manager.decryptRequest(payload);
   if (!decResult.success) {
-    logger.warn("Failed to decrypt request", { error: decResult.error });
+    logger2.warn("Failed to decrypt request", { error: decResult.error });
     return jsonError(servM("serv_transportDecryptFailed"), 400);
   }
   const original = c.req.raw;
@@ -639,6 +888,7 @@ function isEncryptedPayloadShape(value) {
 
 // src/serv-app.ts
 var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+var audioWsInjectors = /* @__PURE__ */ new WeakMap();
 function createApp(options) {
   const http = resolveServHttpConfig(options.http);
   const app = new Hono();
@@ -672,6 +922,18 @@ function createApp(options) {
     mountHealthRoutes(app, http.health);
   if (options.refreshCookie)
     mountRefreshCookieRoutes(app, http.apiPrefix, options.refreshCookie, options.iam);
+  if (options.audio) {
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
+    const audioPath = `${http.apiPrefix}${options.audio.path ?? AUDIO_WS_PATH}`;
+    registerAudioWsRoute(app, audioPath, upgradeWebSocket, {
+      ai: options.audio.ai,
+      verifyToken,
+      maxMessageBytes: options.audio.maxMessageBytes,
+      maxBufferedBytes: options.audio.maxBufferedBytes,
+      maxSessionMs: options.audio.maxSessionMs
+    });
+    audioWsInjectors.set(app, injectWebSocket);
+  }
   mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
   if (http.rpc !== false)
     mountRPCRoutes(app, options.procedures, http.rpc, createContext);
@@ -779,6 +1041,61 @@ function isOrpcValidationErrorPayload(value) {
   return Array.isArray(issues);
 }
 
+// src/adapters/serv-adapter-node.ts
+var DEFAULT_SERV_HOST = "127.0.0.1";
+var DEFAULT_SERV_PORT = 3e3;
+function listen(app, options = {}) {
+  const host = options.host ?? process2.env.HOST ?? DEFAULT_SERV_HOST;
+  const port = options.port ?? (process2.env.PORT ? Number(process2.env.PORT) : DEFAULT_SERV_PORT);
+  const server = serve(
+    { fetch: app.fetch, hostname: host, port },
+    options.onListening
+  );
+  const injectWebSocket = audioWsInjectors.get(app);
+  if (injectWebSocket)
+    injectWebSocket(server);
+  const handle = {
+    server,
+    address: { host, port },
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error)
+          reject(error);
+        else resolve();
+      });
+    })
+  };
+  if (options.onClose) {
+    const onClose = options.onClose;
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown)
+        return;
+      shuttingDown = true;
+      try {
+        await handle.close();
+      } catch {
+      }
+      try {
+        await onClose();
+      } catch {
+      }
+    };
+    process2.once("SIGINT", () => void shutdown());
+    process2.once("SIGTERM", () => void shutdown());
+  }
+  return handle;
+}
+var WILDCARD_ROLE = "*";
+function requireRole(role, handler) {
+  return requireAuth(async (options) => {
+    const roles = options.context.session?.roles ?? [];
+    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
+      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
+    return handler(options);
+  });
+}
+
 // src/serv-cors.ts
 var DEFAULT_CORS_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE", "OPTIONS"];
 var DEFAULT_CORS_ALLOWED_HEADERS = ["Authorization", "Content-Type", "X-Requested-With"];