@h-ai/serv 0.1.0-alpha.46 → 0.1.0-alpha.48

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, ValidationFormError } from '@h-ai/core';
-import { Router, implement } from '@orpc/server';
 import { AIFunctions, AudioWsStartMessage, AudioFormat } from '@h-ai/ai';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
-import { S as ServSession, a as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-BUrtWoFC.js';
-export { d as CreateServContextInput, N as NativeRefreshTokenTransportConfig, e as RefreshTokenPair } from './serv-context-BUrtWoFC.js';
+import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router, ContractRouter, Context, ContractProcedure, InferSchemaInput, InferSchemaOutput } from '@orpc/server';
+import { S as ServSession, a as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-jc3rZxbj.js';
+export { d as CreateServContextInput, N as NativeRefreshTokenTransportConfig, e as RefreshTokenPair } from './serv-context-jc3rZxbj.js';
 import { MiddlewareHandler } from 'hono';
 import { z, ZodType } from 'zod';
 import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
@@ -55,8 +55,7 @@ interface AudioWsDeps {
 /**
  * @h-ai/serv — Pipeline 共享类型
  *
- * 统一定义 Hono middleware 与 oRPC procedure wrapper 的最小公共类型，
- * 供默认实现与使用方自定义实现复用。
+ * 统一定义 Hono middleware 与 oRPC procedure handler 类型。
  * @module pipelines/serv-pipeline-types
  */
 
@@ -69,17 +68,13 @@ type ServMiddleware = MiddlewareHandler;
  * - 带配置 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>;
+/**
+ * 使用 oRPC 公开 `ProcedureHandler` 定义的 HaiResult procedure handler。
+ *
+ * handler options 完整保留 oRPC 的路径、procedure、signal 与错误构造器信息。
+ */
+type ServProcedureOptions<TInput = unknown, TContext extends ServContext = ServContext> = ProcedureHandlerOptions<TContext, TInput, ORPCErrorConstructorMap<ErrorMap>, Meta>;
+type ServProcedureHandler<TInput, TOutput, TContext extends ServContext = ServContext> = ProcedureHandler<TContext, TInput, HaiResult<TOutput>, ErrorMap, Meta>;
 
 /**
  * @h-ai/serv — HTTP 配置
@@ -89,6 +84,13 @@ type ServGuardedProcedureWrapper<TRequirement> = <TInput, TOutput>(requirement:
  * @module serv-config
  */
 
+/** 服务器监听配置（对应 `config/_serv.yml` 的 `server`）。 */
+interface ServServerConfig {
+    readonly host: string;
+    readonly port: number;
+}
+/** `config/_serv.yml` 中的服务器监听输入类型。 */
+type ServServerConfigInput = Partial<ServServerConfig>;
 /** OpenAPI JSON endpoint 配置。 */
 interface ServOpenAPIHttpConfig {
     readonly path: `/${string}`;
@@ -134,6 +136,7 @@ interface ServHttpConfig {
 }
 /** `config/_serv.yml` 的顶层配置结构。 */
 interface ServConfig {
+    readonly server: ServServerConfig;
     readonly http: ServHttpConfig;
     readonly cors: ServCorsRuntimeConfig;
     readonly transport: false | ServTransportRuntimeConfig;
@@ -156,12 +159,17 @@ type ServHttpConfigInput = Partial<{
 }>;
 /** `config/_serv.yml` 的顶层输入类型。 */
 interface ServConfigInput {
+    readonly server?: ServServerConfigInput;
     readonly http?: ServHttpConfigInput;
     readonly cors?: ServCorsRuntimeConfigInput;
     readonly transport?: false | ServTransportRuntimeConfigInput;
 }
 /** `config/_serv.yml` 对应的配置 Schema。 */
 declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
+    server: z.ZodOptional<z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     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<{
@@ -199,10 +207,15 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         maxClients: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>, z.ZodTransform<{
+    server: ServServerConfig;
     http: ServHttpConfig;
     cors: ServCorsRuntimeConfig;
     transport: false | ServTransportRuntimeConfig;
 }, {
+    server?: {
+        host: string;
+        port: number;
+    } | undefined;
     http?: {
         apiPrefix: `/api/${string}`;
         openapi: false | {
@@ -323,7 +336,7 @@ interface ServHttpApp {
  * **认证 / 会话填充设计**（遵循最小知识原则）：
  *
  * - **`iam`**（推荐）：单一顶层引用。提供后 serv 自动：
- *   1. 使用 `iam.session.verifyToken` 填充 `context.session` → `requireAuth/Permission/Role` 生效
+ *   1. 使用 `iam.session.verifyToken` 填充 `context.session` → route guard 生效
  *   2. 若同时启用 `refreshCookie`，使用 `iam.session.refresh` 实现 refresh token 轮换
  *
  * - **`refreshCookie`**（可选）：浏览器默认用 httpOnly cookie；受信原生客户端可配置 body 通道。与 `iam` 正交：
@@ -534,12 +547,13 @@ declare function toFetch(app: ServHttpApp): ServFetchHandler;
 interface ServListenOptions {
     /**
      * 监听端口。
-     * 优先级：显式值 > `PORT` 环境变量 > 默认 `3000`。
+     * 优先级：显式值 > 默认 `3000`。
+     * 环境变量 / 配置文件的 host/port 由 `serv` 配置（`server`）解析后由应用显式传入。
      */
     readonly port?: number;
     /**
      * 监听地址。
-     * 优先级：显式值 > `HOST` 环境变量 > 默认 `'127.0.0.1'`（仅本机可达）。
+     * 优先级：显式值 > 默认 `'127.0.0.1'`（仅本机可达）。
      *
      * - `'127.0.0.1'`：仅本机（推荐用于本地开发、容器内 sidecar、反向代理后端）
      * - `'0.0.0.0'`：监听所有 IPv4 网卡（容器对外暴露、需公网/内网访问）
@@ -574,7 +588,8 @@ interface ServNodeServer {
 /**
  * 在 Node.js 中启动 ServHttpApp。
  *
- * 默认监听 `127.0.0.1:3000`（可通过 `PORT` / `HOST` 环境变量覆盖）。
+ * 默认监听 `127.0.0.1:3000`；host/port 建议由应用从 `serv` 配置的 `server`
+ *（支持 `HOST` / `PORT` 环境变量覆盖，环境变量高于配置文件）解析后显式传入。
  * 传入 `onClose` 后自动注册 SIGINT/SIGTERM 优雅关闭，应用层无需手动处理信号。
  *
  * @param app - `serv.createApp()` 返回的 HTTP app
@@ -583,111 +598,18 @@ interface ServNodeServer {
  *
  * @example
  * ```ts
- * // 最简：读取 PORT / HOST 环境变量，自动优雅关闭
+ * // host/port 来自已解析的 serv 配置（env > 配置文件 > 默认）
+ * const { server } = core.config.getOrThrow<ServConfig>('serv')
  * serv.listen(app, {
+ *   host: server.host,
+ *   port: server.port,
  *   onListening: info => logger.info('listening', { port: info.port }),
  *   onClose: closeApp,
  * })
- *
- * // 容器对外暴露
- * serv.listen(app, { host: '0.0.0.0', onClose: closeApp })
  * ```
  */
 declare function listen(app: ServHttpApp, options?: ServListenOptions): ServNodeServer;
 
-/**
- * @h-ai/serv — Pipeline 公共 helper
- *
- * 放置不属于 Hono middleware / oRPC wrapper 默认实现本身、
- * 但会被多个 pipeline 复用的公共工具。
- * @module pipelines/serv-pipeline-helper
- */
-
-/**
- * 捕获未处理异常并转换为 HaiResult。
- *
- * 虽然它不是 middleware / 鉴权 wrapper，但属于所有 procedure pipeline
- * 都可能复用的“公共包装能力”，因此与 `buildHaiErrorBody()` 一起放在 helper 中。
- *
- * @param handler - 被包装的 procedure handler
- * @returns 带异常保护的新 handler
- *
- * @example
- * ```ts
- * const safeHandler = serv.mapHaiError(myHandler)
- * ```
- */
-declare function mapHaiError<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requireAuth 默认实现
- * @module pipelines/serv-pipeline-require-auth
- */
-
-/**
- * 需要已验证会话的 procedure 包装器。
- *
- * `context.session` 由 `buildAuthContextFactory(verifyToken)`（或 `serv.createApp({ iam })` 自动启用）填充。
- * token 不存在或无效（verifyToken 失败）时 `session` 均为 `undefined`，统一返回 401 UNAUTHORIZED。
- * 内置调用 `mapHaiError`，无需外层再次封装。
- *
- * @param handler - 被包装的 procedure handler
- * @returns 带认证检查的新 handler
- *
- * @example
- * ```ts
- * const protectedHandler = serv.requireAuth(myHandler)
- * ```
- */
-declare function requireAuth<TInput, TOutput>(handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requirePermission 默认实现
- * @module pipelines/serv-pipeline-require-permission
- */
-
-/**
- * 需要指定权限的 procedure 包装器。
- *
- * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.permissions`。
- * 拥有 {@link WILDCARD_PERMISSION}（`'*'`）的用户自动通过所有权限检查。
- *
- * @param permission - 所需权限字符串（如 `'iam.users.read'`）
- * @param handler - 被包装的 procedure handler
- * @returns 带权限检查的新 handler
- *
- * @example
- * ```ts
- * const adminHandler = serv.requirePermission('iam.users.write', myHandler)
- * ```
- */
-declare function requirePermission<TInput, TOutput>(permission: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
-/**
- * @h-ai/serv — requireRole 默认实现
- * @module pipelines/serv-pipeline-require-role
- */
-
-/**
- * 需要指定角色的 procedure 包装器。
- *
- * 内置调用 `requireAuth`，在验证 Token 后进一步匹配 `session.roles`。
- * 拥有 {@link WILDCARD_ROLE}（`'*'`）的用户自动通过所有角色检查。
- *
- * **使用建议**：优先使用 {@link requirePermission}（基于行为的细粒度授权）；
- * `requireRole` 适用于按角色分流的粗粒度路由（如 `'admin'` 专属入口）。
- *
- * @param role - 所需角色字符串（如 `'admin'`）
- * @param handler - 被包装的 procedure handler
- * @returns 带角色检查的新 handler
- *
- * @example
- * ```ts
- * const adminOnly = serv.requireRole('admin', myHandler)
- * ```
- */
-declare function requireRole<TInput, TOutput>(role: string, handler: ServProcedureHandler<TInput, TOutput>): ServProcedureHandler<TInput, TOutput>;
-
 /**
  * @h-ai/serv — CORS middleware
  *
@@ -746,6 +668,86 @@ interface GenerateOpenAPISpecOptions {
  */
 declare function generateSpec(contract: AnyContractRouter, options?: GenerateOpenAPISpecOptions): Promise<OpenAPI.Document>;
 
+/**
+ * @h-ai/serv — contract-first 链式 procedure 实现器
+ *
+ * 在 oRPC `implement()` 之上提供 route 名只出现一次的链式 DSL。
+ * 应用只接触 contract 路径、上下文与 guard，不需要组装 oRPC router 对象。
+ *
+ * @module serv-router
+ */
+
+type EmptyContext = Record<never, never>;
+type StringKey<T> = Extract<keyof T, string>;
+type ServContract = ContractRouter<Meta>;
+/** contract 中所有 procedure 的点分路径。 */
+type ServRoutePath<TContract extends ServContract> = TContract extends ContractProcedure<infer _TInputSchema, infer _TOutputSchema, infer _TErrorMap, infer _TMeta> ? never : {
+    [K in StringKey<TContract>]: TContract[K] extends ContractProcedure<infer _TChildInputSchema, infer _TChildOutputSchema, infer _TChildErrorMap, infer _TChildMeta> ? K : TContract[K] extends ServContract ? ServRoutePath<TContract[K]> extends infer TChild extends string ? `${K}.${TChild}` : never : never;
+}[StringKey<TContract>];
+type ContractAtPath<TContract, TPath extends string> = TPath extends `${infer THead}.${infer TTail}` ? THead extends keyof TContract ? ContractAtPath<TContract[THead], TTail> : never : TPath extends keyof TContract ? TContract[TPath] : never;
+type RouteContract<TContract extends ServContract, TPath extends ServRoutePath<TContract>> = ContractAtPath<TContract, TPath>;
+/** `.auth()`、`.permission()`、`.role()` 后的非空会话上下文。 */
+type AuthenticatedServContext<TContext extends ServContext = ServContext> = TContext & {
+    readonly session: NonNullable<TContext['session']>;
+};
+type RouteHandler<TRouteContract, TContext extends Context> = TRouteContract extends ContractProcedure<infer TInputSchema, infer TOutputSchema, infer TErrorMap, infer TMeta> ? InferSchemaInput<TOutputSchema> extends HaiResult<unknown> ? ProcedureHandler<TContext, InferSchemaOutput<TInputSchema>, InferSchemaInput<TOutputSchema>, TErrorMap, TMeta> : never : never;
+/** 从 contract procedure 精确推导当前 route 的 HaiResult handler。 */
+type ServRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends Context> = RouteHandler<RouteContract<TContract, TPath>, TContext>;
+type ServGuardedRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends ServContext> = RouteHandler<RouteContract<TContract, TPath>, AuthenticatedServContext<TContext>>;
+type NextBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> = ServRouterBuilder<TContract, TInitialContext, TCurrentContext, Exclude<TRemaining, TPath>>;
+/** 尚未声明 guard 的单 route 注册器。 */
+interface ServRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
+    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+/** 已声明认证或授权 guard 的单 route 注册器。 */
+interface ServGuardedRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
+    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly handle: (handler: ServGuardedRouteHandler<TContract, TPath, TCurrentContext>) => NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+interface ServRouteMethod<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>> {
+    <TPath extends TRemaining>(path: TPath, handler: ServRouteHandler<TContract, TPath, TCurrentContext>): NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    <TPath extends TRemaining>(path: TPath): ServRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+type ServRouterBuilderBuild<TContract extends ServContract, TInitialContext extends Context, TRemaining> = [TRemaining] extends [never] ? {
+    /** 所有 contract procedures 均实现后才可调用。 */
+    readonly build: () => Router<TContract, TInitialContext>;
+} : {
+    /** 仅供 TypeScript/IDE 展示尚未实现的 route；运行时不存在。 */
+    readonly missingRoutes: TRemaining;
+};
+/**
+ * 链式 router builder。
+ *
+ * `TRemaining` 会随着 `.route()` 注册逐步收窄；未实现完整 contract 时没有 `.build()`。
+ */
+type ServRouterBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract> = ServRoutePath<TContract>> = {
+    readonly route: ServRouteMethod<TContract, TInitialContext, TCurrentContext, TRemaining>;
+} & ServRouterBuilderBuild<TContract, TInitialContext, TRemaining>;
+/** hai-framework 链式 contract 实现器。 */
+interface ServImplementer<TContract extends ServContract> {
+    readonly context: <TContext extends ServContext>() => ServRouterBuilder<TContract, TContext & EmptyContext, TContext>;
+}
+/**
+ * 创建链式 contract 实现器。
+ *
+ * @example
+ * ```ts
+ * serv
+ *   .implement(contract)
+ *   .context<ServContext>()
+ *   .route('info', infoHandler)
+ *   .route('echo')
+ *   .auth()
+ *   .handle(echoHandler)
+ *   .build()
+ * ```
+ */
+declare function implement<TContract extends ServContract>(contract: TContract): ServImplementer<TContract>;
+
 /**
  * @h-ai/serv — 部署环境 HTTP 安全策略
  *
@@ -877,12 +879,15 @@ declare function resolveRequestLocale(headers: Headers | Record<string, string |
  *
  * 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
- *   // ...
- * })
+ * export const procedures = serv
+ *   .implement(contract)
+ *   .context<ServContext>()
+ *   .route('profile.update', ({ input, context }) => {
+ *     const result = serv.validateInputOrFail(Schema, input, context.locale)
+ *     if (!result.success) return result
+ *     return profileService.update(result.data)
+ *   })
+ *   .build()
  * ```
  *
  * @param schema - Zod schema
@@ -903,16 +908,11 @@ declare const serv: {
     storageAssets: typeof storageAssets;
     createRuntimeSecurityPolicy: typeof createRuntimeSecurityPolicy;
     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 AudioTicketGrant, type AudioTicketVerification, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+export { type AudioTicketGrant, type AudioTicketVerification, type AuthenticatedServContext, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServImplementer, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServRouteHandler, type ServRoutePath, type ServRouterBuilder, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -1,7 +1,5 @@
-import { WILDCARD_PERMISSION, requirePermission } from './chunk-YQV2OMQK.js';
-import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody } from './chunk-4QBF4PUG.js';
-import { implement } from '@orpc/server';
-import process2 from 'process';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, normalizeServLocale, buildHaiErrorBody } from './chunk-KIWHKWLD.js';
+import process from 'process';
 import { serve } from '@hono/node-server';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { core, ok, err, HaiCommonError } from '@h-ai/core';
@@ -662,6 +660,10 @@ var TransportRuntimeConfigInputSchema = z.union([
     maxClients: z.number().int().positive().default(1e4)
   })
 ]);
+var ServerConfigInputSchema = z.object({
+  host: z.string().min(1).default("127.0.0.1"),
+  port: z.number().int().min(1).max(65535).default(3e3)
+});
 var CorsRuntimeConfigInputSchema = z.object({
   origin: z.string().optional(),
   nativeOrigins: z.string().optional(),
@@ -677,14 +679,32 @@ var ServHttpConfigInputSchema = z.object({
   rpc: RpcHttpConfigInputSchema.default(false)
 });
 var ServConfigSchema = z.object({
+  server: ServerConfigInputSchema.optional(),
   http: ServHttpConfigInputSchema.optional(),
   cors: CorsRuntimeConfigInputSchema.optional(),
   transport: TransportRuntimeConfigInputSchema.optional()
-}).transform(({ http, cors: cors2, transport }) => ({
+}).transform(({ server, http, cors: cors2, transport }) => ({
+  server: resolveServServerConfig(server ?? {}),
   http: resolveServHttpConfig(http ?? {}),
   cors: resolveServCorsRuntimeConfig(cors2 ?? {}),
   transport: resolveServTransportRuntimeConfig(transport ?? false)
 }));
+function readServerEnvOverride() {
+  const override = {};
+  const host = process.env.HOST;
+  if (host)
+    override.host = host;
+  const rawPort = process.env.PORT;
+  if (rawPort) {
+    const port = Number(rawPort);
+    if (Number.isInteger(port) && port >= 1 && port <= 65535)
+      override.port = port;
+  }
+  return override;
+}
+function resolveServServerConfig(input = {}) {
+  return { ...ServerConfigInputSchema.parse(input), ...readServerEnvOverride() };
+}
 function resolveServHttpConfig(input = {}) {
   return ServHttpConfigInputSchema.parse(input);
 }
@@ -757,7 +777,7 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
   return {
     cookieName: config.cookieName ?? "hai_refresh_token",
     maxAge: config.maxAge ?? 30 * 24 * 3600,
-    isSecure: config.secure ?? process2.env.NODE_ENV === "production",
+    isSecure: config.secure ?? process.env.NODE_ENV === "production",
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_PATHS.refresh}`,
     onRefresh,
     nativeTokenTransport: config.nativeTokenTransport
@@ -1288,8 +1308,8 @@ function isOrpcValidationErrorPayload(value) {
 var DEFAULT_SERV_HOST = "127.0.0.1";
 var DEFAULT_SERV_PORT = 3e3;
 function listen(app, options = {}) {
-  const host = options.host ?? process2.env.HOST ?? DEFAULT_SERV_HOST;
-  const port = options.port ?? (process2.env.PORT ? Number(process2.env.PORT) : DEFAULT_SERV_PORT);
+  const host = options.host ?? DEFAULT_SERV_HOST;
+  const port = options.port ?? DEFAULT_SERV_PORT;
   const server = serve(
     { fetch: app.fetch, hostname: host, port },
     options.onListening
@@ -1324,20 +1344,11 @@ function listen(app, options = {}) {
       } catch {
       }
     };
-    process2.once("SIGINT", () => void shutdown());
-    process2.once("SIGTERM", () => void shutdown());
+    process.once("SIGINT", () => void shutdown());
+    process.once("SIGTERM", () => void shutdown());
   }
   return handle;
 }
-var WILDCARD_ROLE = "*";
-function requireRole(role, handler) {
-  return requireAuth(async (options) => {
-    const roles = options.context.session?.roles ?? [];
-    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
-      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
-    return handler(options);
-  });
-}
 
 // src/serv-cors.ts
 var DEFAULT_CORS_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE", "OPTIONS"];
@@ -1569,14 +1580,9 @@ var serv = {
   createRuntimeSecurityPolicy,
   // OpenAPI / 导出
   generateSpec,
-  // Procedure 装配（contract 路由定义统一使用 `apiContract.route`）。
-  /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
+  // Contract procedure 装配。
   implement,
-  // oRPC procedure 包装器
-  requireAuth,
-  requirePermission,
-  requireRole,
-  mapHaiError,
+  // Procedure 工具；认证与授权统一由 route 链声明。
   validateInputOrFail,
   // 通配符常量
   WILDCARD_PERMISSION,