@h-ai/serv 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/index.js

@@ -1,13 +1,14 @@
-import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-TWMOZPGU.js';
-import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-I3F7RN4I.js';
-import process from 'process';
+import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-CZ6VA2EN.js';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-PLGCHDZM.js';
+import { errorMonitor } from 'events';
+import process4 from 'process';
+import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
 import { upgradeWebSocket, serve } from '@hono/node-server';
+import { posix } from 'path';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { audit } from '@h-ai/audit';
-import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
-import { TRANSPORT_PLAINTEXT_RANGE, createTransportBodyPolicy, TRANSPORT_PROTOCOL, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
+import { TRANSPORT_PLAINTEXT_RANGE, TRANSPORT_TIME_LIMITS, TRANSPORT_PROTOCOL, createTransportBodyPolicy, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
-import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { Buffer } from 'buffer';
@@ -201,7 +202,9 @@ var AudioConnection = class {
       return;
     }
     this.queue = this.queue.then(() => task()).catch((error) => {
-      logger.debug("audio ws task failed", { error: error instanceof Error ? error.message : String(error) });
+      logger.debug("audio ws task failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
       if (!this.closed)
         this.failFromError(ws, error);
     }).finally(() => {
@@ -482,7 +485,11 @@ var AudioConnection = class {
     if (this.closed)
       return;
     logger.warn("Audio WebSocket operation failed", { error });
-    const hai = error && typeof error === "object" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" ? { code: error.code, message: error.message, httpStatus: "httpStatus" in error && typeof error.httpStatus === "number" ? error.httpStatus : 500 } : { code: HaiCommonError.INTERNAL_ERROR.code, message: "", httpStatus: 500 };
+    const hai = error && typeof error === "object" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" ? {
+      code: error.code,
+      message: error.message,
+      httpStatus: "httpStatus" in error && typeof error.httpStatus === "number" ? error.httpStatus : 500
+    } : { code: HaiCommonError.INTERNAL_ERROR.code, message: "", httpStatus: 500 };
     const safe = core.error.toPublic(hai);
     this.fail(ws, String(safe.code), safe.message);
   }
@@ -513,7 +520,9 @@ var AudioConnection = class {
     this.controller.abort();
     if (this.session && this.authorizedRequest && this.deps.onSessionEnd) {
       void Promise.resolve(this.deps.onSessionEnd(this.session, this.authorizedRequest)).catch((error) => {
-        logger.warn("audio ws session end hook failed", { error: error instanceof Error ? error.message : String(error) });
+        logger.warn("audio ws session end hook failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
       });
     }
   }
@@ -548,75 +557,6 @@ function toArrayBuffer(data) {
   new Uint8Array(buffer).set(data);
   return buffer;
 }
-function readRemoteAddress(metadata) {
-  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
-    return void 0;
-  return core.access.normalizeClientIp(metadata.remoteAddress);
-}
-
-// src/pipelines/serv-pipeline-require-internal-rpc.ts
-var pipelineLogger = core.logger.child({ module: "serv", scope: "pipeline" });
-var cachedGetConnInfo;
-async function resolveGetConnInfo() {
-  if (cachedGetConnInfo !== void 0)
-    return cachedGetConnInfo;
-  try {
-    const mod = await import('@hono/node-server/conninfo');
-    cachedGetConnInfo = mod.getConnInfo;
-  } catch (cause) {
-    pipelineLogger.warn("getConnInfo unavailable in this runtime; loopback/private-network access modes will fail closed", { error: cause });
-    cachedGetConnInfo = null;
-  }
-  return cachedGetConnInfo;
-}
-var LOOPBACK_IPS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1", "localhost"]);
-function requireInternalRPC(config) {
-  return async (c, next) => {
-    const locale = resolveRequestLocale(c.req.raw.headers);
-    if (config.access === "gateway-only") {
-      const headerName = config.gatewayHeader ?? "x-hai-internal-rpc";
-      const received = c.req.header(headerName);
-      if (!config.gatewaySecret || !received || !core.string.constantTimeEqual(received, config.gatewaySecret))
-        return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-      return next();
-    }
-    const ip = await getRequestRemoteAddress(c) ?? "";
-    if (config.access === "loopback" && !isLoopbackIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    if (config.access === "private-network" && !isPrivateNetworkIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    return next();
-  };
-}
-async function getRequestRemoteAddress(c) {
-  const remoteAddress = readRemoteAddress(c.env);
-  if (remoteAddress)
-    return remoteAddress;
-  const getConnInfo = await resolveGetConnInfo();
-  if (!getConnInfo)
-    return void 0;
-  try {
-    return getConnInfo(c).remote.address;
-  } catch {
-    return void 0;
-  }
-}
-function normalizeIpAddress(ip) {
-  return ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip;
-}
-function isLoopbackIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  return LOOPBACK_IPS.has(ip) || LOOPBACK_IPS.has(normalized);
-}
-function isPrivateNetworkIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  if (isLoopbackIP(ip))
-    return true;
-  if (normalized.startsWith("10.") || normalized.startsWith("192.168."))
-    return true;
-  const second = Number(normalized.split(".")[1]);
-  return normalized.startsWith("172.") && Number.isInteger(second) && second >= 16 && second <= 31;
-}
 
 // src/pipelines/serv-pipeline-security-headers.ts
 function securityHeaders() {
@@ -627,9 +567,16 @@ function securityHeaders() {
     await next();
   };
 }
+function readRemoteAddress(metadata) {
+  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
+    return void 0;
+  return core.access.normalizeClientIp(metadata.remoteAddress);
+}
 var ApiPrefixSchema = z.custom(
-  (value) => typeof value === "string" && value.startsWith("/api/"),
-  "apiPrefix must start with /api/"
+  (value) => typeof value === "string" && /^\/[\w.-]+(?:\/[\w.-]+)*$/.test(value) && !value.split("/").some((segment) => segment === "." || segment === ".."),
+  {
+    error: () => servM("serv_invalidApiPrefix")
+  }
 );
 var AbsolutePathSchema = z.custom(
   (value) => typeof value === "string" && value.startsWith("/"),
@@ -637,7 +584,9 @@ var AbsolutePathSchema = z.custom(
 );
 var OpenAPIHttpConfigInputSchema = z.union([
   z.literal(false),
-  z.object({ path: AbsolutePathSchema.default("/openapi.json") })
+  z.object({
+    path: AbsolutePathSchema.default("/openapi.json")
+  })
 ]);
 var DocsHttpConfigInputSchema = z.union([
   z.literal(false),
@@ -653,19 +602,15 @@ var HealthHttpConfigInputSchema = z.union([
     readyPath: AbsolutePathSchema.optional().default("/ready")
   })
 ]);
-var RpcHttpConfigInputSchema = z.union([
-  z.literal(false),
-  z.object({
-    prefix: AbsolutePathSchema.default("/rpc"),
-    access: z.enum(["loopback", "private-network", "gateway-only"]).default("loopback"),
-    gatewayHeader: z.string().optional(),
-    gatewaySecret: z.string().optional()
-  })
-]);
 var TransportRuntimeConfigInputSchema = z.union([
   z.literal(false),
   z.object({
-    maxPlaintextBytes: z.union([z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max), z.literal("auto")]).transform((value) => value === "auto" ? void 0 : value).optional().describe("\u666E\u901A\u4E1A\u52A1\u53CC\u5411\u660E\u6587\u4E0A\u9650\uFF1Bauto \u4E3A 1 MiB\uFF1B\u5927\u6750\u6599\u4F7F\u7528 routePlaintextBytes \u5355\u72EC\u58F0\u660E").meta({ default: "auto" }),
+    maxPlaintextBytes: z.union([
+      z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max),
+      z.literal("auto")
+    ]).transform((value) => value === "auto" ? void 0 : value).optional().describe("\u666E\u901A\u4E1A\u52A1\u53CC\u5411\u660E\u6587\u4E0A\u9650\uFF1Bauto \u4E3A 1 MiB\uFF1B\u5927\u6750\u6599\u4F7F\u7528 routePlaintextBytes \u5355\u72EC\u58F0\u660E").meta({ default: "auto" }),
+    maxFutureSkewSeconds: z.number().int().min(0).max(TRANSPORT_TIME_LIMITS.maxFutureSkewSeconds).optional().describe("\u5141\u8BB8\u5BA2\u6237\u7AEF\u8BF7\u6C42\u65F6\u95F4\u9886\u5148\u670D\u52A1\u5668\u7684\u79D2\u6570").meta({ default: TRANSPORT_PROTOCOL.CLOCK_SKEW_MS / 1e3 }),
+    maxRequestAgeSeconds: z.number().int().min(TRANSPORT_TIME_LIMITS.minRequestAgeSeconds).max(TRANSPORT_TIME_LIMITS.maxRequestAgeSeconds).optional().describe("\u8BF7\u6C42\u4ECE\u7B7E\u53D1\u8D77\u7684\u6709\u6548\u79D2\u6570").meta({ default: TRANSPORT_PROTOCOL.REQUEST_WINDOW_MS / 1e3 }),
     routePlaintextBytes: z.record(AbsolutePathSchema, z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max)).optional().describe("\u5B8C\u6574\u8DEF\u5F84\u6BB5\u5230\u53CC\u5411\u660E\u6587\u5B57\u8282\u4E0A\u9650\u7684\u6620\u5C04\uFF1B\u661F\u53F7\u5339\u914D\u5355\u6BB5\uFF0C\u4F9B\u9644\u4EF6\u548C\u5F52\u6863\u72EC\u7ACB\u5BB9\u91CF"),
     keyExchangePath: AbsolutePathSchema.default("/_hai/key-exchange"),
     excludePaths: z.array(AbsolutePathSchema).default([])
@@ -678,7 +623,13 @@ var ServerConfigInputSchema = z.object({
 var CorsRuntimeConfigInputSchema = z.object({
   origin: z.string().optional(),
   nativeOrigins: z.string().optional(),
-  allowedHeaders: z.array(z.string()).default(["Authorization", "Content-Type", "X-Requested-With", "X-Hai-Reauthentication", "X-Hai-Terminal"]),
+  allowedHeaders: z.array(z.string()).default([
+    "Authorization",
+    "Content-Type",
+    "X-Requested-With",
+    "X-Hai-Reauthentication",
+    "X-Hai-Terminal"
+  ]),
   exposedHeaders: z.array(z.string()).default([]),
   credentials: z.boolean().default(false)
 });
@@ -688,8 +639,7 @@ var ServHttpConfigInputSchema = z.object({
   apiPrefix: ApiPrefixSchema.default("/api/v1"),
   openapi: OpenAPIHttpConfigInputSchema.default(false),
   docs: DocsHttpConfigInputSchema.default(false),
-  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" }),
-  rpc: RpcHttpConfigInputSchema.default(false)
+  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" })
 });
 var ServConfigSchema = z.object({
   server: ServerConfigInputSchema.optional(),
@@ -704,10 +654,10 @@ var ServConfigSchema = z.object({
 }));
 function readServerEnvOverride() {
   const override = {};
-  const host = process.env.HOST;
+  const host = process4.env.HOST;
   if (host)
     override.host = host;
-  const rawPort = process.env.PORT;
+  const rawPort = process4.env.PORT;
   if (rawPort) {
     const port = Number(rawPort);
     if (Number.isInteger(port) && port >= 1 && port <= 65535)
@@ -716,7 +666,10 @@ function readServerEnvOverride() {
   return override;
 }
 function resolveServServerConfig(input = {}) {
-  return { ...ServerConfigInputSchema.parse(input), ...readServerEnvOverride() };
+  return {
+    ...ServerConfigInputSchema.parse(input),
+    ...readServerEnvOverride()
+  };
 }
 function resolveServHttpConfig(input = {}) {
   return ServHttpConfigInputSchema.parse(input);
@@ -774,6 +727,87 @@ function buildAuthContextFactory(verifyToken) {
     }
   };
 }
+function createRuntimeSecurityPolicy(input) {
+  const production = input.environment?.trim().toLowerCase() === "production";
+  const configuredOrigins = parseOrigins(input.corsOrigin);
+  const configuredNativeOrigins = parseNativeOrigins(input.nativeOrigins);
+  const allowsEveryOrigin = configuredOrigins === "*";
+  if (production && (allowsEveryOrigin || configuredOrigins.length === 0))
+    throw new Error("serv.cors.origin must contain explicit HTTP(S) origins in production");
+  const allowedOrigins = allowsEveryOrigin ? void 0 : new Set(configuredOrigins);
+  const allowedNativeOrigins = new Set(configuredNativeOrigins);
+  return {
+    allowOrigin: (origin) => {
+      const normalizedNativeOrigin = tryNormalizeNativeOrigin(origin);
+      if (normalizedNativeOrigin !== void 0 && allowedNativeOrigins.has(normalizedNativeOrigin))
+        return true;
+      if (allowedOrigins === void 0)
+        return true;
+      const normalizedWebOrigin = tryNormalizeWebOrigin(origin);
+      return normalizedWebOrigin !== void 0 && allowedOrigins.has(normalizedWebOrigin);
+    },
+    isNativeOrigin: (origin) => allowedNativeOrigins.has(tryNormalizeNativeOrigin(origin) ?? ""),
+    secureRefreshCookie: resolveSecureRefreshCookie(production),
+    exposeApiDocs: !production
+  };
+}
+function resolveSecureRefreshCookie(defaultSecure) {
+  const override = process4.env.HAI_SERV_REFRESH_COOKIE_SECURE;
+  if (override === "true" || override === "false")
+    return override === "true";
+  return defaultSecure;
+}
+function parseOrigins(value) {
+  const entries = (value ?? "*").split(",").map((origin) => origin.trim()).filter(Boolean);
+  if (entries.includes("*"))
+    return "*";
+  return entries.map(normalizeWebOrigin);
+}
+function parseNativeOrigins(value) {
+  return (value ?? "").split(",").map((origin) => origin.trim()).filter(Boolean).map(normalizeNativeOrigin);
+}
+function normalizeWebOrigin(value) {
+  const normalized = tryNormalizeWebOrigin(value);
+  if (normalized === void 0)
+    throw new Error(`serv.cors.origin contains an invalid origin: ${value}`);
+  return normalized;
+}
+function normalizeNativeOrigin(value) {
+  const normalized = tryNormalizeNativeOrigin(value);
+  if (normalized === void 0)
+    throw new Error(`serv.cors.nativeOrigins contains an invalid origin: ${value}`);
+  return normalized;
+}
+function tryNormalizeWebOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.origin === "null" || url.pathname !== "/" || url.search || url.hash)
+    return void 0;
+  return url.origin;
+}
+function tryNormalizeNativeOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (![
+    "http:",
+    "https:",
+    "capacitor:",
+    "tauri:"
+  ].includes(url.protocol) || !url.hostname || url.username || url.password || !["", "/"].includes(url.pathname) || url.search || url.hash) {
+    return void 0;
+  }
+  return ["capacitor:", "tauri:"].includes(url.protocol) ? `${url.protocol}//${url.host}` : url.origin;
+}
+
+// src/serv-cookie-auth.ts
 var IAM_AUTH_PATHS = {
   login: apiContract.pathOf(apiContract.iam.auth.login),
   loginWithOtp: apiContract.pathOf(apiContract.iam.auth.loginWithOtp),
@@ -793,7 +827,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" || process.env.HAI_CORE_ENV === "production"),
+    isSecure: config.secure ?? resolveSecureRefreshCookie(process4.env.NODE_ENV === "production" || process4.env.HAI_CORE_ENV === "production"),
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_PATHS.refresh}`,
     onRefresh,
     nativeTokenTransport: config.nativeTokenTransport
@@ -908,26 +942,46 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
       const locale = resolveRequestLocale(c.req.raw.headers);
       return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale })), 401);
     }
-    const result = await onRefresh(refreshToken);
-    if (!result.success) {
-      const status = result.error.httpStatus ?? 401;
+    const fail = (internal) => {
+      const safe = core.error.toPublic(internal, void 0, resolveRequestLocale(c.req.raw.headers));
+      core.logger.error("Refresh token request failed", { traceId: safe.traceId, error: internal });
       const headers = new Headers({ "Content-Type": "application/json" });
-      if (!useNativeTokenTransport)
+      if (!useNativeTokenTransport && safe.httpStatus === 401)
         headers.set("Set-Cookie", buildClearCookieHeader(cookieName, refreshCookiePath));
-      return new Response(JSON.stringify({ success: false, error: result.error }), {
-        status,
+      return new Response(JSON.stringify({ success: false, error: safe }), {
+        status: safe.httpStatus ?? 500,
         headers
       });
+    };
+    let result;
+    try {
+      result = await onRefresh(refreshToken);
+    } catch (cause) {
+      return fail({
+        ...HaiCommonError.INTERNAL_ERROR,
+        message: servM("serv_errorInternal"),
+        cause
+      });
     }
+    if (!result.success)
+      return fail(result.error);
     const tokens = result.data;
     if (useNativeTokenTransport) {
-      return new Response(JSON.stringify({ success: true, data: { tokens } }), {
+      return new Response(JSON.stringify({
+        success: true,
+        data: { tokens }
+      }), {
         status: 200,
         headers: { "Content-Type": "application/json" }
       });
     }
     const setCookie = buildSetCookieHeader(cookieName, tokens.refreshToken, refreshCookiePath, maxAge, isSecure);
-    return new Response(JSON.stringify({ success: true, data: { tokens: stripRefreshTokenFromPair(tokens) } }), {
+    return new Response(JSON.stringify({
+      success: true,
+      data: {
+        tokens: stripRefreshTokenFromPair(tokens)
+      }
+    }), {
       status: 200,
       headers: {
         "Content-Type": "application/json",
@@ -942,17 +996,41 @@ async function readRefreshTokenFromBody(request) {
 }
 
 // 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", "X-Hai-Reauthentication", "X-Hai-Terminal"];
+var DEFAULT_CORS_METHODS = [
+  "GET",
+  "HEAD",
+  "PUT",
+  "PATCH",
+  "POST",
+  "DELETE",
+  "OPTIONS"
+];
+var DEFAULT_CORS_ALLOWED_HEADERS = [
+  "Authorization",
+  "Content-Type",
+  "X-Requested-With",
+  "X-Hai-Reauthentication",
+  "X-Hai-Terminal"
+];
 var DEFAULT_CORS_MAX_AGE = 86400;
 var corsMiddlewares = /* @__PURE__ */ new WeakSet();
 function isCorsMiddleware(middleware) {
   return corsMiddlewares.has(middleware);
 }
 function cors(config = {}) {
-  const methods = [...config.methods ?? DEFAULT_CORS_METHODS];
-  const allowedHeaders = [...config.allowedHeaders ?? DEFAULT_CORS_ALLOWED_HEADERS];
-  const exposedHeaders = [.../* @__PURE__ */ new Set(["X-Request-Id", "X-Trace-Id", ...config.exposedHeaders ?? []])];
+  const methods = [
+    ...config.methods ?? DEFAULT_CORS_METHODS
+  ];
+  const allowedHeaders = [
+    ...config.allowedHeaders ?? DEFAULT_CORS_ALLOWED_HEADERS
+  ];
+  const exposedHeaders = [
+    .../* @__PURE__ */ new Set([
+      "X-Request-Id",
+      "X-Trace-Id",
+      ...config.exposedHeaders ?? []
+    ])
+  ];
   const credentials = config.credentials ?? false;
   const maxAge = config.maxAge ?? DEFAULT_CORS_MAX_AGE;
   const originConfig = config.origin ?? "*";
@@ -999,12 +1077,15 @@ function resolveCorsOrigin(origin, configOrigin) {
     return null;
   if (configOrigin === "*")
     return "*";
-  if (typeof configOrigin === "string")
+  if (typeof configOrigin === "string") {
     return origin === configOrigin ? origin : null;
-  if (Array.isArray(configOrigin))
+  }
+  if (Array.isArray(configOrigin)) {
     return configOrigin.includes(origin) ? origin : null;
-  if (typeof configOrigin === "function")
+  }
+  if (typeof configOrigin === "function") {
     return configOrigin(origin) ? origin : null;
+  }
   return null;
 }
 function buildCorsHeaders(options) {
@@ -1035,7 +1116,9 @@ var SCALAR_BROWSER_ENTRY_FALLBACK = "./dist/browser/standalone.js";
 var scalarScriptCache;
 async function generateSpec(contract, options = {}) {
   const generator = new OpenAPIGenerator({
-    schemaConverters: [new ZodToJsonSchemaConverter()]
+    schemaConverters: [
+      new ZodToJsonSchemaConverter()
+    ]
   });
   return generator.generate(contract, {
     info: {
@@ -1043,8 +1126,12 @@ async function generateSpec(contract, options = {}) {
       version: options.version ?? "0.1.0",
       description: options.description
     },
-    servers: options.apiPrefix ? [{ url: options.apiPrefix }] : void 0,
-    security: [{ bearerAuth: [] }],
+    servers: options.apiPrefix ? [
+      { url: options.apiPrefix }
+    ] : void 0,
+    security: [
+      { bearerAuth: [] }
+    ],
     components: {
       securitySchemes: {
         bearerAuth: { type: "http", scheme: "bearer" }
@@ -1103,8 +1190,13 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [],
       return handleKeyExchange(c.req.raw, manager);
     const mode = encryption?.(pathname, c.req.method);
     if (mode === "disabled") {
-      if (c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER) || c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENVELOPE_HEADER))
-        return Response.json(err({ ...HaiCommonError.VALIDATION_ERROR, message: servM("serv_transportPlaintextRequired"), traceId: core.context.get().traceId ?? core.context.get().requestId }), { status: 400 });
+      if (c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER) || c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENVELOPE_HEADER)) {
+        return Response.json(err({
+          ...HaiCommonError.VALIDATION_ERROR,
+          message: servM("serv_transportPlaintextRequired"),
+          traceId: core.context.get().traceId ?? core.context.get().requestId
+        }), { status: 400 });
+      }
       return next();
     }
     if (mode !== "required" && shouldExclude(pathname, excludePaths, keyExchangePath))
@@ -1209,7 +1301,12 @@ async function handleKeyExchange(request, manager) {
     if (new TextEncoder().encode(serverPublicKey).byteLength > TRANSPORT_BODY_LIMITS.publicKeyBytes)
       return jsonError(servM("serv_transportKeyExchangeFailed"), 500);
     const clientId = await manager.registerClientKey(body.clientPublicKey);
-    return new Response(JSON.stringify({ serverKeyId: manager.getServerKeyId(), serverPublicKey, clientId, maxPlaintextBytes: manager.bodyLimits.plaintextBytes }), {
+    return new Response(JSON.stringify({
+      serverKeyId: manager.getServerKeyId(),
+      serverPublicKey,
+      clientId,
+      maxPlaintextBytes: manager.bodyLimits.plaintextBytes
+    }), {
       status: 200,
       headers: { "Content-Type": "application/json; charset=utf-8" }
     });
@@ -1257,7 +1354,14 @@ function jsonError(message, status) {
 }
 
 // src/serv-app.ts
-var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+var API_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS"
+];
 var audioWsServers = /* @__PURE__ */ new WeakMap();
 function createApp(options) {
   const http = resolveServHttpConfig(options.http);
@@ -1276,7 +1380,12 @@ function createApp(options) {
   });
   app.use("*", async (c, next) => {
     const requestId = resolveRequestId(c.req.header("x-request-id") ?? null);
-    await core.context.run({ requestId, userId: void 0, scopeId: void 0, jobId: void 0 }, () => core.i18n.runWithLocale(resolveRequestLocale(c.req.raw.headers), () => audit.withContext({
+    await core.context.run({
+      requestId,
+      userId: void 0,
+      scopeId: void 0,
+      jobId: void 0
+    }, () => core.i18n.runWithLocale(resolveRequestLocale(c.req.raw.headers), () => audit.withContext({
       actor: null,
       requestId,
       traceId: requestId,
@@ -1306,14 +1415,26 @@ function createApp(options) {
   });
   app.notFound((c) => c.json(buildHaiErrorBody(
     HaiCommonError.NOT_FOUND,
-    core.i18n.coreM("core_errorNotFound", { locale: resolveRequestLocale(c.req.raw.headers) })
+    core.i18n.coreM("core_errorNotFound", {
+      locale: resolveRequestLocale(c.req.raw.headers)
+    })
   ), 404));
   const iamRef = options.iam;
   const verifyToken = options.verifyToken ?? (iamRef ? (token) => iamRef.auth.verifyToken(token) : void 0);
   const contextFactory = options.createContext ?? (verifyToken ? buildAuthContextFactory(verifyToken) : parseRequestContext);
   const createContext = async (input) => {
-    const context = await contextFactory({ ...input, ip: resolveIp(input.request, input.remoteAddress) });
-    requestAuditContexts.set(input.request, { actor: context.session ? { id: context.session.userId, username: context.session.username, roles: [...context.session.roles] } : null, scopeId: context.scopeId });
+    const context = await contextFactory({
+      ...input,
+      ip: resolveIp(input.request, input.remoteAddress)
+    });
+    requestAuditContexts.set(input.request, {
+      actor: context.session ? {
+        id: context.session.userId,
+        username: context.session.username,
+        roles: [...context.session.roles]
+      } : null,
+      scopeId: context.scopeId
+    });
     return context;
   };
   let cachedSpec;
@@ -1331,7 +1452,12 @@ function createApp(options) {
       }
       return void 0;
     }
-    core.logger.info("Request access policy denied", { ruleId: decision.ruleId, reason: decision.reason, method: c.req.method, ipAddress });
+    core.logger.info("Request access policy denied", {
+      ruleId: decision.ruleId,
+      reason: decision.reason,
+      method: c.req.method,
+      ipAddress
+    });
     return c.json(buildHaiErrorBody(HaiCommonError.REQUEST_ACCESS_DENIED, core.i18n.coreM("core_requestAccessDenied")), 403);
   };
   const cors2 = options.middlewares?.filter((entry) => isCorsMiddleware(entry.middleware)) ?? [];
@@ -1366,7 +1492,9 @@ function createApp(options) {
     const mgr = options.transport.crypto.transport.createServer({
       serverKeyRing: options.transport.serverKeyRing,
       keyStore: options.transport.keyStore,
-      maxPlaintextBytes: policy.maximum.plaintextBytes
+      maxPlaintextBytes: policy.maximum.plaintextBytes,
+      maxFutureSkewSeconds: options.transport.maxFutureSkewSeconds,
+      maxRequestAgeSeconds: options.transport.maxRequestAgeSeconds
     });
     if (!mgr.success) {
       throw core.error.buildHaiErrorInst(
@@ -1402,14 +1530,13 @@ function createApp(options) {
     audioWsServers.set(app, new WebSocketServer({ noServer: true }));
   }
   mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
-  if (http.rpc !== false)
-    mountRPCRoutes(app, options.procedures, http.rpc, createContext);
   if (http.openapi !== false) {
     app.get(http.openapi.path, async (c) => c.json(await getSpec()));
   }
   if (http.docs !== false) {
     const docs = http.docs;
-    app.get(SCALAR_ROUTE, async (c) => {
+    const docsDirectory = docs.path.slice(0, docs.path.lastIndexOf("/") + 1);
+    app.get(`${docsDirectory}${SCALAR_ROUTE.slice(1)}`, async (c) => {
       const content = await getScalarScript();
       if (!content)
         return c.notFound();
@@ -1419,12 +1546,21 @@ function createApp(options) {
     });
     app.get(docs.path, async (c) => {
       if (docs.requireAuth) {
-        const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
-        if (!context.session)
-          return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
+        const context = await createContext({
+          request: c.req.raw,
+          remoteAddress: readRemoteAddress(c.env)
+        });
+        if (!context.session) {
+          return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", {
+            locale: resolveRequestLocale(c.req.raw.headers)
+          })), 401);
+        }
       }
-      const specUrl = http.openapi === false ? void 0 : http.openapi.path;
-      return c.html(createDocsPage(await getSpec(), { specUrl }));
+      const specUrl = http.openapi === false ? void 0 : posix.relative(docsDirectory, http.openapi.path) || ".";
+      return c.html(createDocsPage(await getSpec(), {
+        specUrl,
+        scriptUrl: SCALAR_ROUTE.slice(1)
+      }));
     });
   }
   return app;
@@ -1442,14 +1578,11 @@ function mountOpenAPIRoutes(app, procedures, apiPrefix, createContext) {
   const handler = new OpenAPIHandler(procedures);
   app.on([...API_METHODS], `${apiPrefix}/*`, (c, next) => handleORPC(c, next, apiPrefix, handler, createContext));
 }
-function mountRPCRoutes(app, procedures, rpcConfig, createContext) {
-  const handler = new RPCHandler(procedures);
-  const prefix = rpcConfig.prefix;
-  app.use(`${prefix}/*`, requireInternalRPC(rpcConfig));
-  app.on([...API_METHODS], `${prefix}/*`, (c, next) => handleORPC(c, next, prefix, handler, createContext));
-}
 async function handleORPC(c, next, prefix, handler, createContext) {
-  const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
+  const context = await createContext({
+    request: c.req.raw,
+    remoteAddress: readRemoteAddress(c.env)
+  });
   const { matched, response } = await core.context.run({ requestId: context.requestId, userId: context.session?.userId, scopeId: context.scopeId }, () => handler.handle(c.req.raw, { prefix, context }));
   if (!matched) {
     await next();
@@ -1479,7 +1612,10 @@ async function localizeValidationResponse(response, requestHeaders) {
     error: {
       code: HaiCommonError.VALIDATION_ERROR.code,
       traceId: core.context.get().traceId ?? core.context.get().requestId,
-      message: core.error.formatMessage({ message: servM("serv_validationFailed", { locale }), traceId: core.context.get().traceId ?? core.context.get().requestId }),
+      message: core.error.formatMessage({
+        message: servM("serv_validationFailed", { locale }),
+        traceId: core.context.get().traceId ?? core.context.get().requestId
+      }),
       httpStatus: HaiCommonError.VALIDATION_ERROR.httpStatus,
       system: HaiCommonError.VALIDATION_ERROR.system,
       module: HaiCommonError.VALIDATION_ERROR.module,
@@ -1516,6 +1652,7 @@ function listen(app, options = {}) {
   const host = options.host ?? DEFAULT_SERV_HOST;
   const port = options.port ?? DEFAULT_SERV_PORT;
   const audioServer = audioWsServers.get(app);
+  const logger3 = core.logger.child({ module: "serv", scope: "node-adapter" });
   const server = serve(
     {
       // 保留原 bindings 对象，WebSocket 升级状态由 Node adapter 在同一对象上共享。
@@ -1526,16 +1663,55 @@ function listen(app, options = {}) {
     },
     options.onListening
   );
+  let listenFailure;
+  const rememberListenFailure = (error) => {
+    listenFailure = error;
+    logger3.error("Service listener failed", { error });
+  };
+  server.on(errorMonitor, rememberListenFailure);
+  let closing;
+  let removeSignalListeners = () => {
+  };
   const handle = {
     server,
     address: { host, port },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error)
-          reject(error);
-        else resolve();
+    close: () => closing ??= (async () => {
+      removeSignalListeners();
+      const httpClosed = new Promise((resolve, reject) => {
+        server.close((error) => {
+          server.removeListener(errorMonitor, rememberListenFailure);
+          if (listenFailure) {
+            reject(listenFailure);
+            return;
+          }
+          if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING" && !server.listening))
+            reject(error);
+          else resolve();
+        });
       });
-    })
+      const audioClosed = new Promise((resolve, reject) => {
+        if (!audioServer) {
+          resolve();
+          return;
+        }
+        const deadline = setTimeout(() => {
+          for (const socket of audioServer.clients)
+            socket.terminate();
+        }, 1e3);
+        audioServer.close((error) => {
+          clearTimeout(deadline);
+          if (error)
+            reject(error);
+          else resolve();
+        });
+        for (const socket of audioServer.clients)
+          socket.close(1001, "Server shutting down");
+      });
+      const results = await Promise.allSettled([httpClosed, audioClosed]);
+      const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+      if (errors.length)
+        throw new AggregateError(errors, "Service listener shutdown failed");
+    })()
   };
   if (options.onClose) {
     const onClose = options.onClose;
@@ -1546,88 +1722,28 @@ function listen(app, options = {}) {
       shuttingDown = true;
       try {
         await handle.close();
-      } catch {
+      } catch (error) {
+        logger3.error("Service listener shutdown failed", { error });
       }
       try {
         await onClose();
-      } catch {
+      } catch (error) {
+        logger3.error("Service resource shutdown failed", { error });
       }
     };
-    process.once("SIGINT", () => void shutdown());
-    process.once("SIGTERM", () => void shutdown());
+    const onSignal = () => {
+      void shutdown();
+    };
+    process4.once("SIGINT", onSignal);
+    process4.once("SIGTERM", onSignal);
+    removeSignalListeners = () => {
+      process4.removeListener("SIGINT", onSignal);
+      process4.removeListener("SIGTERM", onSignal);
+    };
   }
   return handle;
 }
 
-// src/serv-runtime-security.ts
-function createRuntimeSecurityPolicy(input) {
-  const production = input.environment?.trim().toLowerCase() === "production";
-  const configuredOrigins = parseOrigins(input.corsOrigin);
-  const configuredNativeOrigins = parseNativeOrigins(input.nativeOrigins);
-  const allowsEveryOrigin = configuredOrigins === "*";
-  if (production && (allowsEveryOrigin || configuredOrigins.length === 0))
-    throw new Error("serv.cors.origin must contain explicit HTTP(S) origins in production");
-  const allowedOrigins = allowsEveryOrigin ? void 0 : new Set(configuredOrigins);
-  const allowedNativeOrigins = new Set(configuredNativeOrigins);
-  return {
-    allowOrigin: (origin) => {
-      const normalizedNativeOrigin = tryNormalizeNativeOrigin(origin);
-      if (normalizedNativeOrigin !== void 0 && allowedNativeOrigins.has(normalizedNativeOrigin))
-        return true;
-      if (allowedOrigins === void 0)
-        return true;
-      const normalizedWebOrigin = tryNormalizeWebOrigin(origin);
-      return normalizedWebOrigin !== void 0 && allowedOrigins.has(normalizedWebOrigin);
-    },
-    isNativeOrigin: (origin) => allowedNativeOrigins.has(tryNormalizeNativeOrigin(origin) ?? ""),
-    secureRefreshCookie: production,
-    exposeApiDocs: !production
-  };
-}
-function parseOrigins(value) {
-  const entries = (value ?? "*").split(",").map((origin) => origin.trim()).filter(Boolean);
-  if (entries.includes("*"))
-    return "*";
-  return entries.map(normalizeWebOrigin);
-}
-function parseNativeOrigins(value) {
-  return (value ?? "").split(",").map((origin) => origin.trim()).filter(Boolean).map(normalizeNativeOrigin);
-}
-function normalizeWebOrigin(value) {
-  const normalized = tryNormalizeWebOrigin(value);
-  if (normalized === void 0)
-    throw new Error(`serv.cors.origin contains an invalid origin: ${value}`);
-  return normalized;
-}
-function normalizeNativeOrigin(value) {
-  const normalized = tryNormalizeNativeOrigin(value);
-  if (normalized === void 0)
-    throw new Error(`serv.cors.nativeOrigins contains an invalid origin: ${value}`);
-  return normalized;
-}
-function tryNormalizeWebOrigin(value) {
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    return void 0;
-  }
-  if (!["http:", "https:"].includes(url.protocol) || url.origin === "null" || url.pathname !== "/" || url.search || url.hash)
-    return void 0;
-  return url.origin;
-}
-function tryNormalizeNativeOrigin(value) {
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    return void 0;
-  }
-  if (!["http:", "https:", "capacitor:", "tauri:"].includes(url.protocol) || !url.hostname || url.username || url.password || !["", "/"].includes(url.pathname) || url.search || url.hash)
-    return void 0;
-  return ["capacitor:", "tauri:"].includes(url.protocol) ? `${url.protocol}//${url.host}` : url.origin;
-}
-
 // src/serv-storage-assets.ts
 function storageAssets(config) {
   const pathPrefix = config.pathPrefix.endsWith("/") ? config.pathPrefix : `${config.pathPrefix}/`;