@h-ai/serv 0.1.0-alpha.45 → 0.1.0-alpha.47

package/README.md

@@ -5,8 +5,9 @@
 ## 能力概览
 
 - 一行启动：`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 复用根入口导出的共享类型
+- 扁平 API（最小知识）：`serv.createApp / serv.implement / serv.listen / serv.toFetch / serv.generateSpec / ...`
+- 链式 procedure：`implement().context().route().auth/permission/role().handle().build()`
+- 自定义 pipeline：`createApp({ middlewares })` 挂 HTTP middleware；请求级字段通过 context 工厂注入
 - 只读 Storage 资源：`serv.storageAssets(...)` 统一处理安全 key、MIME 白名单、GET/HEAD、ETag 与缓存头
 - 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
 - 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页、可选内部 RPC endpoint
@@ -231,22 +232,24 @@ const app = serv.createApp({
 ### 自定义 procedure（认证 + 权限）
 
 ```ts
-const p = serv.implement(myContract).$context<ServContext>()
-
-const updateProfile = p.users.update.handler(
-  serv.requirePermission('users.write', async ({ input, context }) => {
+const procedures = serv
+  .implement(myContract)
+  .context<ServContext>()
+  .route('users.update')
+  .permission('users.write')
+  .handle(async ({ input, context }) => {
     return await userService.update(input.id, input)
-  }),
-)
+  })
+  .build()
 ```
 
-### 高级：自定义 pipeline（HTTP middleware + context + procedure wrapper）
+### 高级：自定义 pipeline（HTTP middleware + context + route guard）
 
 `@h-ai/serv` 的“pipeline”分三层，分别对应三种扩展方式：
 
 1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 HTTP middleware。
 2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 定制请求上下文。
-3. **procedure wrapper 层**：通过 `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 组合认证、审计、租户校验等业务包装。
+3. **route guard 层**：通过 `.auth()` / `.permission()` / `.role()` 声明认证授权。
 
 #### 1) 自定义 HTTP middleware
 
@@ -343,45 +346,32 @@ const app = serv.createApp({
 - 想在默认认证上下文之上追加字段：用 `buildAuthContextFactory(...) + createContext`
 - 想完全接管上下文构造：直接用 `createContext`
 
-#### 3) 自定义 procedure wrapper
+#### 3) Route guard
 
-当逻辑已经进入 oRPC procedure，需要统一做审计、租户约束、业务 guard 时，使用 procedure wrapper：
+公开 procedure 使用 `.route(path, handler)`；需要 guard 时使用
+`.route(path).auth/permission/role().handle(handler)`：
 
 ```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)),
-    ),
-  ),
-)
+const procedures = serv
+  .implement(widgetContract)
+  .context<ServContext>()
+  .route('widgets.list', ({ input }) => widgetService.list(input))
+  .route('widgets.create')
+  .permission('widgets.write')
+  .role('editor')
+  .handle(({ input, context }) => {
+    // guard 通过后 session 在类型上已是非空，不需要 `!`。
+    return widgetService.create(context.session.userId, input)
+  })
+  .build()
 ```
 
-说明：
+约束：
 
-- `ServProcedureWrapper`：单参数 wrapper，适合 `withAudit(handler)` 这种模式
-- `ServGuardedProcedureWrapper<T>`：带配置参数的 wrapper，适合 `requireTenant('t1', handler)` 这种模式
-- procedure wrapper 返回的是 `HaiResult<T>`，和 `serv.requireAuth` / `serv.requirePermission` 保持一致
-- 常规场景优先继续用 `serv.requireAuth / requirePermission / requireRole / mapHaiError`
+- `.permission()` 与 `.role()` 自动要求认证；未登录返回 401，授权不足返回 403。
+- 同一路由声明多个 permission/role 时必须全部满足；`serv.WILDCARD_PERMISSION` / `serv.WILDCARD_ROLE` 可放行对应类别。
+- handler 抛出的未处理异常统一转成 INTERNAL_ERROR HaiResult；预期业务失败仍应直接返回 `err(...)`。
+- 路径、input、output 从 contract 推导；重复或未知路径会被拒绝，未实现完整 contract 时不能调用 `.build()`。
 
 边界约束：
 
@@ -456,10 +446,11 @@ await apiClient.init({
 - `serv.toFetch(app)`：包装为标准 `fetch(Request)` handler
 - `serv.generateSpec(contract, options)`：由 contract 生成 OpenAPI 3.1 spec
 - `serv.storageAssets(config)`：创建只读 Storage 资源 middleware，内置 key/MIME 白名单、GET/HEAD 与 ETag
-- `serv.requireAuth(handler)`：procedure 认证包装器（`context.session` 为空 → UNAUTHORIZED）
-- `serv.requirePermission(perm, handler)`：procedure 权限包装器（缺失权限 → FORBIDDEN）
-- `serv.requireRole(role, handler)`：procedure 角色包装器（缺失角色 → FORBIDDEN）
-- `serv.mapHaiError(handler)`：统一异常 → `HaiResult` 的包装器
+- `serv.implement(contract)`：创建链式 contract 实现器
+- `.context<ServContext>()`：声明 procedure 请求上下文
+- `.route(path, handler)`：注册公开 procedure
+- `.route(path).auth/permission/role().handle(handler)`：注册带认证授权的 procedure
+- `.build()`：所有 contract procedures 完整实现后构建 router
 - `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` 单次调用本地化
@@ -469,7 +460,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 时复用的共享类型
+- `ServMiddleware` / `ServProcedureHandler`：自定义 pipeline 时复用的共享类型
 - `NativeRefreshTokenTransportConfig` / `ServStorageAssetsConfig`：原生 Token 通道与只读资源 middleware 配置
 
 > 传输加密不作为 `serv.xxx` 扁平 API 暴露；它是 `createApp` 的配置能力，内部委托 `crypto.transport`。
@@ -585,9 +576,9 @@ const app = serv.createApp({
 ## 错误处理
 
 - Default procedures 全部返回 `HaiResult<T>`，客户端直接判断 `result.success`
-- 认证失败 → `HaiCommonError.UNAUTHORIZED`（由 `requireAuth` 按 `context.locale` 本地化）
-- 授权失败 → `HaiCommonError.FORBIDDEN`（由 `requirePermission` / `requireRole` 按 `context.locale` 本地化）
-- 未捕获异常 → `HaiCommonError.INTERNAL_ERROR`（由 `mapHaiError` 统一兜底并按 `context.locale` 本地化）
+- 认证失败 → `HaiCommonError.UNAUTHORIZED`（由 `.auth()` 按 `context.locale` 本地化）
+- 授权失败 → `HaiCommonError.FORBIDDEN`（由 `.permission()` / `.role()` 按 `context.locale` 本地化）
+- 未捕获异常 → `HaiCommonError.INTERNAL_ERROR`（由 route 实现器统一兜底并按 `context.locale` 本地化）
 
 正常业务请求建议按三层处理：
 
@@ -605,20 +596,26 @@ const CreateWidgetSchema = z.object({
   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 }),
-    )
-  }
+const procedures = serv
+  .implement(widgetContract)
+  .context<ServContext>()
+  .route('widgets.create')
+  .permission('widgets.write')
+  .handle(({ 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)
-})
+    return widgetService.create(validated.data)
+  })
+  .build()
 ```
 
 > 如果错误来自下游业务模块（如 `iam.user.xxx()`）且该模块已经直接返回 `HaiResult`，serv 会原样透传它的 `error.message`。当前 `HaiError` 只携带最终 `message`，不携带 `messageKey/params`，因此 **serv 边界无法对任意下游错误再做一次通用 i18n 重翻译**；要支持请求级 i18n，必须在创建该错误消息的模块里就拿到 locale。

package/dist/chunk-KIWHKWLD.js

@@ -0,0 +1,317 @@
+import { core, err, HaiCommonError } from '@h-ai/core';
+import { implement as implement$1 } from '@orpc/server';
+
+// 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 });
+var WILDCARD_PERMISSION = "*";
+var WILDCARD_ROLE = "*";
+function applyServGuards(requirements, handler) {
+  return async (options) => {
+    try {
+      if (!hasAuthenticatedSession(options.context)) {
+        return err(
+          HaiCommonError.UNAUTHORIZED,
+          servM("serv_errorUnauthorized", { locale: options.context.locale })
+        );
+      }
+      const { session } = options.context;
+      if (requirements.permissions?.length) {
+        const allowed = session.permissions.includes(WILDCARD_PERMISSION) || requirements.permissions.every(
+          (permission) => session.permissions.includes(permission)
+        );
+        if (!allowed) {
+          return err(
+            HaiCommonError.FORBIDDEN,
+            servM("serv_errorForbidden", { locale: options.context.locale })
+          );
+        }
+      }
+      if (requirements.roles?.length) {
+        const allowed = session.roles.includes(WILDCARD_ROLE) || requirements.roles.every(
+          (role) => session.roles.includes(role)
+        );
+        if (!allowed) {
+          return err(
+            HaiCommonError.FORBIDDEN,
+            servM("serv_errorForbidden", { locale: options.context.locale })
+          );
+        }
+      }
+      return await handler({
+        ...options,
+        context: options.context
+      });
+    } catch (error) {
+      return err(
+        HaiCommonError.INTERNAL_ERROR,
+        servM("serv_errorInternal", { locale: options.context.locale }),
+        error
+      );
+    }
+  };
+}
+function hasAuthenticatedSession(context) {
+  return context.session !== void 0 && context.session !== null;
+}
+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/serv-router.ts
+function implement(contract) {
+  return {
+    context: () => {
+      const native = implement$1(contract).$context();
+      return createServRouterBuilder(contract, native);
+    }
+  };
+}
+function createServRouterBuilder(contract, implementer) {
+  const runtime = new ServRouterBuilderRuntime(contract, implementer);
+  return runtime;
+}
+var ServRouterBuilderRuntime = class {
+  constructor(contract, implementer) {
+    this.implementer = implementer;
+    this.expectedPaths = new Set(collectProcedurePaths(contract));
+    this.implementedRoutes = createRouterShape(contract);
+  }
+  expectedPaths;
+  implementedRoutes;
+  registeredPaths = /* @__PURE__ */ new Set();
+  route(path, handler) {
+    if (handler !== void 0)
+      return this.register(path, {}, handler);
+    return new ServRouteRegistrationRuntime(this, path);
+  }
+  register(path, guards, handler) {
+    if (!this.expectedPaths.has(path))
+      throw new TypeError(`Contract path is not implementable: ${path}`);
+    if (this.registeredPaths.has(path))
+      throw new TypeError(`Duplicate procedure implementation: ${path}`);
+    if (typeof handler !== "function")
+      throw new TypeError(`Procedure handler must be a function: ${path}`);
+    const procedureImplementer = getAtPath(this.implementer, path);
+    const implementHandler = getHandlerMethod(procedureImplementer);
+    if (!implementHandler)
+      throw new TypeError(`Contract path is not implementable: ${path}`);
+    const safeHandler = hasGuards(guards) ? applyServGuards(guards, handler) : mapHaiError(handler);
+    const implemented = Reflect.apply(
+      implementHandler,
+      procedureImplementer,
+      [safeHandler]
+    );
+    setAtPath(this.implementedRoutes, path, implemented);
+    this.registeredPaths.add(path);
+    return this;
+  }
+  build() {
+    const missingPaths = [...this.expectedPaths].filter((path) => !this.registeredPaths.has(path)).sort();
+    if (missingPaths.length > 0) {
+      throw new TypeError(
+        `Cannot build router. Missing procedures: ${missingPaths.join(", ")}`
+      );
+    }
+    const routerMethod = Reflect.get(this.implementer, "router");
+    if (typeof routerMethod !== "function")
+      throw new TypeError("The oRPC implementer does not expose router()");
+    return Reflect.apply(routerMethod, this.implementer, [this.implementedRoutes]);
+  }
+};
+var ServRouteRegistrationRuntime = class {
+  constructor(parent, path) {
+    this.parent = parent;
+    this.path = path;
+  }
+  authRequired = false;
+  permissions = /* @__PURE__ */ new Set();
+  roles = /* @__PURE__ */ new Set();
+  auth() {
+    this.authRequired = true;
+    return this;
+  }
+  permission(permission) {
+    this.authRequired = true;
+    this.permissions.add(permission);
+    return this;
+  }
+  role(role) {
+    this.authRequired = true;
+    this.roles.add(role);
+    return this;
+  }
+  handle(handler) {
+    return this.parent.register(this.path, {
+      auth: this.authRequired,
+      permissions: [...this.permissions],
+      roles: [...this.roles]
+    }, handler);
+  }
+};
+function hasGuards(guards) {
+  return guards.auth === true || (guards.permissions?.length ?? 0) > 0 || (guards.roles?.length ?? 0) > 0;
+}
+function collectProcedurePaths(contract, prefix = []) {
+  if (isContractProcedure(contract))
+    return prefix.length > 0 ? [prefix.join(".")] : [];
+  return Object.entries(contract).flatMap(([key, child]) => collectProcedurePaths(child, [...prefix, key]));
+}
+function isContractProcedure(contract) {
+  return "~orpc" in contract;
+}
+function createRouterShape(contract) {
+  const shape = /* @__PURE__ */ Object.create(null);
+  for (const [key, child] of Object.entries(contract)) {
+    if (!isContractProcedure(child))
+      shape[key] = createRouterShape(child);
+  }
+  return shape;
+}
+function getAtPath(root, path) {
+  let current = root;
+  for (const segment of path.split(".")) {
+    if (typeof current !== "object" && typeof current !== "function" || current === null || !(segment in current)) {
+      return void 0;
+    }
+    current = Reflect.get(current, segment);
+  }
+  return current;
+}
+function setAtPath(root, path, value) {
+  const segments = path.split(".");
+  const leaf = segments.pop();
+  if (!leaf)
+    throw new TypeError("Procedure path cannot be empty");
+  let current = root;
+  for (const segment of segments) {
+    const existing = current[segment];
+    if (existing === void 0) {
+      const child = /* @__PURE__ */ Object.create(null);
+      current[segment] = child;
+      current = child;
+      continue;
+    }
+    if (!existing || typeof existing !== "object")
+      throw new TypeError(`Procedure path conflicts with an existing route: ${path}`);
+    current = existing;
+  }
+  current[leaf] = value;
+}
+function getHandlerMethod(value) {
+  if (typeof value !== "object" && typeof value !== "function" || value === null)
+    return void 0;
+  const handler = Reflect.get(value, "handler");
+  return typeof handler === "function" ? handler : void 0;
+}
+
+export { WILDCARD_PERMISSION, WILDCARD_ROLE, buildHaiErrorBody, implement, normalizeServLocale, servM };
+//# sourceMappingURL=chunk-KIWHKWLD.js.map
+//# sourceMappingURL=chunk-KIWHKWLD.js.map

package/dist/chunk-KIWHKWLD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../messages/en-US.json","../messages/zh-CN.json","../src/serv-i18n.ts","../src/pipelines/serv-pipeline-guard.ts","../src/pipelines/serv-pipeline-helper.ts","../src/serv-router.ts"],"names":["err","HaiCommonError","orpcImplement"],"mappings":"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","file":"chunk-KIWHKWLD.js","sourcesContent":["{\n  \"$schema\": \"https://inlang.com/schema/inlang-message-format\",\n  \"serv_validationFailed\": \"Validation failed\",\n  \"serv_validationRequired\": \"This field is required\",\n  \"serv_validationInvalid\": \"Invalid input format\",\n  \"serv_validationInvalidType\": \"Invalid field type\",\n  \"serv_validationStringMin\": \"Enter at least {min} characters\",\n  \"serv_validationStringMax\": \"Enter at most {max} characters\",\n  \"serv_validationNumberMin\": \"Value must be at least {min}\",\n  \"serv_validationNumberMax\": \"Value must be at most {max}\",\n  \"serv_validationArrayMin\": \"Select at least {min} item(s)\",\n  \"serv_validationArrayMax\": \"Select at most {max} item(s)\",\n  \"serv_validationTooSmall\": \"Value must be at least {min}\",\n  \"serv_validationTooBig\": \"Value must be at most {max}\",\n  \"serv_validationEmail\": \"Enter a valid email address\",\n  \"serv_validationUrl\": \"Enter a valid URL\",\n  \"serv_validationUuid\": \"Enter a valid UUID\",\n  \"serv_validationEnum\": \"Select a valid option\",\n  \"serv_errorUnauthorized\": \"Unauthorized\",\n  \"serv_errorForbidden\": \"Forbidden\",\n  \"serv_errorInternal\": \"Internal server error\",\n  \"serv_storageKeyRequired\": \"Storage key must not be empty\",\n  \"serv_storageKeyTooLong\": \"Storage key must not exceed {max} characters\",\n  \"serv_storageKeyIllegalChars\": \"Storage key contains illegal characters\",\n  \"serv_storageKeyDotSegments\": \"Storage key must not contain . or .. path segments\",\n  \"serv_iamCannotDeleteCurrentUser\": \"Cannot delete the current logged-in user\",\n  \"serv_transportInvalidPayload\": \"Invalid encrypted transport payload\",\n  \"serv_transportUnknownClient\": \"Unknown encryption client; key exchange required\",\n  \"serv_transportClientIdRequired\": \"Missing X-Client-Id header; key exchange required\",\n  \"serv_transportClientKeyNotFound\": \"Client not registered or session expired; complete key exchange again\",\n  \"serv_transportDecryptFailed\": \"Failed to decrypt request\",\n  \"serv_transportEncryptFailed\": \"Failed to encrypt response\",\n  \"serv_transportKeyExchangeFailed\": \"Key exchange failed\"\n}\n","{\n  \"$schema\": \"https://inlang.com/schema/inlang-message-format\",\n  \"serv_validationFailed\": \"数据验证失败\",\n  \"serv_validationRequired\": \"此字段必填\",\n  \"serv_validationInvalid\": \"输入格式无效\",\n  \"serv_validationInvalidType\": \"字段类型不正确\",\n  \"serv_validationStringMin\": \"至少输入 {min} 个字符\",\n  \"serv_validationStringMax\": \"最多输入 {max} 个字符\",\n  \"serv_validationNumberMin\": \"数值不能小于 {min}\",\n  \"serv_validationNumberMax\": \"数值不能大于 {max}\",\n  \"serv_validationArrayMin\": \"至少选择 {min} 项\",\n  \"serv_validationArrayMax\": \"最多选择 {max} 项\",\n  \"serv_validationTooSmall\": \"不能小于 {min}\",\n  \"serv_validationTooBig\": \"不能大于 {max}\",\n  \"serv_validationEmail\": \"请输入有效的邮箱地址\",\n  \"serv_validationUrl\": \"请输入有效的网址\",\n  \"serv_validationUuid\": \"请输入有效的 UUID\",\n  \"serv_validationEnum\": \"请选择有效选项\",\n  \"serv_errorUnauthorized\": \"未登录或登录已失效\",\n  \"serv_errorForbidden\": \"无权执行该操作\",\n  \"serv_errorInternal\": \"服务器内部错误\",\n  \"serv_storageKeyRequired\": \"存储 key 不能为空\",\n  \"serv_storageKeyTooLong\": \"存储 key 不能超过 {max} 个字符\",\n  \"serv_storageKeyIllegalChars\": \"存储 key 包含非法字符\",\n  \"serv_storageKeyDotSegments\": \"存储 key 不能包含 . 或 .. 路径段\",\n  \"serv_iamCannotDeleteCurrentUser\": \"不能删除当前登录用户\",\n  \"serv_transportInvalidPayload\": \"传输层加密载荷格式无效\",\n  \"serv_transportUnknownClient\": \"未识别的加密客户端，请先完成密钥协商\",\n  \"serv_transportClientIdRequired\": \"缺少 X-Client-Id 请求头，请先完成密钥协商\",\n  \"serv_transportClientKeyNotFound\": \"客户端未注册或会话已过期，请重新完成密钥协商\",\n  \"serv_transportDecryptFailed\": \"请求解密失败\",\n  \"serv_transportEncryptFailed\": \"响应加密失败\",\n  \"serv_transportKeyExchangeFailed\": \"密钥协商失败\"\n}\n","/**\n * @h-ai/serv — i18n 工具\n *\n * Serv 模块的国际化消息工具，从 @h-ai/core 调用 i18n API。\n * 与 kit-i18n 结构对齐，便于跨包统一维护。\n * @module serv-i18n\n */\n\nimport { core } from '@h-ai/core'\nimport messagesEnUS from '../messages/en-US.json'\nimport messagesZhCN from '../messages/zh-CN.json'\n\ntype ServMessageKey = keyof typeof messagesZhCN\n\nconst SUPPORTED_SERV_LOCALES = ['zh-CN', 'en-US'] as const\nconst DEFAULT_SERV_LOCALE = 'zh-CN'\n\n/**\n * 规范化 serv 请求 locale。\n *\n * 支持：\n * - 完整 locale：`zh-CN` / `en-US`\n * - 简写：`zh` / `en`\n * - `Accept-Language` 风格值：`en-US,en;q=0.9`\n *\n * 未识别时回退到默认 `zh-CN`。\n */\nexport function normalizeServLocale(locale: string | undefined): string {\n  const candidate = locale?.split(',')[0]?.trim()\n  if (!candidate)\n    return DEFAULT_SERV_LOCALE\n\n  const exact = SUPPORTED_SERV_LOCALES.find(item => item.toLowerCase() === candidate.toLowerCase())\n  if (exact)\n    return exact\n\n  const baseLanguage = candidate.split('-')[0]?.toLowerCase()\n  if (baseLanguage === 'en')\n    return 'en-US'\n  if (baseLanguage === 'zh')\n    return 'zh-CN'\n\n  return DEFAULT_SERV_LOCALE\n}\n\n/**\n * 获取 Serv 模块的 i18n 消息。\n *\n * 单次调用可通过 `options.locale` 指定该次调用使用的语言，\n * 用于在请求处理过程中根据 `Accept-Language` 头本地化错误消息，\n * 而不污染全局 locale（多并发请求安全）。\n *\n * @example\n * ```ts\n * // 使用全局 locale\n * servM('serv_validationRequired')\n *\n * // 使用请求自身的 locale\n * servM('serv_validationStringMin', { locale: 'en-US', params: { min: 3 } })\n * ```\n */\nexport const servM\n  = core.i18n.createMessageGetter<ServMessageKey>({ 'zh-CN': messagesZhCN, 'en-US': messagesEnUS })\n\nexport type { ServMessageKey }\n","/**\n * @h-ai/serv — procedure 认证与授权 guard\n *\n * 将认证、权限、角色及异常映射合并为单个 handler 包装层，并在类型上把\n * `context.session` 收窄为非空。\n *\n * @module pipelines/serv-pipeline-guard\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport type { ErrorMap, Meta, ProcedureHandler } from '@orpc/server'\nimport type { ServContext } from '../serv-context.js'\nimport type { AuthenticatedServContext } from '../serv-router.js'\nimport { err, HaiCommonError } from '@h-ai/core'\nimport { servM } from '../serv-i18n.js'\n\n/**\n * 通配符权限。仅应授予受信任的超级管理员，可通过任意 permission guard。\n */\nexport const WILDCARD_PERMISSION = '*'\n\n/**\n * 通配符角色。仅应授予受信任的超级管理员，可通过任意 role guard。\n */\nexport const WILDCARD_ROLE = '*'\n\nexport interface ServGuardRequirements {\n  readonly auth?: boolean\n  readonly permissions?: readonly string[]\n  readonly roles?: readonly string[]\n}\n\n/**\n * 将 guard 应用于一个使用 HaiResult 输出的 oRPC handler。\n *\n * 完整保留 oRPC 的 `path`、`procedure`、`signal`、`lastEventId`、`errors` 等\n * options；只在校验成功后把 `context` 收窄为带非空 session 的类型。\n */\nexport function applyServGuards<\n  TContext extends ServContext,\n  TInput,\n  TData,\n  TErrorMap extends ErrorMap,\n  TMeta extends Meta,\n>(\n  requirements: ServGuardRequirements,\n  handler: ProcedureHandler<\n    AuthenticatedServContext<TContext>,\n    TInput,\n    HaiResult<TData>,\n    TErrorMap,\n    TMeta\n  >,\n): ProcedureHandler<TContext, TInput, HaiResult<TData>, TErrorMap, TMeta> {\n  return async (options) => {\n    try {\n      if (!hasAuthenticatedSession(options.context)) {\n        return err(\n          HaiCommonError.UNAUTHORIZED,\n          servM('serv_errorUnauthorized', { locale: options.context.locale }),\n        )\n      }\n\n      const { session } = options.context\n      if (requirements.permissions?.length) {\n        const allowed = session.permissions.includes(WILDCARD_PERMISSION)\n          || requirements.permissions.every(\n            permission => session.permissions.includes(permission),\n          )\n        if (!allowed) {\n          return err(\n            HaiCommonError.FORBIDDEN,\n            servM('serv_errorForbidden', { locale: options.context.locale }),\n          )\n        }\n      }\n\n      if (requirements.roles?.length) {\n        const allowed = session.roles.includes(WILDCARD_ROLE)\n          || requirements.roles.every(\n            role => session.roles.includes(role),\n          )\n        if (!allowed) {\n          return err(\n            HaiCommonError.FORBIDDEN,\n            servM('serv_errorForbidden', { locale: options.context.locale }),\n          )\n        }\n      }\n\n      return await handler({\n        ...options,\n        context: options.context,\n      })\n    }\n    catch (error) {\n      return err(\n        HaiCommonError.INTERNAL_ERROR,\n        servM('serv_errorInternal', { locale: options.context.locale }),\n        error,\n      )\n    }\n  }\n}\n\nfunction hasAuthenticatedSession<TContext extends ServContext>(\n  context: TContext,\n): context is AuthenticatedServContext<TContext> {\n  return context.session !== undefined && context.session !== null\n}\n","/**\n * @h-ai/serv — Pipeline 公共 helper\n *\n * 放置不属于 Hono middleware / route guard 默认实现本身、\n * 但会被多个 pipeline 复用的公共工具。\n * @module pipelines/serv-pipeline-helper\n */\n\nimport type { ServProcedureHandler } from './serv-pipeline-types.js'\nimport { err, HaiCommonError } from '@h-ai/core'\nimport { servM } from '../serv-i18n.js'\n\n/** 构造 `HaiResult` 失败分支同构的 HTTP 错误定义。 */\nexport interface ServErrorBodyDef {\n  readonly code: string | number\n  readonly httpStatus: number\n  readonly system: string\n  readonly module: string\n}\n\n/**\n * 构造与 `HaiResult` 失败分支同构的 HTTP 响应体。\n *\n * - 字段顺序与 `haiResultSchema()` 输出一致，便于客户端统一解析。\n * - 仅暴露最小信息（code/message/httpStatus），避免泄漏内部细节。\n */\nexport function buildHaiErrorBody(def: ServErrorBodyDef, message: string) {\n  return {\n    success: false as const,\n    error: {\n      code: def.code,\n      message,\n      httpStatus: def.httpStatus,\n      system: def.system,\n      module: def.module,\n    },\n  }\n}\n\n/**\n * 捕获未处理异常并转换为 HaiResult。\n *\n * 由 contract router 在注册 handler 时统一应用，业务代码无需手动包装。\n *\n * @param handler - 被包装的 procedure handler\n * @returns 带异常保护的新 handler\n */\nexport function mapHaiError<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput> {\n  return async (options) => {\n    try {\n      return await handler(options)\n    }\n    catch (error) {\n      // 所有未捕获异常统一在这里收口，避免直接把异常冒泡到 HTTP 层。\n      return err(HaiCommonError.INTERNAL_ERROR, servM('serv_errorInternal', { locale: options.context.locale }), error)\n    }\n  }\n}\n","/**\n * @h-ai/serv — contract-first 链式 procedure 实现器\n *\n * 在 oRPC `implement()` 之上提供 route 名只出现一次的链式 DSL。\n * 应用只接触 contract 路径、上下文与 guard，不需要组装 oRPC router 对象。\n *\n * @module serv-router\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport type {\n  Context,\n  ContractProcedure,\n  ContractRouter,\n  ErrorMap,\n  Implementer,\n  InferSchemaInput,\n  InferSchemaOutput,\n  Meta,\n  ProcedureHandler,\n  Router,\n} from '@orpc/server'\nimport type { ServGuardRequirements } from './pipelines/serv-pipeline-guard.js'\nimport type { ServContext } from './serv-context.js'\nimport { implement as orpcImplement } from '@orpc/server'\nimport { applyServGuards } from './pipelines/serv-pipeline-guard.js'\nimport { mapHaiError } from './pipelines/serv-pipeline-helper.js'\n\ntype EmptyContext = Record<never, never>\ntype StringKey<T> = Extract<keyof T, string>\ntype ServContract = ContractRouter<Meta>\n\n/** contract 中所有 procedure 的点分路径。 */\nexport type ServRoutePath<TContract extends ServContract>\n  = TContract extends ContractProcedure<\n    infer _TInputSchema,\n    infer _TOutputSchema,\n    infer _TErrorMap,\n    infer _TMeta\n  >\n    ? never\n    : {\n        [K in StringKey<TContract>]: TContract[K] extends ContractProcedure<\n          infer _TChildInputSchema,\n          infer _TChildOutputSchema,\n          infer _TChildErrorMap,\n          infer _TChildMeta\n        >\n          ? K\n          : TContract[K] extends ServContract\n            ? ServRoutePath<TContract[K]> extends infer TChild extends string\n              ? `${K}.${TChild}`\n              : never\n            : never\n      }[StringKey<TContract>]\n\ntype ContractAtPath<TContract, TPath extends string>\n  = TPath extends `${infer THead}.${infer TTail}`\n    ? THead extends keyof TContract\n      ? ContractAtPath<TContract[THead], TTail>\n      : never\n    : TPath extends keyof TContract\n      ? TContract[TPath]\n      : never\n\ntype RouteContract<\n  TContract extends ServContract,\n  TPath extends ServRoutePath<TContract>,\n> = ContractAtPath<TContract, TPath>\n\n/** `.auth()`、`.permission()`、`.role()` 后的非空会话上下文。 */\nexport type AuthenticatedServContext<TContext extends ServContext = ServContext>\n  = TContext & {\n    readonly session: NonNullable<TContext['session']>\n  }\n\ntype RouteHandler<\n  TRouteContract,\n  TContext extends Context,\n> = TRouteContract extends ContractProcedure<\n  infer TInputSchema,\n  infer TOutputSchema,\n  infer TErrorMap,\n  infer TMeta\n>\n  ? InferSchemaInput<TOutputSchema> extends HaiResult<unknown>\n    ? ProcedureHandler<\n      TContext,\n      InferSchemaOutput<TInputSchema>,\n      InferSchemaInput<TOutputSchema>,\n      TErrorMap,\n      TMeta\n    >\n    : never\n  : never\n\n/** 从 contract procedure 精确推导当前 route 的 HaiResult handler。 */\nexport type ServRouteHandler<\n  TContract extends ServContract,\n  TPath extends ServRoutePath<TContract>,\n  TContext extends Context,\n> = RouteHandler<RouteContract<TContract, TPath>, TContext>\n\ntype ServGuardedRouteHandler<\n  TContract extends ServContract,\n  TPath extends ServRoutePath<TContract>,\n  TContext extends ServContext,\n> = RouteHandler<RouteContract<TContract, TPath>, AuthenticatedServContext<TContext>>\n\ntype NextBuilder<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n  TRemaining extends ServRoutePath<TContract>,\n  TPath extends TRemaining,\n> = ServRouterBuilder<\n  TContract,\n  TInitialContext,\n  TCurrentContext,\n  Exclude<TRemaining, TPath>\n>\n\n/** 尚未声明 guard 的单 route 注册器。 */\nexport interface ServRouteRegistration<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n  TRemaining extends ServRoutePath<TContract>,\n  TPath extends TRemaining,\n> {\n  readonly auth: () => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n  readonly permission: (permission: string) => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n  readonly role: (role: string) => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n}\n\n/** 已声明认证或授权 guard 的单 route 注册器。 */\nexport interface ServGuardedRouteRegistration<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n  TRemaining extends ServRoutePath<TContract>,\n  TPath extends TRemaining,\n> {\n  readonly auth: () => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n  readonly permission: (permission: string) => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n  readonly role: (role: string) => ServGuardedRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n  readonly handle: (\n    handler: ServGuardedRouteHandler<TContract, TPath, TCurrentContext>,\n  ) => NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>\n}\n\ninterface ServRouteMethod<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n  TRemaining extends ServRoutePath<TContract>,\n> {\n  <TPath extends TRemaining>(\n    path: TPath,\n    handler: ServRouteHandler<TContract, TPath, TCurrentContext>,\n  ): NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>\n  <TPath extends TRemaining>(\n    path: TPath,\n  ): ServRouteRegistration<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining,\n    TPath\n  >\n}\n\ntype ServRouterBuilderBuild<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TRemaining,\n> = [TRemaining] extends [never]\n  ? {\n      /** 所有 contract procedures 均实现后才可调用。 */\n      readonly build: () => Router<TContract, TInitialContext>\n    }\n  : {\n      /** 仅供 TypeScript/IDE 展示尚未实现的 route；运行时不存在。 */\n      readonly missingRoutes: TRemaining\n    }\n\n/**\n * 链式 router builder。\n *\n * `TRemaining` 会随着 `.route()` 注册逐步收窄；未实现完整 contract 时没有 `.build()`。\n */\nexport type ServRouterBuilder<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n  TRemaining extends ServRoutePath<TContract> = ServRoutePath<TContract>,\n> = {\n  readonly route: ServRouteMethod<\n    TContract,\n    TInitialContext,\n    TCurrentContext,\n    TRemaining\n  >\n} & ServRouterBuilderBuild<TContract, TInitialContext, TRemaining>\n\n/** hai-framework 链式 contract 实现器。 */\nexport interface ServImplementer<TContract extends ServContract> {\n  readonly context: <TContext extends ServContext>() => ServRouterBuilder<\n    TContract,\n    TContext & EmptyContext,\n    TContext\n  >\n}\n\n/**\n * 创建链式 contract 实现器。\n *\n * @example\n * ```ts\n * serv\n *   .implement(contract)\n *   .context<ServContext>()\n *   .route('info', infoHandler)\n *   .route('echo')\n *   .auth()\n *   .handle(echoHandler)\n *   .build()\n * ```\n */\nexport function implement<TContract extends ServContract>(\n  contract: TContract,\n): ServImplementer<TContract> {\n  return {\n    context: <TContext extends ServContext>() => {\n      const native = orpcImplement(contract).$context<TContext>()\n      return createServRouterBuilder(contract, native)\n    },\n  }\n}\n\nfunction createServRouterBuilder<\n  TContract extends ServContract,\n  TInitialContext extends Context,\n  TCurrentContext extends ServContext,\n>(\n  contract: TContract,\n  implementer: Implementer<TContract, TInitialContext, TCurrentContext>,\n): ServRouterBuilder<TContract, TInitialContext, TCurrentContext> {\n  const runtime = new ServRouterBuilderRuntime(contract, implementer)\n\n  // oRPC 的 contract 泛型只能在编译期表示；运行时 builder 由同一 contract\n  // 创建并逐项校验路径，因此这里将动态实现收敛到唯一的类型边界。\n  return runtime as unknown as ServRouterBuilder<\n    TContract,\n    TInitialContext,\n    TCurrentContext\n  >\n}\n\ntype RuntimeProcedureHandler = ProcedureHandler<\n  ServContext,\n  unknown,\n  HaiResult<unknown>,\n  ErrorMap,\n  Meta\n>\ntype AuthenticatedRuntimeProcedureHandler = ProcedureHandler<\n  AuthenticatedServContext,\n  unknown,\n  HaiResult<unknown>,\n  ErrorMap,\n  Meta\n>\n\nclass ServRouterBuilderRuntime {\n  private readonly expectedPaths: ReadonlySet<string>\n  private readonly implementedRoutes: Record<string, unknown>\n  private readonly registeredPaths = new Set<string>()\n\n  constructor(\n    contract: ServContract,\n    private readonly implementer: object,\n  ) {\n    this.expectedPaths = new Set(collectProcedurePaths(contract))\n    this.implementedRoutes = createRouterShape(contract)\n  }\n\n  route(path: string, handler?: unknown): unknown {\n    if (handler !== undefined)\n      return this.register(path, {}, handler)\n\n    return new ServRouteRegistrationRuntime(this, path)\n  }\n\n  register(path: string, guards: ServGuardRequirements, handler: unknown): this {\n    if (!this.expectedPaths.has(path))\n      throw new TypeError(`Contract path is not implementable: ${path}`)\n    if (this.registeredPaths.has(path))\n      throw new TypeError(`Duplicate procedure implementation: ${path}`)\n    if (typeof handler !== 'function')\n      throw new TypeError(`Procedure handler must be a function: ${path}`)\n\n    const procedureImplementer = getAtPath(this.implementer, path)\n    const implementHandler = getHandlerMethod(procedureImplementer)\n    if (!implementHandler)\n      throw new TypeError(`Contract path is not implementable: ${path}`)\n\n    // 点路径反射会丢失单条 contract 的泛型；路径已由 expectedPaths 校验，\n    // handler 的精确 input/output 则由公开的 ServRouteHandler 在调用侧保证。\n    const safeHandler = hasGuards(guards)\n      ? applyServGuards(guards, handler as AuthenticatedRuntimeProcedureHandler)\n      : mapHaiError(handler as RuntimeProcedureHandler)\n    const implemented = Reflect.apply(\n      implementHandler,\n      procedureImplementer,\n      [safeHandler],\n    )\n\n    setAtPath(this.implementedRoutes, path, implemented)\n    this.registeredPaths.add(path)\n    return this\n  }\n\n  build(): unknown {\n    const missingPaths = [...this.expectedPaths]\n      .filter(path => !this.registeredPaths.has(path))\n      .sort()\n    if (missingPaths.length > 0) {\n      throw new TypeError(\n        `Cannot build router. Missing procedures: ${missingPaths.join(', ')}`,\n      )\n    }\n\n    const routerMethod = Reflect.get(this.implementer, 'router')\n    if (typeof routerMethod !== 'function')\n      throw new TypeError('The oRPC implementer does not expose router()')\n\n    return Reflect.apply(routerMethod, this.implementer, [this.implementedRoutes])\n  }\n}\n\nclass ServRouteRegistrationRuntime {\n  private authRequired = false\n  private readonly permissions = new Set<string>()\n  private readonly roles = new Set<string>()\n\n  constructor(\n    private readonly parent: ServRouterBuilderRuntime,\n    private readonly path: string,\n  ) {}\n\n  auth(): this {\n    this.authRequired = true\n    return this\n  }\n\n  permission(permission: string): this {\n    this.authRequired = true\n    this.permissions.add(permission)\n    return this\n  }\n\n  role(role: string): this {\n    this.authRequired = true\n    this.roles.add(role)\n    return this\n  }\n\n  handle(handler: unknown): ServRouterBuilderRuntime {\n    return this.parent.register(this.path, {\n      auth: this.authRequired,\n      permissions: [...this.permissions],\n      roles: [...this.roles],\n    }, handler)\n  }\n}\n\nfunction hasGuards(guards: ServGuardRequirements): boolean {\n  return guards.auth === true\n    || (guards.permissions?.length ?? 0) > 0\n    || (guards.roles?.length ?? 0) > 0\n}\n\nfunction collectProcedurePaths(\n  contract: ServContract,\n  prefix: readonly string[] = [],\n): string[] {\n  if (isContractProcedure(contract))\n    return prefix.length > 0 ? [prefix.join('.')] : []\n\n  return Object.entries(contract).flatMap(([key, child]) =>\n    collectProcedurePaths(child, [...prefix, key]))\n}\n\nfunction isContractProcedure(contract: ServContract): boolean {\n  return '~orpc' in contract\n}\n\nfunction createRouterShape(contract: ServContract): Record<string, unknown> {\n  const shape: Record<string, unknown> = Object.create(null)\n\n  for (const [key, child] of Object.entries(contract)) {\n    if (!isContractProcedure(child))\n      shape[key] = createRouterShape(child)\n  }\n\n  return shape\n}\n\nfunction getAtPath(root: object, path: string): unknown {\n  let current: unknown = root\n\n  for (const segment of path.split('.')) {\n    if (\n      (typeof current !== 'object' && typeof current !== 'function')\n      || current === null\n      || !(segment in current)\n    ) {\n      return undefined\n    }\n\n    current = Reflect.get(current, segment)\n  }\n\n  return current\n}\n\nfunction setAtPath(root: Record<string, unknown>, path: string, value: unknown): void {\n  const segments = path.split('.')\n  const leaf = segments.pop()\n  if (!leaf)\n    throw new TypeError('Procedure path cannot be empty')\n\n  let current = root\n  for (const segment of segments) {\n    const existing = current[segment]\n    if (existing === undefined) {\n      const child: Record<string, unknown> = Object.create(null)\n      current[segment] = child\n      current = child\n      continue\n    }\n\n    if (!existing || typeof existing !== 'object')\n      throw new TypeError(`Procedure path conflicts with an existing route: ${path}`)\n\n    current = existing as Record<string, unknown>\n  }\n\n  current[leaf] = value\n}\n\nfunction getHandlerMethod(value: unknown): ((handler: unknown) => unknown) | undefined {\n  if ((typeof value !== 'object' && typeof value !== 'function') || value === null)\n    return undefined\n\n  const handler = Reflect.get(value, 'handler')\n  return typeof handler === 'function'\n    ? handler as (handler: unknown) => unknown\n    : undefined\n}\n"]}