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

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 配置
@@ -323,7 +318,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` 正交：
@@ -595,99 +590,6 @@ interface ServNodeServer {
  */
 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 +648,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 +859,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 +888,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, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -1,6 +1,4 @@
-import { WILDCARD_PERMISSION, requirePermission } from './chunk-YQV2OMQK.js';
-import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody } from './chunk-4QBF4PUG.js';
-import { implement } from '@orpc/server';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, normalizeServLocale, buildHaiErrorBody } from './chunk-KIWHKWLD.js';
 import process2 from 'process';
 import { serve } from '@hono/node-server';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
@@ -1329,15 +1327,6 @@ function listen(app, options = {}) {
   }
   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 +1558,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,