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

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
     : {
@@ -241,7 +249,7 @@ const updateProfile = p.users.update.handler(
 
 #### 1) 自定义 HTTP middleware
 
-当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑** 时，使用 `middlewares`。常见 CORS 场景可直接复用 `serv.cors(...)`：
+当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑**，或挂载不适合进入 JSON/oRPC contract 的 WebSocket、文件和二进制端点时，使用 `middlewares`。常见 CORS 场景可直接复用 `serv.cors(...)`：
 
 ```ts
 import type { ServMiddleware } from '@h-ai/serv'
@@ -274,6 +282,14 @@ const app = serv.createApp({
         await next()
       },
     },
+    {
+      path: '/assets/*',
+      // 路径级 middleware 可以终结请求；响应仍经过内置 securityHeaders。
+      middleware: c => c.body(imageBytes, 200, {
+        'Content-Type': 'image/png',
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      }),
+    },
   ],
 })
 ```
@@ -289,7 +305,9 @@ const app = serv.createApp({
 
 - `middlewares` 按数组顺序注册
 - `path` 省略时默认 `'*'`
-- 由于 `middlewares` 先于 `transport` 执行，CORS 这类 preflight middleware 可以直接短路；若需要读取解密后的业务 body，请改用 context / procedure 层扩展
+- 由于 `middlewares` 先于 `transport` 执行，CORS preflight 或二进制端点可以直接短路；短路响应仍带内置安全头，但不会经过 transport
+- 文件端点的允许方法、路径校验、MIME、缓存和访问授权由应用显式决定；框架不内置头像等业务概念
+- 若需要读取解密后的业务 body，请改用 context / procedure 层扩展
 - 浏览器若需读取自定义响应头（例如 transport 的 `X-Encrypted`），请通过 `serv.cors({ exposedHeaders: [...] })` 显式暴露
 - 这一层直接操作 HTTP middleware context，返回的是 **HTTP Response**，不是 `HaiResult`
 
@@ -484,6 +502,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 +531,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}`[];
@@ -313,10 +340,11 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
     /**
      * 自定义 HTTP middleware（当前内部由 Hono 承载，但应用 API 不暴露 Hono app）。
      *
-     * 典型用途：请求日志、trace、指标、CORS、限流、租户头校验等 HTTP 层横切逻辑。
+     * 典型用途：请求日志、trace、指标、CORS、限流、租户头校验，以及不适合放入
+     * JSON/oRPC contract 的 WebSocket、文件或其它二进制 HTTP 端点。
      * 这些 middleware 会在内置安全头之后、传输加密与业务路由之前注册；
-     * 因此 CORS 这类 preflight middleware 可以直接短路返回，若需要读取解密后的业务 body，
-     * 应改用 context / procedure 层扩展，而不是 HTTP middleware。
+     * 因此 CORS preflight 或二进制端点可以直接短路返回。短路响应仍包含内置安全头，
+     * 但不会经过 transport；若需要读取解密后的业务 body，应改用 context / procedure 层扩展。
      */
     readonly middlewares?: readonly ServMiddlewareMount[];
     /**
@@ -717,6 +745,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 +848,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 +862,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`）。