@h-ai/serv 0.1.0-alpha.15 → 0.1.0-alpha.18

package/README.md

@@ -1,10 +1,10 @@
 # @h-ai/serv
 
-> hai-framework 的 Hono + oRPC API 服务运行时，把 `@h-ai/api-contract` 的契约挂载为跨端可访问的 HTTP API。
+> hai-framework 的 API 服务运行时：对外暴露稳定的 HTTP App 抽象，把 `@h-ai/api-contract` 契约挂载为跨端可访问的 HTTP API；Hono 仅作为内部运行时实现。
 
 ## 能力概览
 
-- 一行启动：`serv.createApp(...)` → `serv.listen(app, { port })`
+- 一行启动：`serv.createApp(...)` → `serv.listen(app, { port })`，应用代码不需要 import Hono
 - 扁平 API（最小知识）：`serv.listen / serv.toFetch / serv.requireAuth / serv.requirePermission / serv.generateSpec / ...`
 - 自定义 pipeline：`createApp({ middlewares })` 挂 HTTP middleware；procedure wrapper 复用根入口导出的共享类型
 - 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
@@ -30,7 +30,7 @@ const procedures = {
   ai: createAiProcedures({ ai }),
 }
 
-// 3) 创建 app
+// 3) 创建 HTTP App
 const app = serv.createApp({
   contract,
   procedures,
@@ -203,16 +203,17 @@ const updateProfile = p.users.update.handler(
 
 `@h-ai/serv` 的“pipeline”分三层，分别对应三种扩展方式：
 
-1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 Hono middleware。
+1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 HTTP middleware。
 2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 定制请求上下文。
 3. **procedure wrapper 层**：通过 `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 组合认证、审计、租户校验等业务包装。
 
 #### 1) 自定义 HTTP middleware
 
-当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑** 时，使用 `middlewares`：
+当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑** 时，使用 `middlewares`。常见 CORS 场景可直接复用 `serv.cors(...)`：
 
 ```ts
 import type { ServMiddleware } from '@h-ai/serv'
+import { serv } from '@h-ai/serv'
 
 const requestMetrics: ServMiddleware = async (c, next) => {
   const startedAt = Date.now()
@@ -225,6 +226,13 @@ const app = serv.createApp({
   procedures,
   http: { apiPrefix: '/api/v1' },
   middlewares: [
+    {
+      middleware: serv.cors({
+        origin: origin => origin === 'https://app.example.com',
+        credentials: true,
+        exposedHeaders: ['X-Encrypted', 'X-Request-Id'],
+      }),
+    },
     { middleware: requestMetrics }, // 默认挂到 '*'
     {
       path: '/api/v1/*',
@@ -241,15 +249,17 @@ const app = serv.createApp({
 执行顺序固定为：
 
 1. 内置 `securityHeaders`
-2. 内置 `transport`（若启用）
-3. 你的 `middlewares`
+2. 你的 `middlewares`
+3. 内置 `transport`（若启用）
 4. health / refresh-cookie / OpenAPI / RPC / docs / oRPC routes
 
 说明：
 
 - `middlewares` 按数组顺序注册
 - `path` 省略时默认 `'*'`
-- 这一层直接操作 Hono `Context`，返回的是 **HTTP Response**，不是 `HaiResult`
+- 由于 `middlewares` 先于 `transport` 执行，CORS 这类 preflight middleware 可以直接短路；若需要读取解密后的业务 body，请改用 context / procedure 层扩展
+- 浏览器若需读取自定义响应头（例如 transport 的 `X-Encrypted`），请通过 `serv.cors({ exposedHeaders: [...] })` 显式暴露
+- 这一层直接操作 HTTP middleware context，返回的是 **HTTP Response**，不是 `HaiResult`
 
 #### 2) 自定义 context pipeline
 
@@ -375,7 +385,7 @@ await apiClient.init({
 
 ## API 概览
 
-- `serv.createApp(options)`：创建 Hono app，挂载自定义 `middlewares`、健康检查、OpenAPI handler、可选文档与 RPC
+- `serv.createApp(options)`：创建 HTTP App 抽象，挂载自定义 `middlewares`、健康检查、OpenAPI handler、可选文档与 RPC
 - `serv.parseRequestContext({ request })`：默认上下文解析（提取 Bearer token + requestId，不填充 session）
 - `serv.listen(app, options)`：在 Node.js 启动 HTTP 服务，返回 `{ server, address, close }`
 - `serv.toFetch(app)`：包装为标准 `fetch(Request)` handler
@@ -391,6 +401,7 @@ await apiClient.init({
 另有根级类型 / 命名导出：
 
 - `ServConfigSchema`：用于 `core.config.validate('serv', ServConfigSchema)` 校验 `config/_serv.yml`
+- HTTP App 抽象：`serv.createApp()` 返回具备 `fetch/request` 能力的公开应用对象；内部是否使用 Hono 不影响应用代码
 - `ServMiddlewareMount`：`createApp({ middlewares })` 的挂载项类型（`{ path?, middleware }`）
 - `ServMiddleware` / `ServProcedureWrapper` / `ServGuardedProcedureWrapper`：自定义 pipeline 时复用的共享类型
 

package/dist/index.d.ts

@@ -1,124 +1,14 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, ValidationFormError } from '@h-ai/core';
 import { Router, implement } from '@orpc/server';
-import { Hono, MiddlewareHandler } from 'hono';
-import { ServerType } from '@hono/node-server';
-import { AddressInfo } from 'node:net';
+import { AnyContractRouter, OpenAPI } from '@orpc/contract';
+import { MiddlewareHandler } from 'hono';
 import { S as ServContext, a as ServIam, R as RefreshCookieConfig, b as ServSession, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-CwewduFi.js';
 export { d as CreateServContextInput, e as RefreshTokenPair } from './serv-context-CwewduFi.js';
-import { AnyContractRouter, OpenAPI } from '@orpc/contract';
 import { z, ZodType } from 'zod';
 import { CryptoFunctions } from '@h-ai/crypto';
-
-/**
- * @h-ai/serv — Fetch 适配器
- *
- * 将 Hono app 包装为标准 Web `fetch(Request)` 处理函数，
- * 适用于 Cloudflare Workers、Deno、Bun 等 Fetch-first 运行时。
- * @module adapters/serv-adapter-fetch
- */
-
-/**
- * Fetch runtime handler。
- *
- * 兼容标准 Web `fetch` 签名 `(input, init)` —— 既可作为 Cloudflare Workers / Bun
- * 的 `fetch` 导出，也可作为 oRPC client `fetch` 选项的替代实现，让客户端在测试
- * 中直连 in-process 服务。
- */
-type ServFetchHandler = typeof fetch;
-/**
- * 将 Hono app 转成 Fetch handler。
- *
- * @param app - Hono app
- * @returns fetch-compatible handler
- *
- * @example
- * ```ts
- * // Cloudflare Workers
- * export default { fetch: serv.toFetch(app) }
- *
- * // Bun
- * Bun.serve({ fetch: serv.toFetch(app), port: 3000 })
- *
- * // 测试：把服务端 app 当作 fetch 注入到 client，免去 HTTP 监听
- * const client = apiClient.create(contract)
- * await client.init({ baseUrl: 'http://test', fetch: serv.toFetch(app) })
- * ```
- */
-declare function toFetch(app: Hono): ServFetchHandler;
-
-/**
- * @h-ai/serv — Node.js 适配器
- *
- * 封装 `@hono/node-server`，将 Hono app 以 Node.js HTTP 服务器形式启动。
- * 默认监听 `127.0.0.1`（仅本机可达）；如需对外暴露，需显式设置 `host: '0.0.0.0'` 或指定 IP。
- * @module adapters/serv-adapter-node
- */
-
-/** Node 服务器启动配置。 */
-interface ServListenOptions {
-    /**
-     * 监听端口。
-     * 优先级：显式值 > `PORT` 环境变量 > 默认 `3000`。
-     */
-    readonly port?: number;
-    /**
-     * 监听地址。
-     * 优先级：显式值 > `HOST` 环境变量 > 默认 `'127.0.0.1'`（仅本机可达）。
-     *
-     * - `'127.0.0.1'`：仅本机（推荐用于本地开发、容器内 sidecar、反向代理后端）
-     * - `'0.0.0.0'`：监听所有 IPv4 网卡（容器对外暴露、需公网/内网访问）
-     * - 指定 IP：仅监听该网卡（多网卡精确绑定）
-     */
-    readonly host?: string;
-    /** 服务启动就绪后的回调。 */
-    readonly onListening?: (info: AddressInfo) => void;
-    /**
-     * 优雅关闭回调（释放业务模块资源）。
-     *
-     * 传入后 `serv.listen` 自动监听 `SIGINT` / `SIGTERM`，按以下顺序关闭：
-     * 1. 停止接受新 HTTP 连接
-     * 2. 调用此回调释放业务资源
-     *
-     * 应用层无需手动注册 `process.once('SIGINT', ...)` 或维护 `shuttingDown` 标志。
-     */
-    readonly onClose?: () => Promise<void>;
-}
-/** Node 服务运行句柄。 */
-interface ServNodeServer {
-    /** 底层 Node.js HTTP Server 实例。 */
-    readonly server: ServerType;
-    /** 实际监听地址（host 与解析后的 port）。 */
-    readonly address: {
-        readonly host: string;
-        readonly port: number;
-    };
-    /** 优雅关闭服务器并等待已有连接断开。 */
-    readonly close: () => Promise<void>;
-}
-/**
- * 在 Node.js 中启动 Hono app。
- *
- * 默认监听 `127.0.0.1:3000`（可通过 `PORT` / `HOST` 环境变量覆盖）。
- * 传入 `onClose` 后自动注册 SIGINT/SIGTERM 优雅关闭，应用层无需手动处理信号。
- *
- * @param app - Hono app
- * @param options - 监听配置（port / host / onListening / onClose）
- * @returns 运行句柄
- *
- * @example
- * ```ts
- * // 最简：读取 PORT / HOST 环境变量，自动优雅关闭
- * serv.listen(app, {
- *   onListening: info => logger.info('listening', { port: info.port }),
- *   onClose: closeApp,
- * })
- *
- * // 容器对外暴露
- * serv.listen(app, { host: '0.0.0.0', onClose: closeApp })
- * ```
- */
-declare function listen(app: Hono, options?: ServListenOptions): ServNodeServer;
+import { ServerType } from '@hono/node-server';
+import { AddressInfo } from 'node:net';
 
 /**
  * @h-ai/serv — Pipeline 共享类型
@@ -149,99 +39,6 @@ type ServProcedureWrapper = <TInput, TOutput>(handler: ServProcedureHandler<TInp
 /** 带额外参数的 procedure 包装器（例如 `requirePermission('x', handler)`）。 */
 type ServGuardedProcedureWrapper<TRequirement> = <TInput, TOutput>(requirement: TRequirement, handler: ServProcedureHandler<TInput, TOutput>) => ServProcedureHandler<TInput, TOutput>;
 
-/**
- * @h-ai/serv — Pipeline 公共 helper
- *
- * 放置不属于 Hono middleware / oRPC wrapper 默认实现本身、
- * 但会被多个 pipeline 复用的公共工具。
- * @module pipelines/serv-pipeline-helper
- */
-
-/**
- * 捕获未处理异常并转换为 HaiResult。
- *
- * 虽然它不是 middleware / 鉴权 wrapper，但属于所有 procedure pipeline
- * 都可能复用的“公共包装能力”，因此与 `buildHaiErrorBody()` 一起放在 helper 中。
- *
- * @param handler - 被包装的 procedure handler
- * @returns 带异常保护的新 handler
- *
- * @example
- * ```ts
- * const safeHandler = serv.mapHaiError(myHandler)
- * ```
- */
-declare function mapHaiError<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requireAuth 默认实现
- * @module pipelines/serv-pipeline-require-auth
- */
-
-/**
- * 需要已验证会话的 procedure 包装器。
- *
- * `context.session` 由 `buildAuthContextFactory(verifyToken)`（或 `serv.createApp({ iam })` 自动启用）填充。
- * token 不存在或无效（verifyToken 失败）时 `session` 均为 `undefined`，统一返回 401 UNAUTHORIZED。
- * 内置调用 `mapHaiError`，无需外层再次封装。
- *
- * @param handler - 被包装的 procedure handler
- * @returns 带认证检查的新 handler
- *
- * @example
- * ```ts
- * const protectedHandler = serv.requireAuth(myHandler)
- * ```
- */
-declare function requireAuth<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requirePermission 默认实现
- * @module pipelines/serv-pipeline-require-permission
- */
-
-/**
- * 需要指定权限的 procedure 包装器。
- *
- * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.permissions`。
- * 拥有 {@link WILDCARD_PERMISSION}（`'*'`）的用户自动通过所有权限检查。
- *
- * @param permission - 所需权限字符串（如 `'iam.users.read'`）
- * @param handler - 被包装的 procedure handler
- * @returns 带权限检查的新 handler
- *
- * @example
- * ```ts
- * const adminHandler = serv.requirePermission('iam.users.write', myHandler)
- * ```
- */
-declare function requirePermission<TInput, TOutput>(permission: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requireRole 默认实现
- * @module pipelines/serv-pipeline-require-role
- */
-
-/**
- * 需要指定角色的 procedure 包装器。
- *
- * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.roles`。
- * 拥有 {@link WILDCARD_ROLE}（`'*'`）的用户自动通过所有角色检查。
- *
- * **使用建议**：优先使用 {@link requirePermission}（基于行为的细粒度授权）；
- * `requireRole` 适用于按角色分流的粗粒度路由（如 `'admin'` 专属入口）。
- *
- * @param role - 所需角色字符串（如 `'admin'`）
- * @param handler - 被包装的 procedure handler
- * @returns 带角色检查的新 handler
- *
- * @example
- * ```ts
- * const adminOnly = serv.requireRole('admin', myHandler)
- * ```
- */
-declare function requireRole<TInput, TOutput>(role: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
 /**
  * @h-ai/serv — HTTP 配置
  *
@@ -277,7 +74,7 @@ interface ServTransportRuntimeConfig {
     readonly excludePaths: readonly `/${string}`[];
     readonly maxClients: number;
 }
-/** Hono app 的 HTTP 挂载配置。 */
+/** ServHttpApp 的 HTTP 挂载配置。 */
 interface ServHttpConfig {
     readonly apiPrefix: `/api/${string}`;
     readonly openapi: false | ServOpenAPIHttpConfig;
@@ -410,17 +207,17 @@ interface ServTransportConfig {
 }
 
 /**
- * @h-ai/serv — Hono app 装配
+ * @h-ai/serv — HTTP app 装配
  *
- * 将 oRPC contract + procedures + http 配置组合为可运行的 Hono app，
+ * 将 oRPC contract + procedures + http 配置组合为可运行的 ServHttpApp，
  * 自动挂载安全响应头、健康检查、OpenAPI JSON、Scalar 文档页与 oRPC handler。
  *
  * 关键装配顺序：
  * 1. 解析 HTTP 配置
  * 2. 选择请求上下文工厂
  * 3. 挂基础安全 middleware
- * 4. （可选）挂传输加密 middleware
- * 5. 挂自定义 middleware（若提供）
+ * 4. 挂自定义 middleware（若提供）
+ * 5. （可选）挂传输加密 middleware
  * 6. 挂基础路由（health / refresh-cookie）
  * 7. 挂业务路由（oRPC / RPC）
  * 8. 挂文档路由（openapi / docs）
@@ -432,14 +229,25 @@ interface ServTransportConfig {
  *
  * - `path` 省略时默认挂到 `'*'`
  * - 按数组顺序注册
- * - 注册位置固定在内置 `securityHeaders` / `transport` 之后、业务路由之前
+ * - 注册位置固定在内置 `securityHeaders` 之后、`transport` / 业务路由之前
  */
 interface ServMiddlewareMount {
     readonly path?: string;
     readonly middleware: ServMiddleware;
 }
 /**
- * 创建 Hono app 的配置。
+ * `@h-ai/serv` 对外暴露的 HTTP app 抽象。
+ *
+ * Hono 是当前内部实现细节，应用代码只应依赖此最小接口：
+ * - `fetch`：部署到 Fetch-first 运行时或交给 `serv.listen()`。
+ * - `request`：测试 / 本地直连时发起 in-process 请求，避免消费方 import Hono。
+ */
+interface ServHttpApp {
+    readonly fetch: (request: Request) => Response | Promise<Response>;
+    readonly request: (input: RequestInfo | URL, init?: RequestInit) => Response | Promise<Response>;
+}
+/**
+ * 创建 ServHttpApp 的配置。
  *
  * **认证 / 会话填充设计**（遵循最小知识原则）：
  *
@@ -460,10 +268,12 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
     readonly procedures: TProcedures;
     readonly http?: ServHttpConfigInput;
     /**
-     * 自定义 Hono middleware。
+     * 自定义 HTTP middleware（当前内部由 Hono 承载，但应用 API 不暴露 Hono app）。
      *
      * 典型用途：请求日志、trace、指标、CORS、限流、租户头校验等 HTTP 层横切逻辑。
-     * 这些 middleware 会在内置安全头 / 传输加密之后、health/oRPC/OpenAPI/docs 路由之前注册。
+     * 这些 middleware 会在内置安全头之后、传输加密与业务路由之前注册；
+     * 因此 CORS 这类 preflight middleware 可以直接短路返回，若需要读取解密后的业务 body，
+     * 应改用 context / procedure 层扩展，而不是 HTTP middleware。
      */
     readonly middlewares?: readonly ServMiddlewareMount[];
     /**
@@ -501,10 +311,10 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
     readonly transport?: ServTransportConfig;
 }
 /**
- * 创建并装配 Hono API app。
+ * 创建并装配 HTTP API app。
  *
  * @param options - contract/procedures/http 三段式配置
- * @returns Hono app
+ * @returns 可被 `serv.listen()` / `serv.toFetch()` 使用的 ServHttpApp
  *
  * @example
  * ```ts
@@ -520,7 +330,235 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
  * serv.listen(app, { port: 3000, host: '0.0.0.0' })
  * ```
  */
-declare function createApp<TContract extends AnyContractRouter, TProcedures extends Router<AnyContractRouter, ServContext>>(options: CreateServAppOptions<TContract, TProcedures>): Hono;
+declare function createApp<TContract extends AnyContractRouter, TProcedures extends Router<AnyContractRouter, ServContext>>(options: CreateServAppOptions<TContract, TProcedures>): ServHttpApp;
+
+/**
+ * @h-ai/serv — Fetch 适配器
+ *
+ * 将 ServHttpApp 包装为标准 Web `fetch(Request)` 处理函数，
+ * 适用于 Cloudflare Workers、Deno、Bun 等 Fetch-first 运行时。
+ * @module adapters/serv-adapter-fetch
+ */
+
+/**
+ * Fetch runtime handler。
+ *
+ * 兼容标准 Web `fetch` 签名 `(input, init)` —— 既可作为 Cloudflare Workers / Bun
+ * 的 `fetch` 导出，也可作为 oRPC client `fetch` 选项的替代实现，让客户端在测试
+ * 中直连 in-process 服务。
+ */
+type ServFetchHandler = typeof fetch;
+/**
+ * 将 ServHttpApp 转成 Fetch handler。
+ *
+ * @param app - `serv.createApp()` 返回的 HTTP app
+ * @returns fetch-compatible handler
+ *
+ * @example
+ * ```ts
+ * // Cloudflare Workers
+ * export default { fetch: serv.toFetch(app) }
+ *
+ * // Bun
+ * Bun.serve({ fetch: serv.toFetch(app), port: 3000 })
+ *
+ * // 测试：把服务端 app 当作 fetch 注入到 client，免去 HTTP 监听
+ * const client = apiClient.create(contract)
+ * await client.init({ baseUrl: 'http://test', fetch: serv.toFetch(app) })
+ * ```
+ */
+declare function toFetch(app: ServHttpApp): ServFetchHandler;
+
+/**
+ * @h-ai/serv — Node.js 适配器
+ *
+ * 封装 `@hono/node-server`，将 ServHttpApp 以 Node.js HTTP 服务器形式启动。
+ * 默认监听 `127.0.0.1`（仅本机可达）；如需对外暴露，需显式设置 `host: '0.0.0.0'` 或指定 IP。
+ * @module adapters/serv-adapter-node
+ */
+
+/** Node 服务器启动配置。 */
+interface ServListenOptions {
+    /**
+     * 监听端口。
+     * 优先级：显式值 > `PORT` 环境变量 > 默认 `3000`。
+     */
+    readonly port?: number;
+    /**
+     * 监听地址。
+     * 优先级：显式值 > `HOST` 环境变量 > 默认 `'127.0.0.1'`（仅本机可达）。
+     *
+     * - `'127.0.0.1'`：仅本机（推荐用于本地开发、容器内 sidecar、反向代理后端）
+     * - `'0.0.0.0'`：监听所有 IPv4 网卡（容器对外暴露、需公网/内网访问）
+     * - 指定 IP：仅监听该网卡（多网卡精确绑定）
+     */
+    readonly host?: string;
+    /** 服务启动就绪后的回调。 */
+    readonly onListening?: (info: AddressInfo) => void;
+    /**
+     * 优雅关闭回调（释放业务模块资源）。
+     *
+     * 传入后 `serv.listen` 自动监听 `SIGINT` / `SIGTERM`，按以下顺序关闭：
+     * 1. 停止接受新 HTTP 连接
+     * 2. 调用此回调释放业务资源
+     *
+     * 应用层无需手动注册 `process.once('SIGINT', ...)` 或维护 `shuttingDown` 标志。
+     */
+    readonly onClose?: () => Promise<void>;
+}
+/** Node 服务运行句柄。 */
+interface ServNodeServer {
+    /** 底层 Node.js HTTP Server 实例。 */
+    readonly server: ServerType;
+    /** 实际监听地址（host 与解析后的 port）。 */
+    readonly address: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** 优雅关闭服务器并等待已有连接断开。 */
+    readonly close: () => Promise<void>;
+}
+/**
+ * 在 Node.js 中启动 ServHttpApp。
+ *
+ * 默认监听 `127.0.0.1:3000`（可通过 `PORT` / `HOST` 环境变量覆盖）。
+ * 传入 `onClose` 后自动注册 SIGINT/SIGTERM 优雅关闭，应用层无需手动处理信号。
+ *
+ * @param app - `serv.createApp()` 返回的 HTTP app
+ * @param options - 监听配置（port / host / onListening / onClose）
+ * @returns 运行句柄
+ *
+ * @example
+ * ```ts
+ * // 最简：读取 PORT / HOST 环境变量，自动优雅关闭
+ * serv.listen(app, {
+ *   onListening: info => logger.info('listening', { port: info.port }),
+ *   onClose: closeApp,
+ * })
+ *
+ * // 容器对外暴露
+ * serv.listen(app, { host: '0.0.0.0', onClose: closeApp })
+ * ```
+ */
+declare function listen(app: ServHttpApp, options?: ServListenOptions): ServNodeServer;
+
+/**
+ * @h-ai/serv — Pipeline 公共 helper
+ *
+ * 放置不属于 Hono middleware / oRPC wrapper 默认实现本身、
+ * 但会被多个 pipeline 复用的公共工具。
+ * @module pipelines/serv-pipeline-helper
+ */
+
+/**
+ * 捕获未处理异常并转换为 HaiResult。
+ *
+ * 虽然它不是 middleware / 鉴权 wrapper，但属于所有 procedure pipeline
+ * 都可能复用的“公共包装能力”，因此与 `buildHaiErrorBody()` 一起放在 helper 中。
+ *
+ * @param handler - 被包装的 procedure handler
+ * @returns 带异常保护的新 handler
+ *
+ * @example
+ * ```ts
+ * const safeHandler = serv.mapHaiError(myHandler)
+ * ```
+ */
+declare function mapHaiError<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
+
+/**
+ * @h-ai/serv — requireAuth 默认实现
+ * @module pipelines/serv-pipeline-require-auth
+ */
+
+/**
+ * 需要已验证会话的 procedure 包装器。
+ *
+ * `context.session` 由 `buildAuthContextFactory(verifyToken)`（或 `serv.createApp({ iam })` 自动启用）填充。
+ * token 不存在或无效（verifyToken 失败）时 `session` 均为 `undefined`，统一返回 401 UNAUTHORIZED。
+ * 内置调用 `mapHaiError`，无需外层再次封装。
+ *
+ * @param handler - 被包装的 procedure handler
+ * @returns 带认证检查的新 handler
+ *
+ * @example
+ * ```ts
+ * const protectedHandler = serv.requireAuth(myHandler)
+ * ```
+ */
+declare function requireAuth<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
+
+/**
+ * @h-ai/serv — requirePermission 默认实现
+ * @module pipelines/serv-pipeline-require-permission
+ */
+
+/**
+ * 需要指定权限的 procedure 包装器。
+ *
+ * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.permissions`。
+ * 拥有 {@link WILDCARD_PERMISSION}（`'*'`）的用户自动通过所有权限检查。
+ *
+ * @param permission - 所需权限字符串（如 `'iam.users.read'`）
+ * @param handler - 被包装的 procedure handler
+ * @returns 带权限检查的新 handler
+ *
+ * @example
+ * ```ts
+ * const adminHandler = serv.requirePermission('iam.users.write', myHandler)
+ * ```
+ */
+declare function requirePermission<TInput, TOutput>(permission: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
+
+/**
+ * @h-ai/serv — requireRole 默认实现
+ * @module pipelines/serv-pipeline-require-role
+ */
+
+/**
+ * 需要指定角色的 procedure 包装器。
+ *
+ * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.roles`。
+ * 拥有 {@link WILDCARD_ROLE}（`'*'`）的用户自动通过所有角色检查。
+ *
+ * **使用建议**：优先使用 {@link requirePermission}（基于行为的细粒度授权）；
+ * `requireRole` 适用于按角色分流的粗粒度路由（如 `'admin'` 专属入口）。
+ *
+ * @param role - 所需角色字符串（如 `'admin'`）
+ * @param handler - 被包装的 procedure handler
+ * @returns 带角色检查的新 handler
+ *
+ * @example
+ * ```ts
+ * const adminOnly = serv.requireRole('admin', myHandler)
+ * ```
+ */
+declare function requireRole<TInput, TOutput>(role: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
+
+/**
+ * @h-ai/serv — CORS middleware
+ *
+ * 统一处理 OPTIONS 预检与常规响应的 CORS 头注入，让应用层只保留 origin 白名单策略。
+ * @module serv-cors
+ */
+
+/** serv CORS 配置。 */
+interface ServCorsConfig {
+    /** 允许的 origin：`'*'`、单个字符串、数组或自定义匹配函数。默认 `'*'`。 */
+    readonly origin?: '*' | string | readonly string[] | ((origin: string) => boolean);
+    /** 允许的方法。默认 `GET/HEAD/PUT/PATCH/POST/DELETE/OPTIONS`。 */
+    readonly methods?: readonly string[];
+    /** 允许的请求头；若预检请求带 `Access-Control-Request-Headers`，优先回显该值。 */
+    readonly allowedHeaders?: readonly string[];
+    /** 暴露给浏览器 JS 的响应头。 */
+    readonly exposedHeaders?: readonly string[];
+    /** 是否允许携带 credentials（cookie / Authorization）。默认 `false`。 */
+    readonly credentials?: boolean;
+    /** 预检缓存秒数。默认 `86400`。 */
+    readonly maxAge?: number;
+}
+/** 创建可复用的 CORS middleware。 */
+declare function cors(config?: ServCorsConfig): ServMiddleware;
 
 /**
  * @h-ai/serv — OpenAPI 文档
@@ -630,6 +668,7 @@ declare const serv: {
     resolveRequestLocale: typeof resolveRequestLocale;
     listen: typeof listen;
     toFetch: typeof toFetch;
+    cors: typeof cors;
     generateSpec: typeof generateSpec;
     /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
     implement: typeof implement;
@@ -643,4 +682,4 @@ declare const serv: {
     m: (key: "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationStringMin" | "serv_validationStringMax" | "serv_validationNumberMin" | "serv_validationNumberMax" | "serv_validationArrayMin" | "serv_validationArrayMax" | "serv_validationTooSmall" | "serv_validationTooBig" | "serv_validationEmail" | "serv_validationUrl" | "serv_validationUuid" | "serv_validationEnum" | "serv_errorUnauthorized" | "serv_errorForbidden" | "serv_errorInternal" | "serv_storageKeyRequired" | "serv_storageKeyTooLong" | "serv_storageKeyIllegalChars" | "serv_storageKeyDotSegments" | "serv_iamCannotDeleteCurrentUser" | "serv_transportInvalidPayload" | "serv_transportUnknownClient" | "serv_transportClientIdRequired" | "serv_transportClientKeyNotFound" | "serv_transportDecryptFailed" | "serv_transportEncryptFailed" | "serv_transportKeyExchangeFailed", options?: _h_ai_core.MessageOptions) => string;
 };
 
-export { type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServDocsHttpConfig, type ServFetchHandler, type ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, ServSession, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+export { type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type 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 };