@h-ai/serv 0.1.0-alpha.15

package/dist/index.d.ts

@@ -0,0 +1,646 @@
+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 { 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;
+
+/**
+ * @h-ai/serv — Pipeline 共享类型
+ *
+ * 统一定义 Hono middleware 与 oRPC procedure wrapper 的最小公共类型，
+ * 供默认实现与使用方自定义实现复用。
+ * @module pipelines/serv-pipeline-types
+ */
+
+/** Serv 层 Hono middleware。 */
+type ServMiddleware = MiddlewareHandler;
+/**
+ * Hono middleware 工厂类型。
+ *
+ * - 无配置 middleware：`ServMiddlewareFactory<void>`
+ * - 带配置 middleware：`ServMiddlewareFactory<MyConfig>`
+ */
+type ServMiddlewareFactory<TConfig = void> = [TConfig] extends [void] ? () => ServMiddleware : (config: TConfig) => ServMiddleware;
+/** oRPC procedure handler 的最小上下文约束。 */
+interface ServProcedureOptions<TInput = unknown> {
+    readonly input: TInput;
+    readonly context: ServContext;
+}
+/** oRPC procedure handler。 */
+type ServProcedureHandler<TInput, TOutput> = (options: ServProcedureOptions<TInput>) => HaiResult<TOutput> | Promise<HaiResult<TOutput>>;
+/** 单参数 procedure 包装器（例如 `mapHaiError`、`requireAuth`）。 */
+type ServProcedureWrapper = <TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>) => ServProcedureHandler<TInput, TOutput>;
+/** 带额外参数的 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 配置
+ *
+ * 提供用于控制 API 前缀、OpenAPI、docs、健康检查、内部 RPC 与传输加密策略的配置结构，
+ * 并由 zod 负责默认值填充与边界校验。
+ * @module serv-config
+ */
+
+/** OpenAPI JSON endpoint 配置。 */
+interface ServOpenAPIHttpConfig {
+    readonly path: `/${string}`;
+}
+/** 文档页面 endpoint 配置。 */
+interface ServDocsHttpConfig {
+    readonly path: `/${string}`;
+    readonly requireAuth?: boolean;
+}
+/** 健康检查 endpoint 配置。 */
+interface ServHealthHttpConfig {
+    readonly path: `/${string}`;
+    readonly readyPath?: `/${string}`;
+}
+/** 内部 RPC endpoint 配置。 */
+interface ServRpcHttpConfig {
+    readonly prefix: `/${string}`;
+    readonly access: 'loopback' | 'private-network' | 'gateway-only';
+    readonly gatewayHeader?: string;
+    readonly gatewaySecret?: string;
+}
+/** 传输加密运行时配置（对应 `config/_serv.yml`）。 */
+interface ServTransportRuntimeConfig {
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+    readonly maxClients: number;
+}
+/** Hono app 的 HTTP 挂载配置。 */
+interface ServHttpConfig {
+    readonly apiPrefix: `/api/${string}`;
+    readonly openapi: false | ServOpenAPIHttpConfig;
+    readonly docs: false | ServDocsHttpConfig;
+    readonly health: false | ServHealthHttpConfig;
+    readonly rpc: false | ServRpcHttpConfig;
+}
+/** `config/_serv.yml` 的顶层配置结构。 */
+interface ServConfig {
+    readonly http: ServHttpConfig;
+    readonly transport: false | ServTransportRuntimeConfig;
+}
+/** `config/_serv.yml` 中的传输加密输入类型。 */
+type ServTransportRuntimeConfigInput = Partial<{
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+    readonly maxClients: number;
+}>;
+/** `serv.createApp` 接受的 HTTP 配置入参类型。 */
+type ServHttpConfigInput = Partial<{
+    readonly apiPrefix: `/api/${string}`;
+    readonly openapi: false | Partial<ServOpenAPIHttpConfig>;
+    readonly docs: false | Partial<ServDocsHttpConfig>;
+    readonly health: false | Partial<ServHealthHttpConfig>;
+    readonly rpc: false | Partial<ServRpcHttpConfig>;
+}>;
+/** `config/_serv.yml` 的顶层输入类型。 */
+interface ServConfigInput {
+    readonly http?: ServHttpConfigInput;
+    readonly transport?: false | ServTransportRuntimeConfigInput;
+}
+/** `config/_serv.yml` 对应的配置 Schema。 */
+declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
+    http: z.ZodOptional<z.ZodObject<{
+        apiPrefix: z.ZodDefault<z.ZodCustom<`/api/${string}`, `/api/${string}`>>;
+        openapi: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
+        }, z.core.$strip>]>>;
+        docs: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
+            requireAuth: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>]>>;
+        health: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
+            readyPath: z.ZodDefault<z.ZodOptional<z.ZodCustom<`/${string}`, `/${string}`>>>;
+        }, z.core.$strip>]>>;
+        rpc: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            prefix: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
+            access: z.ZodDefault<z.ZodEnum<{
+                loopback: "loopback";
+                "private-network": "private-network";
+                "gateway-only": "gateway-only";
+            }>>;
+            gatewayHeader: z.ZodOptional<z.ZodString>;
+            gatewaySecret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+    }, 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}`>>>;
+        maxClients: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodTransform<{
+    http: ServHttpConfig;
+    transport: false | ServTransportRuntimeConfig;
+}, {
+    http?: {
+        apiPrefix: `/api/${string}`;
+        openapi: false | {
+            path: `/${string}`;
+        };
+        docs: false | {
+            path: `/${string}`;
+            requireAuth?: boolean | undefined;
+        };
+        health: false | {
+            path: `/${string}`;
+            readyPath: `/${string}`;
+        };
+        rpc: false | {
+            prefix: `/${string}`;
+            access: "loopback" | "private-network" | "gateway-only";
+            gatewayHeader?: string | undefined;
+            gatewaySecret?: string | undefined;
+        };
+    } | undefined;
+    transport?: false | {
+        keyExchangePath: `/${string}`;
+        excludePaths: `/${string}`[];
+        maxClients: number;
+    } | 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` 配置项。 */
+interface ServTransportConfig {
+    /**
+     * crypto 服务实例。serv 通过 `crypto.transport.createServer()` 创建
+     * 传输加密管理器，并使用 `crypto.transport.protocol` 中的协议常量。
+     */
+    readonly crypto: CryptoFunctions;
+    /**
+     * 密钥协商端点路径（相对于 `apiPrefix`）。默认 `/_hai/key-exchange`。
+     */
+    readonly keyExchangePath?: string;
+    /**
+     * 不参与加解密的路径白名单（绝对路径完整匹配或前缀匹配）。
+     * 健康检查、文档页等公共路由通常无需加密。
+     */
+    readonly excludePaths?: readonly string[];
+    /** 服务端可缓存的客户端公钥数量上限。默认 10000。 */
+    readonly maxClients?: number;
+}
+
+/**
+ * @h-ai/serv — Hono app 装配
+ *
+ * 将 oRPC contract + procedures + http 配置组合为可运行的 Hono app，
+ * 自动挂载安全响应头、健康检查、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 挂载项。
+ *
+ * - `path` 省略时默认挂到 `'*'`
+ * - 按数组顺序注册
+ * - 注册位置固定在内置 `securityHeaders` / `transport` 之后、业务路由之前
+ */
+interface ServMiddlewareMount {
+    readonly path?: string;
+    readonly middleware: ServMiddleware;
+}
+/**
+ * 创建 Hono app 的配置。
+ *
+ * **认证 / 会话填充设计**（遵循最小知识原则）：
+ *
+ * - **`iam`**（推荐）：单一顶层引用。提供后 serv 自动：
+ *   1. 使用 `iam.session.verifyToken` 填充 `context.session` → `requireAuth/Permission/Role` 生效
+ *   2. 若同时启用 `refreshCookie`，使用 `iam.session.refresh` 实现 cookie 刷新
+ *
+ * - **`refreshCookie`**（可选）：opt-in httpOnly cookie 传输 refresh token。与 `iam` 正交：
+ *   `iam` 决定 *谁* 验证 token，`refreshCookie` 决定 refresh token *怎么* 传输。
+ *
+ * - **`verifyToken`**（高级）：不使用 IAM 模块的逆脱口。优先于 `iam.session.verifyToken`。
+ *
+ * - **`createContext`**（高级）：完全接管上下文构造，设置后 serv **不再**自动填充 session，
+ *   由调用方负责。
+ */
+interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures extends Router<AnyContractRouter, ServContext>> {
+    readonly contract: TContract;
+    readonly procedures: TProcedures;
+    readonly http?: ServHttpConfigInput;
+    /**
+     * 自定义 Hono middleware。
+     *
+     * 典型用途：请求日志、trace、指标、CORS、限流、租户头校验等 HTTP 层横切逻辑。
+     * 这些 middleware 会在内置安全头 / 传输加密之后、health/oRPC/OpenAPI/docs 路由之前注册。
+     */
+    readonly middlewares?: readonly ServMiddlewareMount[];
+    /**
+     * IAM 模块引用（推荐）。提供后 serv 自动使用 `iam.session.verifyToken` 填充 session，
+     * 以及在 `refreshCookie` 启用时使用 `iam.session.refresh` 实现 cookie 刷新。
+     *
+     * 类型上要求 {@link ServIam}（`iam` 可以直接传入，结构类型保证兼容）。
+     */
+    readonly iam?: ServIam;
+    /**
+     * 启用 httpOnly Cookie 传输 refresh token（opt-in）。
+     * 需配合 `iam` 或 `refreshCookie.onRefresh` 使用。
+     */
+    readonly refreshCookie?: RefreshCookieConfig;
+    /**
+     * 高级：自定义访问令牌校验回调，覆盖 `iam.session.verifyToken`。
+     * 不使用 IAM 模块的场景下使用。
+     */
+    readonly verifyToken?: (token: string) => Promise<HaiResult<ServSession>>;
+    /**
+     * 高级：完全接管上下文工厂。设置后上述 `iam` / `verifyToken` 均不生效（session 不会被自动填充）。
+     */
+    readonly createContext?: CreateServContext;
+    /**
+     * 启用传输加密（opt-in）。提供后 serv 自动：
+     * 1. 调用 `crypto.transport.createServer()` 创建管理器
+     * 2. 在 oRPC 路由之前挂载中间件，自动解密请求 / 加密响应
+     * 3. 在 `${apiPrefix}${keyExchangePath}` 暴露 POST 密钥协商端点
+     *
+     * @example
+     * ```ts
+     * serv.createApp({ contract, procedures, transport: { crypto } })
+     * ```
+     */
+    readonly transport?: ServTransportConfig;
+}
+/**
+ * 创建并装配 Hono API app。
+ *
+ * @param options - contract/procedures/http 三段式配置
+ * @returns Hono app
+ *
+ * @example
+ * ```ts
+ * const app = serv.createApp({
+ *   contract,
+ *   procedures,
+ *   http: {
+ *     apiPrefix: '/api/v1',
+ *     openapi: { path: '/openapi.json' },
+ *     docs: { path: '/docs' },
+ *   },
+ * })
+ * 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;
+
+/**
+ * @h-ai/serv — OpenAPI 文档
+ *
+ * 由 oRPC contract 生成 OpenAPI 3.1 spec，并集中处理 Scalar 文档页 HTML
+ * 与本地脚本资源读取逻辑。
+ * @module serv-openapi
+ */
+
+/** OpenAPI spec 生成配置。 */
+interface GenerateOpenAPISpecOptions {
+    readonly title?: string;
+    readonly version?: string;
+    readonly apiPrefix?: string;
+    readonly description?: string;
+}
+/**
+ * 由应用级 contract 生成 OpenAPI 3.1 spec。
+ *
+ * @param contract - 已组合完成的应用级 oRPC contract
+ * @param options - 文档元信息
+ * @returns OpenAPI 文档对象
+ *
+ * @example
+ * ```ts
+ * const spec = await serv.generateSpec(contract, {
+ *   title: 'My API',
+ *   version: '1.0.0',
+ *   apiPrefix: '/api/v1',
+ * })
+ * ```
+ */
+declare function generateSpec(contract: AnyContractRouter, options?: GenerateOpenAPISpecOptions): Promise<OpenAPI.Document>;
+
+/**
+ * @h-ai/serv — 校验工具
+ *
+ * 为 API service 提供与 kit 对等的校验 i18n 能力：
+ * - {@link resolveRequestLocale}：从请求头（`x-hai-locale` / `Accept-Language`）解析语言。
+ * - {@link validateInputOrFail}：在 procedure 内显式校验数据，失败返回 `HaiResult` 错误。
+ * - oRPC contract 输入校验失败的自动本地化由 `serv-app.ts` 中的 oRPC 响应拦截器处理。
+ *
+ * @module serv-validation
+ */
+
+/**
+ * 校验失败响应体（含 i18n 错误列表）。
+ *
+ * 复用 `HaiResult` 失败分支结构。字段错误同时在两处出现：
+ * - `error.cause`：与 `validateInputOrFail` 输出对齐，HaiResult 标准位置
+ * - 顶层 `errors`：保留以兼容已有客户端
+ */
+interface ServValidationFailureBody {
+    readonly success: false;
+    readonly error: {
+        readonly code: string | number;
+        readonly message: string;
+        readonly httpStatus: number;
+        readonly system: string;
+        readonly module: string;
+        readonly cause?: readonly ValidationFormError[];
+    };
+    readonly errors: readonly ValidationFormError[];
+}
+/**
+ * 从请求头解析客户端期望 locale。
+ *
+ * 优先级：`x-hai-locale` > `Accept-Language` 第一个匹配项 > 默认值（`zh-CN`）。
+ * 返回值会被规范化为 serv 当前支持的 locale（如 `en` → `en-US`）。
+ *
+ * @param headers - 请求头（`Headers` 或与之等价的对象）
+ * @returns 解析得到的 locale
+ */
+declare function resolveRequestLocale(headers: Headers | Record<string, string | undefined>): string;
+/**
+ * 在 procedure handler 内显式校验数据。
+ *
+ * 与 oRPC contract 自动校验不同，本函数用于业务层二次校验（例如对从数据库读到的对象再校验）。
+ * 失败时返回 `HaiResult` 错误分支，错误的 `cause` 字段携带 `ValidationFormError[]`。
+ *
+ * 推荐使用方式：
+ * ```ts
+ * import { z } from 'zod'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const Schema = z.object({ name: z.string().min(1) })
+ *
+ * export const handler = serv.mapHaiError(async ({ input, context }) => {
+ *   const result = serv.validateInputOrFail(Schema, input, context.locale)
+ *   if (!result.success) return result
+ *   const { name } = result.data
+ *   // ...
+ * })
+ * ```
+ *
+ * @param schema - Zod schema
+ * @param input - 待校验数据
+ * @param locale - 期望 locale（通常来自请求上下文）
+ */
+declare function validateInputOrFail<TOutput>(schema: ZodType<TOutput>, input: unknown, locale?: string): HaiResult<TOutput>;
+
+/** hai-framework API service runtime 统一入口（扁平 API）。 */
+declare const serv: {
+    createApp: typeof createApp;
+    parseRequestContext: typeof parseRequestContext;
+    buildAuthContextFactory: typeof buildAuthContextFactory;
+    resolveRequestLocale: typeof resolveRequestLocale;
+    listen: typeof listen;
+    toFetch: typeof toFetch;
+    generateSpec: typeof generateSpec;
+    /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
+    implement: typeof implement;
+    requireAuth: typeof requireAuth;
+    requirePermission: typeof requirePermission;
+    requireRole: typeof requireRole;
+    mapHaiError: typeof mapHaiError;
+    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;
+};
+
+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 };