@h-ai/serv 0.1.0-alpha.15

package/README.md

@@ -0,0 +1,515 @@
+# @h-ai/serv
+
+> hai-framework 的 Hono + oRPC API 服务运行时，把 `@h-ai/api-contract` 的契约挂载为跨端可访问的 HTTP API。
+
+## 能力概览
+
+- 一行启动：`serv.createApp(...)` → `serv.listen(app, { port })`
+- 扁平 API（最小知识）：`serv.listen / serv.toFetch / serv.requireAuth / serv.requirePermission / serv.generateSpec / ...`
+- 自定义 pipeline：`createApp({ middlewares })` 挂 HTTP middleware；procedure wrapper 复用根入口导出的共享类型
+- 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
+- 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页、可选内部 RPC endpoint
+- 可选传输加密：`serv.createApp({ transport: { crypto } })` 自动挂载密钥协商与请求/响应加解密
+
+## 快速开始
+
+```ts
+import { apiContract } from '@h-ai/api-contract'
+import { serv } from '@h-ai/serv'
+import { createAiProcedures } from '@h-ai/serv/features/ai'
+import { createIamProcedures } from '@h-ai/serv/features/iam'
+import { createStorageProcedures } from '@h-ai/serv/features/storage'
+
+// 1) 创建契约
+const contract = apiContract.create({ iam: apiContract.iam, storage: apiContract.storage, ai: apiContract.ai })
+
+// 2) 组装 procedures（注入 iam / storage / ai 已初始化的 functions）
+const procedures = {
+  iam: createIamProcedures({ iam }),
+  storage: createStorageProcedures({ storage }),
+  ai: createAiProcedures({ ai }),
+}
+
+// 3) 创建 app
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: {
+    apiPrefix: '/api/v1',
+    openapi: { path: '/openapi.json' },
+    docs: { path: '/docs' },
+  },
+})
+
+// 4) 启动 Node 服务（读取 PORT / HOST 环境变量，onClose 自动处理 SIGINT/SIGTERM）
+serv.listen(app, {
+  onListening: info => logger.info('API service listening', { port: info.port }),
+  onClose: closeApp,
+})
+
+// 5) 优雅关闭由 serv 托管，无需手动注册 process.once('SIGINT', ...)
+```
+
+### 容器对外暴露
+
+默认 `host` 为 `127.0.0.1`（仅本机可达）。容器或需对外提供服务时显式指定：
+
+```ts
+serv.listen(app, { host: '0.0.0.0', onClose: closeApp })
+```
+
+### Fetch Runtime（Workers / Bun / Deno）
+
+```ts
+const handler = serv.toFetch(app)
+export default { fetch: handler }
+```
+
+### 传输加密（与 `@h-ai/crypto` 统一）
+
+serv 不暴露本地传输加密工厂；统一从 `crypto.transport` 创建服务端管理器。使用方只需传入顶层 `crypto` 句柄：
+
+```ts
+import { crypto } from '@h-ai/crypto'
+import { serv } from '@h-ai/serv'
+
+await crypto.init()
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  transport: {
+    crypto,
+    // keyExchangePath 默认 '/_hai/key-exchange'，最终端点为 '/api/v1/_hai/key-exchange'
+    // excludePaths: ['/health'],
+    // maxClients: 10000,
+  },
+})
+```
+
+客户端使用 `@h-ai/api-client`：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  transport: { crypto },
+})
+```
+
+如果应用通过 `@h-ai/core` 从 `config/_serv.yml` 驱动 `ServConfigSchema`，transport 也可以一起配置：
+
+```yaml
+# config/_serv.yml
+http:
+  apiPrefix: /api/v1
+
+transport:
+  keyExchangePath: /_hai/key-exchange
+  excludePaths:
+    - /health
+    - /ready
+    - /openapi.json
+    - /docs
+    - /_hai/scalar.js
+  maxClients: 10000
+```
+
+```ts
+const servConfig = core.config.getOrThrow<import('@h-ai/serv').ServConfig>('serv')
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: servConfig.http,
+  transport: servConfig.transport === false
+    ? undefined
+    : {
+        crypto,
+        keyExchangePath: servConfig.transport.keyExchangePath,
+        excludePaths: [...servConfig.transport.excludePaths],
+        maxClients: servConfig.transport.maxClients,
+      },
+})
+```
+
+> **多节点部署提示**：传输加密的会话密钥保存在 **服务端进程内**，多副本部署时必须满足下列条件之一才能正常工作：
+>
+> - 在负载均衡层启用**会话粘性（sticky session）**，确保同一客户端命中同一节点；
+> - 或为每个客户端在每个节点首次访问时分别完成一次密钥协商；
+> - 或后续提供分布式密钥存储（roadmap）。
+>
+> 单节点部署无需额外配置。
+
+> **安全策略**：启用 `transport` 后，除 `excludePaths` 与密钥协商端点外，业务请求必须携带有效 `X-Client-Id`。缺失或未知 clientId 会返回 400；响应体无法加密、非 JSON 业务响应或超过单次加密上限时返回错误，不会明文透传业务数据。
+
+### Token 认证（`iam` / `refreshCookie`）
+
+`serv.createApp` 推荐直接传入顶层 `iam` 句柄，自动派生两件事：
+
+- **access token 校验**：每个请求调用 `iam.session.verifyToken` 填充 `context.session`（不缓存）。
+- **refresh token 轮换**：启用 `refreshCookie` 后，自动使用 `iam.session.refresh` 作为 httpOnly cookie 刷新回调。
+
+**上下文工厂优先级**：显式 `createContext` > `verifyToken` > `iam.session.verifyToken` > 默认仅解析元数据。
+
+```ts
+// 推荐：传入 iam，一行打开认证与 Cookie 刷新
+const app = serv.createApp({
+  contract,
+  procedures,
+  iam,
+  refreshCookie: {}, // 可选：启用 httpOnly cookie 刷新路径
+})
+
+// 逃脱口 1：不使用 @h-ai/iam，自定义 verifyToken
+const app = serv.createApp({
+  contract,
+  procedures,
+  verifyToken: token => myAuthService.verify(token),
+})
+
+// 逃脱口 2（高级）：多租户等额外字段 — 完全接管上下文构造
+const app = serv.createApp({
+  contract,
+  procedures,
+  createContext: async ({ request }) => {
+    const base = serv.parseRequestContext({ request })
+    // 手动填充 session（serv 不再自动填充）
+    const result = await iam.session.verifyToken(base.accessToken ?? '')
+    return {
+      ...base,
+      session: result.success ? result.data : undefined,
+      tenantId: request.headers.get('x-tenant') ?? null,
+    }
+  },
+})
+```
+
+### 自定义 procedure（认证 + 权限）
+
+```ts
+const p = serv.implement(myContract).$context<ServContext>()
+
+const updateProfile = p.users.update.handler(
+  serv.requirePermission('users.write', async ({ input, context }) => {
+    return await userService.update(input.id, input)
+  }),
+)
+```
+
+### 高级：自定义 pipeline（HTTP middleware + context + procedure wrapper）
+
+`@h-ai/serv` 的“pipeline”分三层，分别对应三种扩展方式：
+
+1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 Hono middleware。
+2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 定制请求上下文。
+3. **procedure wrapper 层**：通过 `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 组合认证、审计、租户校验等业务包装。
+
+#### 1) 自定义 HTTP middleware
+
+当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑** 时，使用 `middlewares`：
+
+```ts
+import type { ServMiddleware } from '@h-ai/serv'
+
+const requestMetrics: ServMiddleware = async (c, next) => {
+  const startedAt = Date.now()
+  await next()
+  c.header('x-response-time-ms', String(Date.now() - startedAt))
+}
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  middlewares: [
+    { middleware: requestMetrics }, // 默认挂到 '*'
+    {
+      path: '/api/v1/*',
+      middleware: async (c, next) => {
+        if (!c.req.header('x-tenant-id'))
+          return c.text('Missing x-tenant-id', 400)
+        await next()
+      },
+    },
+  ],
+})
+```
+
+执行顺序固定为：
+
+1. 内置 `securityHeaders`
+2. 内置 `transport`（若启用）
+3. 你的 `middlewares`
+4. health / refresh-cookie / OpenAPI / RPC / docs / oRPC routes
+
+说明：
+
+- `middlewares` 按数组顺序注册
+- `path` 省略时默认 `'*'`
+- 这一层直接操作 Hono `Context`，返回的是 **HTTP Response**，不是 `HaiResult`
+
+#### 2) 自定义 context pipeline
+
+如果你只想复用 `Bearer token -> session` 这一段逻辑，再额外补充租户、工作区、来源系统等字段，
+优先用 `serv.buildAuthContextFactory()` 组装自定义 `createContext`：
+
+```ts
+const baseContext = serv.buildAuthContextFactory(token => iam.session.verifyToken(token))
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  createContext: async ({ request }) => {
+    const context = await baseContext({ request })
+    return {
+      ...context,
+      tenantId: request.headers.get('x-tenant-id') ?? null,
+    }
+  },
+})
+```
+
+什么时候用哪个：
+
+- 只想换 token 校验实现：用 `verifyToken`
+- 想在默认认证上下文之上追加字段：用 `buildAuthContextFactory(...) + createContext`
+- 想完全接管上下文构造：直接用 `createContext`
+
+#### 3) 自定义 procedure wrapper
+
+当逻辑已经进入 oRPC procedure，需要统一做审计、租户约束、业务 guard 时，使用 procedure wrapper：
+
+```ts
+import type { ServGuardedProcedureWrapper, ServProcedureWrapper } from '@h-ai/serv'
+import { err, HaiCommonError } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+
+const withAudit: ServProcedureWrapper = handler => async (options) => {
+  options.context.logger.info('procedure.start', { requestId: options.context.requestId })
+  return await handler(options)
+}
+
+const requireTenant: ServGuardedProcedureWrapper<string> = (tenantId, handler) => async (options) => {
+  if (options.context.request.headers.get('x-tenant-id') !== tenantId) {
+    return err(
+      HaiCommonError.FORBIDDEN,
+      serv.m('serv_errorForbidden', { locale: options.context.locale }),
+    )
+  }
+  return await handler(options)
+}
+
+const createWidget = serv.mapHaiError(
+  serv.requireAuth(
+    withAudit(
+      requireTenant('tenant-a', async ({ input }) => widgetService.create(input)),
+    ),
+  ),
+)
+```
+
+说明：
+
+- `ServProcedureWrapper`：单参数 wrapper，适合 `withAudit(handler)` 这种模式
+- `ServGuardedProcedureWrapper<T>`：带配置参数的 wrapper，适合 `requireTenant('t1', handler)` 这种模式
+- procedure wrapper 返回的是 `HaiResult<T>`，和 `serv.requireAuth` / `serv.requirePermission` 保持一致
+- 常规场景优先继续用 `serv.requireAuth / requirePermission / requireRole / mapHaiError`
+
+边界约束：
+
+- `src/pipelines/*` 是 `@h-ai/serv` 的内部默认实现目录，不作为公开子路径 API 承诺
+- 对应用层公开的稳定入口仍然是根入口 `@h-ai/serv`
+- `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` 等内部 helper/middleware 不作为单独子路径文档暴露
+
+### httpOnly Cookie 认证（推荐生产方案）
+
+httpOnly cookie 模式将 refresh token 存储在服务端管理的 cookie 中（浏览器 JS 无法读取），避免 XSS 风险。
+
+先把两个 token 的职责分清：
+
+- `accessToken`：短期凭证。客户端把它放在内存中，并通过 `Authorization: Bearer <token>` 发送。
+  `serv.parseRequestContext()` / `extractBearerToken()` 解析的就是它；`buildAuthContextFactory()` 校验的也是它。
+- `refreshToken`：长期凭证。启用 `refreshCookie` 后，它不会再暴露给前端 JS，而是只保存在浏览器的 httpOnly cookie 中。
+  它**不会**被 `extractBearerToken()` 读取，只会在 `/auth/refresh` 被服务端取出，用来换发新的 access token。
+
+**工作原理：**
+
+1. 浏览器登录 → 服务端在响应中 `Set-Cookie: hai_refresh_token=...;HttpOnly`，并从 JSON 响应体擦除 `refreshToken`
+2. Access token 存储在客户端内存（不持久化）
+3. Access token 过期时，浏览器自动携带 cookie 访问 `/auth/refresh`
+4. 服务端读取 cookie → 调用 `onRefresh` → 返回新 access token + 更新 cookie（响应体不暴露 refresh token）
+
+**服务端配置：**
+
+```ts
+// 服务端：api-service/src/app.ts
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  iam, // 顶层 iam 同时驱动 verifyToken 与 refresh
+  refreshCookie: {
+    // cookieName: 'hai_refresh_token', // 默认
+    // maxAge: 30 * 24 * 3600,          // 默认 30 天
+    // secure: true,                    // 默认在 NODE_ENV=production 时开启
+    // onRefresh: customFn,             // 可覆盖 iam.session.refresh。
+  },
+  // ✅ 无需再传 verifyToken，iam.session.verifyToken 自动用于填充 context.session
+})
+```
+
+**客户端配置（与 `@h-ai/api-client` 配合）：**
+
+```ts
+// 默认存储即 httpOnly cookie，refreshPath 默认 /auth/refresh，无需额外配置。
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+})
+```
+
+> **Cookie 规格**：`HttpOnly; SameSite=Strict; Secure`（生产）；`Path` 限制为 `{apiPrefix}/auth/refresh`。
+
+## API 概览
+
+- `serv.createApp(options)`：创建 Hono 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
+- `serv.generateSpec(contract, options)`：由 contract 生成 OpenAPI 3.1 spec
+- `serv.requireAuth(handler)`：procedure 认证包装器（`context.session` 为空 → UNAUTHORIZED）
+- `serv.requirePermission(perm, handler)`：procedure 权限包装器（缺失权限 → FORBIDDEN）
+- `serv.requireRole(role, handler)`：procedure 角色包装器（缺失角色 → FORBIDDEN）
+- `serv.mapHaiError(handler)`：统一异常 → `HaiResult` 的包装器
+- `serv.validateInputOrFail(zodSchema, input, locale)`：在 procedure 内做 Zod 二次校验，失败时返回本地化 `HaiResult` + `ValidationFormError[]`
+- `serv.resolveRequestLocale(headers)`：从 `x-hai-locale` / `Accept-Language` 解析并规范化请求 locale
+- `serv.m(key, options)`：读取 `@h-ai/serv` 自身消息，支持 `options.locale` 单次调用本地化
+
+另有根级类型 / 命名导出：
+
+- `ServConfigSchema`：用于 `core.config.validate('serv', ServConfigSchema)` 校验 `config/_serv.yml`
+- `ServMiddlewareMount`：`createApp({ middlewares })` 的挂载项类型（`{ path?, middleware }`）
+- `ServMiddleware` / `ServProcedureWrapper` / `ServGuardedProcedureWrapper`：自定义 pipeline 时复用的共享类型
+
+> 传输加密不作为 `serv.xxx` 扁平 API 暴露；它是 `createApp` 的配置能力，内部委托 `crypto.transport`。
+
+## 配置
+
+`@h-ai/serv` 本身不主动扫描 YAML；推荐由 `@h-ai/core` 统一加载 `config/_serv.yml`，再把解析结果传给 `serv.createApp()`。
+
+```ts
+import { core } from '@h-ai/core'
+import { serv, ServConfigSchema } from '@h-ai/serv'
+
+core.init({ configDir: './config' })
+
+const validation = core.config.validate('serv', ServConfigSchema)
+if (!validation.success)
+  throw new Error(validation.error.message)
+
+const servConfig = core.config.getOrThrow<import('@h-ai/serv').ServConfig>('serv')
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: servConfig.http,
+  transport: servConfig.transport === false
+    ? undefined
+    : {
+        crypto,
+        keyExchangePath: servConfig.transport.keyExchangePath,
+        excludePaths: [...servConfig.transport.excludePaths],
+        maxClients: servConfig.transport.maxClients,
+      },
+})
+```
+
+`config/_serv.yml` 示例：
+
+```yaml
+http:
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+
+transport:
+  keyExchangePath: /_hai/key-exchange
+  excludePaths:
+    - /health
+    - /ready
+    - /openapi.json
+    - /docs
+    - /_hai/scalar.js
+  maxClients: 10000
+```
+
+`ServHttpConfigInput`：
+
+- `apiPrefix`：默认 `/api/v1`
+- `health`：默认 `{ path: '/health', readyPath: '/ready' }`
+- `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? }`
+- `transport`：`config/_serv.yml` 顶层配置；启用后可通过 `servConfig.transport` 装配到 `createApp({ transport })`，默认密钥协商子路径 `/_hai/key-exchange`
+
+## 错误处理
+
+- Default procedures 全部返回 `HaiResult<T>`，客户端直接判断 `result.success`
+- 认证失败 → `HaiCommonError.UNAUTHORIZED`（由 `requireAuth` 按 `context.locale` 本地化）
+- 授权失败 → `HaiCommonError.FORBIDDEN`（由 `requirePermission` / `requireRole` 按 `context.locale` 本地化）
+- 未捕获异常 → `HaiCommonError.INTERNAL_ERROR`（由 `mapHaiError` 统一兜底并按 `context.locale` 本地化）
+
+正常业务请求建议按三层处理：
+
+1. **oRPC contract 输入校验**：进入 procedure 前由 oRPC 执行；`serv.createApp()` 内部会自动拦截并把 Zod 默认英文错误重写为本地化 `errors[]`。
+2. **procedure 内二次校验**：对数据库读回对象、跨字段约束等适合 Zod 表达的规则，使用 `serv.validateInputOrFail(zodSchema, input, context.locale)`；简单业务规则直接 `err(...)` 即可，不必为了统一额外造 schema。
+3. **业务/领域错误**：不要 throw 预期业务失败；直接返回 `err(...)`，并在**创建错误消息的那一层**使用对应模块的 i18n getter，例如 `serv.m(..., { locale: context.locale })` 或 `widgetM(..., { locale: context.locale })`。
+
+```ts
+import { err, HaiCommonError } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { z } from 'zod'
+
+const CreateWidgetSchema = z.object({
+  title: z.string().min(1),
+  slug: z.string().min(3),
+})
+
+const createWidget = serv.mapHaiError(async ({ input, context }) => {
+  const validated = serv.validateInputOrFail(CreateWidgetSchema, input, context.locale)
+  if (!validated.success)
+    return validated
+
+  if (validated.data.slug === 'admin') {
+    return err(
+      HaiCommonError.FORBIDDEN,
+      serv.m('serv_errorForbidden', { locale: context.locale }),
+    )
+  }
+
+  return widgetService.create(validated.data)
+})
+```
+
+> 如果错误来自下游业务模块（如 `iam.user.xxx()`）且该模块已经直接返回 `HaiResult`，serv 会原样透传它的 `error.message`。当前 `HaiError` 只携带最终 `message`，不携带 `messageKey/params`，因此 **serv 边界无法对任意下游错误再做一次通用 i18n 重翻译**；要支持请求级 i18n，必须在创建该错误消息的模块里就拿到 locale。
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/serv test
+pnpm --filter @h-ai/serv typecheck
+pnpm --filter @h-ai/serv lint
+```
+
+## License
+
+Apache-2.0

package/dist/chunk-27PCPE37.js

@@ -0,0 +1,17 @@
+import { ok } from '@h-ai/core';
+
+// src/features/serv-feature-helpers.ts
+function wrapItemsResult(result) {
+  if (!result.success)
+    return result;
+  return ok({ items: result.data });
+}
+function mapHaiResult(result, mapper) {
+  if (!result.success)
+    return result;
+  return ok(mapper(result.data));
+}
+
+export { mapHaiResult, wrapItemsResult };
+//# sourceMappingURL=chunk-27PCPE37.js.map
+//# sourceMappingURL=chunk-27PCPE37.js.map

package/dist/chunk-27PCPE37.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/features/serv-feature-helpers.ts"],"names":[],"mappings":";;;AAgBO,SAAS,gBAAmB,MAAA,EAAmD;AACpF,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA;AACV,IAAA,OAAO,MAAA;AACT,EAAA,OAAO,EAAA,CAAG,EAAE,KAAA,EAAO,MAAA,CAAO,MAAM,CAAA;AAClC;AAKO,SAAS,YAAA,CAAmB,QAAsB,MAAA,EAAsC;AAC7F,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA;AACV,IAAA,OAAO,MAAA;AACT,EAAA,OAAO,EAAA,CAAG,MAAA,CAAO,MAAA,CAAO,IAAI,CAAC,CAAA;AAC/B","file":"chunk-27PCPE37.js","sourcesContent":["/**\n * @h-ai/serv — features 公共辅助\n *\n * 把多个 feature procedure 中重复出现的 `HaiResult` 包装逻辑收敛到一处。\n * @module features/serv-feature-helpers\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport { ok } from '@h-ai/core'\n\n/**\n * 把 `HaiResult<T[]>` 转换为 `HaiResult<{ items: T[] }>`。\n *\n * oRPC contract 中 list 类返回常用 `{ items: [...] }` 信封；\n * 业务模块通常直接返回数组，本工具负责套上信封。\n */\nexport function wrapItemsResult<T>(result: HaiResult<T[]>): HaiResult<{ items: T[] }> {\n  if (!result.success)\n    return result\n  return ok({ items: result.data })\n}\n\n/**\n * 把 `HaiResult<T>` 通过 mapper 映射为 `HaiResult<U>`，错误透传。\n */\nexport function mapHaiResult<T, U>(result: HaiResult<T>, mapper: (data: T) => U): HaiResult<U> {\n  if (!result.success)\n    return result\n  return ok(mapper(result.data))\n}\n"]}

package/dist/chunk-4QBF4PUG.js

@@ -0,0 +1,128 @@
+import { core, err, HaiCommonError } from '@h-ai/core';
+
+// src/serv-i18n.ts
+
+// messages/en-US.json
+var en_US_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  serv_validationFailed: "Validation failed",
+  serv_validationRequired: "This field is required",
+  serv_validationInvalid: "Invalid input format",
+  serv_validationInvalidType: "Invalid field type",
+  serv_validationStringMin: "Enter at least {min} characters",
+  serv_validationStringMax: "Enter at most {max} characters",
+  serv_validationNumberMin: "Value must be at least {min}",
+  serv_validationNumberMax: "Value must be at most {max}",
+  serv_validationArrayMin: "Select at least {min} item(s)",
+  serv_validationArrayMax: "Select at most {max} item(s)",
+  serv_validationTooSmall: "Value must be at least {min}",
+  serv_validationTooBig: "Value must be at most {max}",
+  serv_validationEmail: "Enter a valid email address",
+  serv_validationUrl: "Enter a valid URL",
+  serv_validationUuid: "Enter a valid UUID",
+  serv_validationEnum: "Select a valid option",
+  serv_errorUnauthorized: "Unauthorized",
+  serv_errorForbidden: "Forbidden",
+  serv_errorInternal: "Internal server error",
+  serv_storageKeyRequired: "Storage key must not be empty",
+  serv_storageKeyTooLong: "Storage key must not exceed {max} characters",
+  serv_storageKeyIllegalChars: "Storage key contains illegal characters",
+  serv_storageKeyDotSegments: "Storage key must not contain . or .. path segments",
+  serv_iamCannotDeleteCurrentUser: "Cannot delete the current logged-in user",
+  serv_transportInvalidPayload: "Invalid encrypted transport payload",
+  serv_transportUnknownClient: "Unknown encryption client; key exchange required",
+  serv_transportClientIdRequired: "Missing X-Client-Id header; key exchange required",
+  serv_transportClientKeyNotFound: "Client not registered or session expired; complete key exchange again",
+  serv_transportDecryptFailed: "Failed to decrypt request",
+  serv_transportEncryptFailed: "Failed to encrypt response",
+  serv_transportKeyExchangeFailed: "Key exchange failed"
+};
+
+// messages/zh-CN.json
+var zh_CN_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  serv_validationFailed: "\u6570\u636E\u9A8C\u8BC1\u5931\u8D25",
+  serv_validationRequired: "\u6B64\u5B57\u6BB5\u5FC5\u586B",
+  serv_validationInvalid: "\u8F93\u5165\u683C\u5F0F\u65E0\u6548",
+  serv_validationInvalidType: "\u5B57\u6BB5\u7C7B\u578B\u4E0D\u6B63\u786E",
+  serv_validationStringMin: "\u81F3\u5C11\u8F93\u5165 {min} \u4E2A\u5B57\u7B26",
+  serv_validationStringMax: "\u6700\u591A\u8F93\u5165 {max} \u4E2A\u5B57\u7B26",
+  serv_validationNumberMin: "\u6570\u503C\u4E0D\u80FD\u5C0F\u4E8E {min}",
+  serv_validationNumberMax: "\u6570\u503C\u4E0D\u80FD\u5927\u4E8E {max}",
+  serv_validationArrayMin: "\u81F3\u5C11\u9009\u62E9 {min} \u9879",
+  serv_validationArrayMax: "\u6700\u591A\u9009\u62E9 {max} \u9879",
+  serv_validationTooSmall: "\u4E0D\u80FD\u5C0F\u4E8E {min}",
+  serv_validationTooBig: "\u4E0D\u80FD\u5927\u4E8E {max}",
+  serv_validationEmail: "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u90AE\u7BB1\u5730\u5740",
+  serv_validationUrl: "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u7F51\u5740",
+  serv_validationUuid: "\u8BF7\u8F93\u5165\u6709\u6548\u7684 UUID",
+  serv_validationEnum: "\u8BF7\u9009\u62E9\u6709\u6548\u9009\u9879",
+  serv_errorUnauthorized: "\u672A\u767B\u5F55\u6216\u767B\u5F55\u5DF2\u5931\u6548",
+  serv_errorForbidden: "\u65E0\u6743\u6267\u884C\u8BE5\u64CD\u4F5C",
+  serv_errorInternal: "\u670D\u52A1\u5668\u5185\u90E8\u9519\u8BEF",
+  serv_storageKeyRequired: "\u5B58\u50A8 key \u4E0D\u80FD\u4E3A\u7A7A",
+  serv_storageKeyTooLong: "\u5B58\u50A8 key \u4E0D\u80FD\u8D85\u8FC7 {max} \u4E2A\u5B57\u7B26",
+  serv_storageKeyIllegalChars: "\u5B58\u50A8 key \u5305\u542B\u975E\u6CD5\u5B57\u7B26",
+  serv_storageKeyDotSegments: "\u5B58\u50A8 key \u4E0D\u80FD\u5305\u542B . \u6216 .. \u8DEF\u5F84\u6BB5",
+  serv_iamCannotDeleteCurrentUser: "\u4E0D\u80FD\u5220\u9664\u5F53\u524D\u767B\u5F55\u7528\u6237",
+  serv_transportInvalidPayload: "\u4F20\u8F93\u5C42\u52A0\u5BC6\u8F7D\u8377\u683C\u5F0F\u65E0\u6548",
+  serv_transportUnknownClient: "\u672A\u8BC6\u522B\u7684\u52A0\u5BC6\u5BA2\u6237\u7AEF\uFF0C\u8BF7\u5148\u5B8C\u6210\u5BC6\u94A5\u534F\u5546",
+  serv_transportClientIdRequired: "\u7F3A\u5C11 X-Client-Id \u8BF7\u6C42\u5934\uFF0C\u8BF7\u5148\u5B8C\u6210\u5BC6\u94A5\u534F\u5546",
+  serv_transportClientKeyNotFound: "\u5BA2\u6237\u7AEF\u672A\u6CE8\u518C\u6216\u4F1A\u8BDD\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u5B8C\u6210\u5BC6\u94A5\u534F\u5546",
+  serv_transportDecryptFailed: "\u8BF7\u6C42\u89E3\u5BC6\u5931\u8D25",
+  serv_transportEncryptFailed: "\u54CD\u5E94\u52A0\u5BC6\u5931\u8D25",
+  serv_transportKeyExchangeFailed: "\u5BC6\u94A5\u534F\u5546\u5931\u8D25"
+};
+
+// src/serv-i18n.ts
+var SUPPORTED_SERV_LOCALES = ["zh-CN", "en-US"];
+var DEFAULT_SERV_LOCALE = "zh-CN";
+function normalizeServLocale(locale) {
+  const candidate = locale?.split(",")[0]?.trim();
+  if (!candidate)
+    return DEFAULT_SERV_LOCALE;
+  const exact = SUPPORTED_SERV_LOCALES.find((item) => item.toLowerCase() === candidate.toLowerCase());
+  if (exact)
+    return exact;
+  const baseLanguage = candidate.split("-")[0]?.toLowerCase();
+  if (baseLanguage === "en")
+    return "en-US";
+  if (baseLanguage === "zh")
+    return "zh-CN";
+  return DEFAULT_SERV_LOCALE;
+}
+var servM = core.i18n.createMessageGetter({ "zh-CN": zh_CN_default, "en-US": en_US_default });
+function buildHaiErrorBody(def, message) {
+  return {
+    success: false,
+    error: {
+      code: def.code,
+      message,
+      httpStatus: def.httpStatus,
+      system: def.system,
+      module: def.module
+    }
+  };
+}
+function mapHaiError(handler) {
+  return async (options) => {
+    try {
+      return await handler(options);
+    } catch (error) {
+      return err(HaiCommonError.INTERNAL_ERROR, servM("serv_errorInternal", { locale: options.context.locale }), error);
+    }
+  };
+}
+
+// src/pipelines/serv-pipeline-require-auth.ts
+function requireAuth(handler) {
+  return mapHaiError(async (options) => {
+    if (!options.context.session)
+      return err(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: options.context.locale }));
+    return handler(options);
+  });
+}
+
+export { buildHaiErrorBody, mapHaiError, normalizeServLocale, requireAuth, servM };
+//# sourceMappingURL=chunk-4QBF4PUG.js.map
+//# sourceMappingURL=chunk-4QBF4PUG.js.map