@h-ai/serv 0.1.0-alpha.74 → 0.1.0-alpha.76

package/dist/index.d.ts

@@ -250,6 +250,8 @@ interface ServRpcHttpConfig {
 interface ServTransportRuntimeConfig {
     /** 双向明文 UTF-8 字节上限；省略使用 1 MiB，范围 1 KiB～64 MiB。 */
     readonly maxPlaintextBytes?: number;
+    /** 按完整路径段匹配的明文容量；* 匹配单段。 */
+    readonly routePlaintextBytes?: Readonly<Record<string, number>>;
     readonly keyExchangePath: `/${string}`;
     readonly excludePaths: readonly `/${string}`[];
 }
@@ -337,6 +339,7 @@ type ServCorsRuntimeConfigInput = Partial<ServCorsRuntimeConfig>;
  */
 type ServTransportRuntimeConfigInput = Partial<{
     readonly maxPlaintextBytes: number | 'auto';
+    readonly routePlaintextBytes: Readonly<Record<string, number>>;
     readonly keyExchangePath: `/${string}`;
     readonly excludePaths: readonly `/${string}`[];
 }>;
@@ -432,6 +435,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strip>>;
     transport: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
         maxPlaintextBytes: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>, z.ZodTransform<number | undefined, number | "auto">>>;
+        routePlaintextBytes: z.ZodOptional<z.ZodRecord<z.ZodCustom<`/${string}`, `/${string}`>, z.ZodNumber>>;
         keyExchangePath: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         excludePaths: z.ZodDefault<z.ZodArray<z.ZodCustom<`/${string}`, `/${string}`>>>;
     }, z.core.$strip>]>>;
@@ -477,27 +481,10 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         keyExchangePath: `/${string}`;
         excludePaths: `/${string}`[];
         maxPlaintextBytes?: number | undefined;
+        routePlaintextBytes?: Record<`/${string}`, number> | undefined;
     } | undefined;
 }>>;
 
-/**
- * @h-ai/serv — 传输加密集成
- *
- * 提供 Hono 中间件 + 密钥协商端点，直接依赖 `@h-ai/crypto` 的
- * `TransportEncryptionManager` 与 `TRANSPORT_PROTOCOL` 协议常量，
- * 确保前后端协议不漂移。
- *
- * 单次请求的处理顺序：
- * 1. 特判密钥协商端点
- * 2. 跳过不参与加解密的路径
- * 3. 校验 clientId 与已注册公钥
- * 4. 解密请求体并把明文 request 回写给下游
- * 5. 执行业务逻辑
- * 6. 尝试加密 JSON 响应
- *
- * @module serv-transport
- */
-
 /**
  * {@link createApp} 的 `transport` 配置项。
  *
@@ -518,6 +505,8 @@ interface ServTransportConfig {
     /** 受管服务端密钥环，仅运行时从私有 Secret 注入。 */
     /** 双向业务明文 UTF-8 字节上限；默认 1 MiB，整数范围 1 KiB～64 MiB。 */
     readonly maxPlaintextBytes?: number;
+    /** 路由明文容量；* 匹配一个完整路径段。 */
+    routePlaintextBytes?: Readonly<Record<string, number>>;
     readonly serverKeyRing: TransportServerKeyRing;
     /**
      * crypto 服务实例。serv 通过 `crypto.transport.createServer()` 创建
@@ -537,24 +526,6 @@ interface ServTransportConfig {
     readonly keyStore: TransportKeyStore;
 }
 
-/**
- * @h-ai/serv — HTTP app 装配
- *
- * 将 oRPC contract + procedures + http 配置组合为可运行的 ServHttpApp，
- * 自动挂载安全响应头、健康检查、OpenAPI JSON、Scalar 文档页与 oRPC handler。
- *
- * 关键装配顺序：
- * 1. 解析 HTTP 配置
- * 2. 选择请求上下文工厂
- * 3. 挂基础安全 middleware
- * 4. 挂自定义 middleware（若提供）
- * 5. （可选）挂传输加密 middleware
- * 6. 挂基础路由（health / refresh-cookie）
- * 7. 挂业务路由（oRPC / RPC）
- * 8. 挂文档路由（openapi / docs）
- * @module serv-app
- */
-
 /**
  * `serv.createApp()` 的自定义 middleware 挂载项。
  *
@@ -1325,7 +1296,7 @@ declare const serv: {
     validateInputOrFail: typeof validateInputOrFail;
     WILDCARD_PERMISSION: string;
     WILDCARD_ROLE: string;
-    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;
+    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" | "serv_transportBusy" | "serv_feedbackUnavailable", options?: _h_ai_core.MessageOptions) => string;
 };
 
 export { type AudioTicketGrant, type AudioTicketVerification, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, 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, ServRequestMetadata, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -1,17 +1,17 @@
-import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-IRZVJW4V.js';
-import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-N6IOKLQY.js';
+import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-65XNI7TH.js';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-JAQIEQJS.js';
 import process from 'process';
 import { upgradeWebSocket, serve } from '@hono/node-server';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { audit } from '@h-ai/audit';
 import { core, 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 { OpenAPIHandler } from '@orpc/openapi/fetch';
 import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { Buffer } from 'buffer';
 import { BlockList, isIP } from 'net';
-import { TRANSPORT_PLAINTEXT_RANGE, TRANSPORT_PROTOCOL, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
 import { z } from 'zod';
 import { getCookie } from 'hono/cookie';
 import { readFile } from 'fs/promises';
@@ -725,7 +725,8 @@ var RpcHttpConfigInputSchema = z.union([
 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("\u53CC\u5411\u660E\u6587\u4E0A\u9650\uFF1Bauto \u6309\u5DF2\u542F\u7528\u6A21\u5757\u63A8\u5BFC\uFF0C\u65E0\u6A21\u5757\u9700\u6C42\u65F6 1 MiB\uFF1B\u663E\u5F0F\u6574\u6570\u4E0D\u5F97\u5C0F\u4E8E\u6A21\u5757\u9700\u6C42").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" }),
+    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([])
   })
@@ -1062,7 +1063,7 @@ function readScalarBrowserEntry(packageInfo) {
 }
 var logger2 = core.logger.child({ module: "serv", scope: "transport" });
 var ENCRYPTABLE_RESPONSE_CONTENT_TYPES = ["application/json"];
-function createTransportMiddleware(manager, keyExchangePath, excludePaths = []) {
+function createTransportMiddleware(manager, keyExchangePath, excludePaths = [], policy = createTransportBodyPolicy(manager.bodyLimits.plaintextBytes)) {
   return async (c, next) => {
     const pathname = new URL(c.req.url).pathname;
     if (pathname === keyExchangePath && c.req.method === "POST")
@@ -1072,76 +1073,83 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [])
     const clientId = c.req.header(TRANSPORT_PROTOCOL.CLIENT_ID_HEADER);
     if (!clientId)
       return jsonError(servM("serv_transportClientIdRequired"), 400);
-    let requestContext;
+    const lease = policy.acquire(pathname);
+    if (!lease)
+      return jsonError(servM("serv_transportBusy"), 503);
     try {
-      const verified = await authenticateTransportRequest(manager, c.req.raw);
-      if (!verified.success) {
-        if (verified.error.cause instanceof TransportTimeError && verified.error.cause.context)
-          return createTransportErrorResponse(verified.error.cause, { manager, context: verified.error.cause.context });
-        return jsonError(servM("serv_transportDecryptFailed"), 400);
+      let requestContext;
+      try {
+        const verified = await authenticateTransportRequest(manager, c.req.raw, lease.limits);
+        if (!verified.success) {
+          if (verified.error.cause instanceof TransportTimeError && verified.error.cause.context)
+            return createTransportErrorResponse(verified.error.cause, { manager, context: verified.error.cause.context });
+          return jsonError(servM("serv_transportDecryptFailed"), 400);
+        }
+        requestContext = verified.data.context;
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+          replaceRequestBody(c, verified.data.plaintext);
+      } catch (error) {
+        if (error instanceof TransportBodyTooLargeError)
+          return createTransportErrorResponse(error);
+        return jsonError(servM("serv_transportInvalidPayload"), error instanceof RangeError ? 413 : 400);
       }
-      requestContext = verified.data.context;
-      if (c.req.method !== "GET" && c.req.method !== "HEAD")
-        replaceRequestBody(c, verified.data.plaintext);
-    } catch (error) {
-      if (error instanceof TransportBodyTooLargeError)
-        return createTransportErrorResponse(error);
-      return jsonError(servM("serv_transportInvalidPayload"), error instanceof RangeError ? 413 : 400);
-    }
-    await next();
-    const response = c.res;
-    if (!response)
-      return;
-    const contentType = response.headers.get("Content-Type") ?? "";
-    const bodyless = c.req.method === "HEAD" || isEmptyResponse(response);
-    if (bodyless)
-      void response.body?.cancel().catch(() => {
-      });
-    c.header("Content-Length", void 0);
-    c.header("Content-Encoding", void 0);
-    c.header(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, void 0);
-    c.header(TRANSPORT_PROTOCOL.ENVELOPE_HEADER, void 0);
-    if (!bodyless && !canEncryptResponseContentType(contentType)) {
-      void response.body?.cancel().catch(() => {
-      });
-      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
-      return;
-    }
-    let bodyText;
-    try {
-      bodyText = bodyless ? "" : await readTransportBody(response.body, {
-        maxBytes: manager.bodyLimits.plaintextBytes,
-        direction: "response",
-        signal: c.req.raw.signal
-      });
-    } catch (cause) {
-      if (cause instanceof TransportBodyTooLargeError) {
-        c.res = await createTransportErrorResponse(cause, { manager, context: requestContext });
+      await next();
+      const response = c.res;
+      if (!response)
+        return;
+      const contentType = response.headers.get("Content-Type") ?? "";
+      const bodyless = c.req.method === "HEAD" || isEmptyResponse(response);
+      if (bodyless)
+        void response.body?.cancel().catch(() => {
+        });
+      c.header("Content-Length", void 0);
+      c.header("Content-Encoding", void 0);
+      c.header(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, void 0);
+      c.header(TRANSPORT_PROTOCOL.ENVELOPE_HEADER, void 0);
+      if (!bodyless && !canEncryptResponseContentType(contentType)) {
+        void response.body?.cancel().catch(() => {
+        });
+        c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
         return;
       }
-      logger2.warn("Failed to read response body for encryption", { error: cause });
-      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
-      return;
-    }
-    const headers = new Headers(response.headers);
-    headers.delete(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER);
-    headers.delete("Content-Length");
-    headers.delete("Content-Encoding");
-    const encResult = await manager.encryptResponse(requestContext, bodyText, response.status);
-    if (!encResult.success) {
-      logger2.warn("Failed to encrypt response", { error: encResult.error });
-      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
-      return;
+      let bodyText;
+      try {
+        bodyText = bodyless ? "" : await readTransportBody(response.body, {
+          maxBytes: lease.limits.plaintextBytes,
+          direction: "response",
+          signal: c.req.raw.signal
+        });
+      } catch (cause) {
+        if (cause instanceof TransportBodyTooLargeError) {
+          c.res = await createTransportErrorResponse(cause, { manager, context: requestContext });
+          return;
+        }
+        logger2.warn("Failed to read response body for encryption", { error: cause });
+        c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+        return;
+      }
+      const headers = new Headers(response.headers);
+      headers.delete(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER);
+      headers.delete("Content-Length");
+      headers.delete("Content-Encoding");
+      const encResult = await manager.encryptResponse(requestContext, bodyText, response.status);
+      if (!encResult.success) {
+        logger2.warn("Failed to encrypt response", { error: encResult.error });
+        c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+        return;
+      }
+      headers.set("Content-Type", "application/json; charset=utf-8");
+      headers.set(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE);
+      if (bodyless)
+        headers.set(TRANSPORT_PROTOCOL.ENVELOPE_HEADER, JSON.stringify(encResult.data));
+      c.res = new Response(bodyless ? null : JSON.stringify(encResult.data), {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+      });
+    } finally {
+      lease.release();
     }
-    headers.set("Content-Type", "application/json; charset=utf-8");
-    headers.set(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE);
-    if (bodyless)
-      headers.set(TRANSPORT_PROTOCOL.ENVELOPE_HEADER, JSON.stringify(encResult.data));
-    c.res = new Response(bodyless ? null : JSON.stringify(encResult.data), {
-      status: response.status,
-      statusText: response.statusText,
-      headers
-    });
   };
 }
 async function handleKeyExchange(request, manager) {
@@ -1235,7 +1243,7 @@ function createApp(options) {
       userAgent: c.req.header("user-agent")?.slice(0, 4096)
     }, async () => {
       await next();
-      if (c.res.status >= 400) {
+      if (audit.isInitialized && c.res.status >= 400) {
         const trusted = requestAuditContexts.get(c.req.raw);
         const recorded = await audit.capture({
           action: "http.reject",
@@ -1275,10 +1283,11 @@ function createApp(options) {
   if (options.middlewares)
     mountCustomMiddlewares(app, options.middlewares);
   if (options.transport) {
+    const policy = createTransportBodyPolicy(options.transport.maxPlaintextBytes, options.transport.routePlaintextBytes);
     const mgr = options.transport.crypto.transport.createServer({
       serverKeyRing: options.transport.serverKeyRing,
       keyStore: options.transport.keyStore,
-      maxPlaintextBytes: options.transport.maxPlaintextBytes
+      maxPlaintextBytes: policy.maximum.plaintextBytes
     });
     if (!mgr.success) {
       throw core.error.buildHaiErrorInst(
@@ -1288,7 +1297,7 @@ function createApp(options) {
       );
     }
     const keyExchangePath = `${http.apiPrefix}${options.transport.keyExchangePath ?? "/_hai/key-exchange"}`;
-    app.use("*", createTransportMiddleware(mgr.data, keyExchangePath, options.transport.excludePaths));
+    app.use("*", createTransportMiddleware(mgr.data, keyExchangePath, options.transport.excludePaths, policy));
   }
   if (http.health !== false)
     mountHealthRoutes(app, http.health);