@h-ai/serv 0.1.0-alpha.42 → 0.1.0-alpha.43

package/README.md

@@ -156,6 +156,14 @@ const app = serv.createApp({
   contract,
   procedures,
   http: servConfig.http,
+  middlewares: [{
+    middleware: serv.cors({
+      origin: servConfig.cors.origin,
+      credentials: servConfig.cors.credentials,
+      allowedHeaders: [...servConfig.cors.allowedHeaders],
+      exposedHeaders: [...servConfig.cors.exposedHeaders],
+    }),
+  }],
   transport: servConfig.transport === false
     ? undefined
     : {
@@ -484,6 +492,17 @@ http:
     readyPath: /ready
   rpc: false
 
+cors:
+  origin: https://app.example.com
+  nativeOrigins: capacitor://app.example.local,tauri://app.example.local
+  credentials: true
+  allowedHeaders:
+    - Authorization
+    - Content-Type
+    - X-Client-Id
+  exposedHeaders:
+    - X-Encrypted
+
 transport:
   keyExchangePath: /_hai/key-exchange
   excludePaths:
@@ -502,8 +521,40 @@ transport:
 - `openapi`：默认 `false`；启用：`{ path: '/openapi.json' }`
 - `docs`：默认 `false`；启用：`{ path: '/docs' }`（依赖 `openapi`）；启用后自动挂载 `/_hai/scalar.js`，从 `@scalar/api-reference` 的 browser bundle 提供本地 Scalar UI 脚本，无需外网 CDN
 - `rpc`：默认 `false`；启用：`{ prefix: '/rpc', access: 'loopback' | 'private-network' | 'gateway-only', gatewayHeader?, gatewaySecret? }`
+- `cors`：配置文件中的跨端 origin、credentials、allowedHeaders 与 exposedHeaders；应用通过 `serv.cors(...)` 装配。
 - `transport`：`config/_serv.yml` 顶层配置；启用后可通过 `servConfig.transport` 装配到 `createApp({ transport })`，默认密钥协商子路径 `/_hai/key-exchange`
 
+生产环境应先通过 `serv.createRuntimeSecurityPolicy(...)` 收敛 CORS、Cookie 与文档暴露策略：
+
+```ts
+const security = serv.createRuntimeSecurityPolicy({
+  environment: coreConfig.env,
+  corsOrigin: servConfig.cors.origin,
+  nativeOrigins: servConfig.cors.nativeOrigins,
+})
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: {
+    ...servConfig.http,
+    openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+    docs: security.exposeApiDocs ? servConfig.http.docs : false,
+  },
+  refreshCookie: { secure: security.secureRefreshCookie },
+  middlewares: [{
+    middleware: serv.cors({
+      origin: security.allowOrigin,
+      credentials: servConfig.cors.credentials,
+      allowedHeaders: [...servConfig.cors.allowedHeaders],
+      exposedHeaders: [...servConfig.cors.exposedHeaders],
+    }),
+  }],
+})
+```
+
+生产环境下 `_serv.yml` 的 `cors.origin` 为空或为 `*` 会在启动时失败；Web 与 Capacitor/Tauri Origin 均按规范化后的完整 Origin 精确匹配，避免后缀伪造。生产环境同时强制 Secure refresh cookie 并关闭 OpenAPI/docs，配置文件仍决定非生产环境具体挂载哪些端点。
+
 ## 错误处理
 
 - Default procedures 全部返回 `HaiResult<T>`，客户端直接判断 `result.success`

package/dist/index.d.ts

@@ -115,6 +115,14 @@ interface ServTransportRuntimeConfig {
     readonly excludePaths: readonly `/${string}`[];
     readonly maxClients: number;
 }
+/** `config/_serv.yml` 中可序列化的跨端 CORS 配置。 */
+interface ServCorsRuntimeConfig {
+    readonly origin?: string;
+    readonly nativeOrigins?: string;
+    readonly allowedHeaders: readonly string[];
+    readonly exposedHeaders: readonly string[];
+    readonly credentials: boolean;
+}
 /** ServHttpApp 的 HTTP 挂载配置。 */
 interface ServHttpConfig {
     readonly apiPrefix: `/api/${string}`;
@@ -126,8 +134,11 @@ interface ServHttpConfig {
 /** `config/_serv.yml` 的顶层配置结构。 */
 interface ServConfig {
     readonly http: ServHttpConfig;
+    readonly cors: ServCorsRuntimeConfig;
     readonly transport: false | ServTransportRuntimeConfig;
 }
+/** `config/_serv.yml` 中的 CORS 输入类型。 */
+type ServCorsRuntimeConfigInput = Partial<ServCorsRuntimeConfig>;
 /** `config/_serv.yml` 中的传输加密输入类型。 */
 type ServTransportRuntimeConfigInput = Partial<{
     readonly keyExchangePath: `/${string}`;
@@ -145,6 +156,7 @@ type ServHttpConfigInput = Partial<{
 /** `config/_serv.yml` 的顶层输入类型。 */
 interface ServConfigInput {
     readonly http?: ServHttpConfigInput;
+    readonly cors?: ServCorsRuntimeConfigInput;
     readonly transport?: false | ServTransportRuntimeConfigInput;
 }
 /** `config/_serv.yml` 对应的配置 Schema。 */
@@ -173,6 +185,13 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             gatewaySecret: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>;
+    cors: z.ZodOptional<z.ZodObject<{
+        origin: z.ZodOptional<z.ZodString>;
+        nativeOrigins: z.ZodOptional<z.ZodString>;
+        allowedHeaders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exposedHeaders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        credentials: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     transport: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
         keyExchangePath: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         excludePaths: z.ZodDefault<z.ZodArray<z.ZodCustom<`/${string}`, `/${string}`>>>;
@@ -180,6 +199,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strip>]>>;
 }, z.core.$strip>, z.ZodTransform<{
     http: ServHttpConfig;
+    cors: ServCorsRuntimeConfig;
     transport: false | ServTransportRuntimeConfig;
 }, {
     http?: {
@@ -202,6 +222,13 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             gatewaySecret?: string | undefined;
         };
     } | undefined;
+    cors?: {
+        allowedHeaders: string[];
+        exposedHeaders: string[];
+        credentials: boolean;
+        origin?: string | undefined;
+        nativeOrigins?: string | undefined;
+    } | undefined;
     transport?: false | {
         keyExchangePath: `/${string}`;
         excludePaths: `/${string}`[];
@@ -717,6 +744,33 @@ interface GenerateOpenAPISpecOptions {
  */
 declare function generateSpec(contract: AnyContractRouter, options?: GenerateOpenAPISpecOptions): Promise<OpenAPI.Document>;
 
+/**
+ * @h-ai/serv — 部署环境 HTTP 安全策略
+ *
+ * 将环境与 CORS 配置收敛为 fail-closed 的运行时策略，避免每个业务应用重复实现
+ * Origin 解析、生产通配符保护、Cookie Secure 与 API 文档暴露规则。
+ * @module serv-runtime-security
+ */
+/** 运行时安全策略输入；通常来自 `_core.yml.env` 与 `_serv.yml.cors`。 */
+interface ServRuntimeSecurityPolicyInput {
+    readonly environment?: string;
+    readonly corsOrigin?: string;
+    readonly nativeOrigins?: string;
+}
+/** 可直接装配到 CORS、refresh cookie 与 HTTP 文档配置的安全策略。 */
+interface ServRuntimeSecurityPolicy {
+    readonly allowOrigin: (origin: string) => boolean;
+    readonly isNativeOrigin: (origin: string) => boolean;
+    readonly secureRefreshCookie: boolean;
+    readonly exposeApiDocs: boolean;
+}
+/**
+ * 创建部署环境安全策略。
+ *
+ * 生产环境必须显式配置 HTTP(S) Origin，禁止缺省或 `*`；开发环境保留通配符便利性。
+ */
+declare function createRuntimeSecurityPolicy(input: ServRuntimeSecurityPolicyInput): ServRuntimeSecurityPolicy;
+
 /**
  * @h-ai/serv — 校验工具
  *
@@ -793,6 +847,7 @@ declare const serv: {
     listen: typeof listen;
     toFetch: typeof toFetch;
     cors: typeof cors;
+    createRuntimeSecurityPolicy: typeof createRuntimeSecurityPolicy;
     generateSpec: typeof generateSpec;
     /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
     implement: typeof implement;
@@ -806,4 +861,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 AudioTicketGrant, type AudioTicketVerification, type AuthorizedAudioRequest, 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 };
+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 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, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, ServSession, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -3,7 +3,7 @@ import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody
 import { implement } from '@orpc/server';
 import process2 from 'process';
 import { serve } from '@hono/node-server';
-import { AUDIO_WS_PATH, IAM_AUTH_ROUTES, AudioWsClientMessageSchema } from '@h-ai/api-contract';
+import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { core, ok, err, HaiCommonError } from '@h-ai/core';
 import { createNodeWebSocket } from '@hono/node-ws';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
@@ -662,6 +662,13 @@ var TransportRuntimeConfigInputSchema = z.union([
     maxClients: z.number().int().positive().default(1e4)
   })
 ]);
+var CorsRuntimeConfigInputSchema = z.object({
+  origin: z.string().optional(),
+  nativeOrigins: z.string().optional(),
+  allowedHeaders: z.array(z.string()).default(["Authorization", "Content-Type", "X-Requested-With"]),
+  exposedHeaders: z.array(z.string()).default([]),
+  credentials: z.boolean().default(false)
+});
 var ServHttpConfigInputSchema = z.object({
   apiPrefix: ApiPrefixSchema.default("/api/v1"),
   openapi: OpenAPIHttpConfigInputSchema.default(false),
@@ -671,14 +678,19 @@ var ServHttpConfigInputSchema = z.object({
 });
 var ServConfigSchema = z.object({
   http: ServHttpConfigInputSchema.optional(),
+  cors: CorsRuntimeConfigInputSchema.optional(),
   transport: TransportRuntimeConfigInputSchema.optional()
-}).transform(({ http, transport }) => ({
+}).transform(({ http, cors: cors2, transport }) => ({
   http: resolveServHttpConfig(http ?? {}),
+  cors: resolveServCorsRuntimeConfig(cors2 ?? {}),
   transport: resolveServTransportRuntimeConfig(transport ?? false)
 }));
 function resolveServHttpConfig(input = {}) {
   return ServHttpConfigInputSchema.parse(input);
 }
+function resolveServCorsRuntimeConfig(input = {}) {
+  return CorsRuntimeConfigInputSchema.parse(input);
+}
 function resolveServTransportRuntimeConfig(input = false) {
   return TransportRuntimeConfigInputSchema.parse(input);
 }
@@ -727,6 +739,13 @@ function buildAuthContextFactory(verifyToken) {
     }
   };
 }
+var IAM_AUTH_PATHS = {
+  login: apiContract.pathOf(apiContract.iam.auth.login),
+  loginWithOtp: apiContract.pathOf(apiContract.iam.auth.loginWithOtp),
+  register: apiContract.pathOf(apiContract.iam.auth.register),
+  logout: apiContract.pathOf(apiContract.iam.auth.logout),
+  refresh: apiContract.pathOf(apiContract.iam.auth.refresh)
+};
 function resolveRefreshCookieConfig(apiPrefix, config, iam) {
   const onRefresh = config.onRefresh ?? (iam ? (refreshToken) => iam.session.refresh(refreshToken) : void 0);
   if (!onRefresh) {
@@ -739,7 +758,7 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
     cookieName: config.cookieName ?? "hai_refresh_token",
     maxAge: config.maxAge ?? 30 * 24 * 3600,
     isSecure: config.secure ?? process2.env.NODE_ENV === "production",
-    refreshCookiePath: `${apiPrefix}${IAM_AUTH_ROUTES.refresh}`,
+    refreshCookiePath: `${apiPrefix}${IAM_AUTH_PATHS.refresh}`,
     onRefresh
   };
 }
@@ -792,9 +811,9 @@ function stripRefreshTokenFromPair(tokens) {
 function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
   const { cookieName, maxAge, isSecure, refreshCookiePath, onRefresh } = resolveRefreshCookieConfig(apiPrefix, config, iam);
   const loginPaths = [
-    `${apiPrefix}${IAM_AUTH_ROUTES.login}`,
-    `${apiPrefix}${IAM_AUTH_ROUTES.loginWithOtp}`,
-    `${apiPrefix}${IAM_AUTH_ROUTES.register}`
+    `${apiPrefix}${IAM_AUTH_PATHS.login}`,
+    `${apiPrefix}${IAM_AUTH_PATHS.loginWithOtp}`,
+    `${apiPrefix}${IAM_AUTH_PATHS.register}`
   ];
   for (const path of loginPaths) {
     app.post(path, async (c, next) => {
@@ -819,7 +838,7 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
       c.res = new Response(responseBody, { status: c.res.status, statusText: c.res.statusText, headers });
     });
   }
-  app.post(`${apiPrefix}${IAM_AUTH_ROUTES.logout}`, async (c, next) => {
+  app.post(`${apiPrefix}${IAM_AUTH_PATHS.logout}`, async (c, next) => {
     await next();
     if (c.res.status !== 200)
       return;
@@ -833,7 +852,7 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
     }
     c.res = new Response(bodyText, { status: c.res.status, statusText: c.res.statusText, headers });
   });
-  app.post(`${apiPrefix}${IAM_AUTH_ROUTES.refresh}`, async (c) => {
+  app.post(`${apiPrefix}${IAM_AUTH_PATHS.refresh}`, async (c) => {
     const refreshToken = getCookie(c, cookieName);
     if (!refreshToken) {
       const locale = resolveRequestLocale(c.req.raw.headers);
@@ -1382,6 +1401,75 @@ function buildCorsHeaders(options) {
   return headers;
 }
 
+// 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-main.ts
 var serv = {
   // 应用与上下文
@@ -1393,6 +1481,7 @@ var serv = {
   listen,
   toFetch,
   cors,
+  createRuntimeSecurityPolicy,
   // OpenAPI / 导出
   generateSpec,
   // Procedure 装配（contract 路由定义统一使用 `apiContract.route`）。