@h-ai/serv 1.0.0-beta.2 → 1.0.0-beta.3

package/README.en.md

@@ -18,7 +18,7 @@ hai-framework's API service runtime: a stable public HTTP App abstraction that m
 - Default feature procedures: `createIamProcedures()`, `createStorageProcedures()`, `createAiProcedures()`.
 - `build()` synchronously returns a plain router, so nested default feature procedures can be selected directly. Match the mounted contract to the selected procedures; unselected routes stay unavailable.
 - Missing routes return localized HaiResult JSON with HTTP 404. Transport encryption preserves that status instead of producing a 500 for a non-JSON response.
-- Built-in security headers and health checks; optional OpenAPI JSON, Scalar docs, and internal RPC endpoints.
+- Built-in security headers and health checks; optional OpenAPI JSON, Scalar docs.
 - Optional transport encryption: `serv.createApp({ transport: { crypto, serverKeyRing, keyStore } })` mounts key exchange and request/response encryption automatically.
 - Optional audio: `serv.createApp({ audio: { ai, verifyTicket, authorize } })` mounts a unified audio WebSocket. Connections authenticate immediately with one-time tickets (`{ session, grant? }`, separate pre-auth timeout). Every frame uses runtime Zod validation and a strict state machine, with input/queue/send-buffer backpressure and cascading cancellation. Authorization verifies operations, models, voices, quotas, and concurrency on the server.
 
@@ -102,7 +102,7 @@ const handler = serv.toFetch(app)
 export default { fetch: handler }
 ```
 
-Node `serv.listen()` supplies the socket peer address. Forwarded headers are ignored by default. Only proxy IPs/CIDRs in `http.trustedProxies` may supply them: XFF is walked from right to left until the first untrusted address; content to the left of that address is ignored. An invalid or excessively long trusted chain leaves IP undefined rather than promoting the proxy to client identity. Proxies must sanitize or append forwarded headers. Fetch platforms explicitly provide a trusted peer through `app.fetch(request, { remoteAddress: platformPeerAddress })`; without metadata IP is undefined. Do not copy arbitrary headers into metadata. Custom `createContext(input)` forwards the complete input to preserve resolved `input.ip`. Internal RPC checks the connection peer.
+Node `serv.listen()` supplies the socket peer address. Forwarded headers are ignored by default. Only proxy IPs/CIDRs in `http.trustedProxies` may supply them: XFF is walked from right to left until the first untrusted address; content to the left of that address is ignored. An invalid or excessively long trusted chain leaves IP undefined rather than promoting the proxy to client identity. Proxies must sanitize or append forwarded headers. Fetch platforms explicitly provide a trusted peer through `app.fetch(request, { remoteAddress: platformPeerAddress })`; without metadata IP is undefined. Do not copy arbitrary headers into metadata. Custom `createContext(input)` forwards the complete input to preserve resolved `input.ip`.
 
 toFetch constructs Request(input, init) for Request, URL and string inputs, applying RequestInit overrides including method, headers, body and signal without mutating input fields. Consumed or locked bodies and invalid body combinations reject the returned Promise. Cancellation before dispatch skips the handler; in-flight cancellation ends the caller wait and reaches the app through the effective signal. Listeners are released on completion, failure or cancellation, and a discarded late response body is cancelled. Cancellation cannot roll back external effects already started; after Response delivery the app owns streaming cleanup through request.signal.
 
@@ -355,7 +355,7 @@ Execution order is fixed:
 2. Built-in CORS response wrapping; access checks for key exchange and preflight.
 3. Built-in `transport`, if enabled, and request access checks.
 4. Your `middlewares`.
-5. health / refresh-cookie / OpenAPI / RPC / docs / oRPC routes
+5. health / refresh-cookie / OpenAPI / docs / oRPC routes
 
 Notes:
 
@@ -426,7 +426,7 @@ Public API boundaries:
 
 - `src/pipelines/*` holds internal defaults and is not a public subpath API.
 - The stable application-facing entry remains `@h-ai/serv`.
-- Internal helpers such as `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` are not documented as separate subpath exports.
+- Internal helpers such as `securityHeaders` / `buildHaiErrorBody` are not documented as separate subpath exports.
 
 #### httpOnly cookie authentication (recommended for production)
 
@@ -489,7 +489,7 @@ await apiClient.init({
 
 ### API overview
 
-- `serv.createApp(options)`: create the HTTP App with custom middleware, health checks, OpenAPI, optional docs, and RPC.
+- `serv.createApp(options)`: create the HTTP App with custom middleware, health checks, OpenAPI, optional docs.
 - `serv.parseRequestContext({ request })`: extract Bearer token + requestId without populating session.
 - `serv.listen(app, options)`: start Node.js HTTP service; return `{ server, address, close }`.
 - `serv.toFetch(app)`: wrap as a standard `fetch(Request)` handler.
@@ -574,7 +574,6 @@ http:
   health:
     path: /health
     readyPath: /ready
-  rpc: false
 
 cors:
   origin: https://app.example.com
@@ -601,11 +600,12 @@ transport:
 
 `ServHttpConfigInput`：
 
+Native RPC endpoints, `HAI_SERV_HTTP_RPC` and `ServRpcHttpConfig` have been removed. Existing OpenAPI/REST APIs, `api-client`, and the oRPC contracts and procedures remain supported.
+
 - `apiPrefix`: defaults to `/api/v1`.
 - `health`: defaults to `{ path: '/health', readyPath: '/ready' }`.
 - `openapi`: defaults to `false`; enable with `{ path: '/openapi.json' }`.
-- `docs`: defaults to `false`; enable with `{ path: '/docs' }` (requires `openapi`). It mounts `/_hai/scalar.js` from the `@scalar/api-reference` browser bundle for local Scalar UI without an external CDN.
-- `rpc`: defaults to `false`; enable with `{ prefix: '/rpc', access: 'loopback' | 'private-network' | 'gateway-only', gatewayHeader?, gatewaySecret? }`.
+- `docs`: defaults to `false`; enable with `{ path: '/docs' }`. Scalar is mounted as `_hai/scalar.js` in the document directory (default `/_hai/scalar.js`), without an external CDN. Script and spec URLs are relative. When a gateway preserves a prefix, place docs and OpenAPI paths within it; stripping a prefix also works. Backend `requireAuth` checks remain enforced.
 - `cors`: configured origins, credentials, allowedHeaders, and exposedHeaders; mount through `serv.cors(...)`.
 - `transport`: top-level `config/_serv.yml` option passed as `servConfig.transport` to `createApp({ transport })`; default key exchange subpath is `/_hai/key-exchange`.
 
@@ -652,7 +652,7 @@ createIamProcedures({ iam }) implements public config, password/LDAP/OTP login,
 
 Ordinary procedures return authentication, authorization, business failures and caught handler exceptions as HaiResult over HTTP 200 by default. `error.httpStatus` is domain-error metadata and does not change the response status. Clients must check `success` and `error.code`: an unauthenticated failure has `error.httpStatus=401`, while database query failures or INTERNAL_ERROR have 500.
 
-oRPC contract input validation fails before procedures with HTTP 400 and a localized body containing `error.httpStatus=400` and field errors. Procedure-level `serv.validateInputOrFail` failures remain HTTP 200. HTTP middleware, refresh-cookie, OpenAPI/RPC access checks and transport protocol failures follow their own HTTP response contracts. api-client refreshes after an actual HTTP 401 or a valid failed HaiResult over HTTP 200 (`success=false`, string `error.code/message` and `error.httpStatus=401`) and retries once on success. Built-in login and registration and the configured refresh path are excluded; 403/500 do not trigger refresh. With transport enabled, refresh and retry share the encrypted fetch path.
+oRPC contract input validation fails before procedures with HTTP 400 and a localized body containing `error.httpStatus=400` and field errors. Procedure-level `serv.validateInputOrFail` failures remain HTTP 200. HTTP middleware, refresh-cookie, OpenAPI access checks and transport protocol failures follow their own HTTP response contracts. api-client refreshes after an actual HTTP 401 or a valid failed HaiResult over HTTP 200 (`success=false`, string `error.code/message` and `error.httpStatus=401`) and retries once on success. Built-in login and registration and the configured refresh path are excluded; 403/500 do not trigger refresh. With transport enabled, refresh and retry share the encrypted fetch path.
 
 - All default procedures return `HaiResult<T>`; clients check `result.success`.
 - Authentication failure → `HaiCommonError.UNAUTHORIZED`, localized by `.auth()` using `context.locale`.

package/README.ja.md

@@ -18,7 +18,7 @@ hai-framework の API サービスランタイム。公開 HTTP App 抽象を通
 - 既定の機能 procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`。
 - `build()` は通常の router を同期的に返すため、標準 feature のネストした procedures を直接選択できます。接続する contract と procedures を一致させ、未選択の入口は公開しません。
 - 存在しないルートは翻訳された HaiResult JSON と HTTP 404 を返します。通信暗号化でも 404 を保ち、非 JSON 応答による 500 にしません。
-- 安全な応答ヘッダー・ヘルスチェックを内蔵し、OpenAPI JSON・Scalar 文書・内部 RPC endpoint は任意。
+- 安全な応答ヘッダー・ヘルスチェックを内蔵し、OpenAPI JSON・Scalar 文書・
 - 任意の通信暗号化：`serv.createApp({ transport: { crypto, serverKeyRing, keyStore } })` で鍵交換とリクエスト・レスポンスの暗号化を自動接続。
 - 任意の音声入口：`serv.createApp({ audio: { ai, verifyTicket, authorize } })` が共通 WebSocket を接続します。接続直後に単回 ticket で認証（`{ session, grant? }`、独立した事前認証 timeout）。各フレームを Zod と厳密な状態機械で検証し、入力・キュー・送信バッファの背圧と連鎖キャンセルを管理します。サーバーの認可処理で操作・モデル・声・割当量・同時使用数を確認します。
 
@@ -102,7 +102,7 @@ const handler = serv.toFetch(app)
 export default { fetch: handler }
 ```
 
-Node `serv.listen()` は socket の接続元を自動で渡し、既定では転送ヘッダーを無視します。`http.trustedProxies` の IP/CIDR のみ信頼し、XFF を右から左へ調べ、最初の非信頼アドレスで停止します。その左側は無視します。信頼チェーンが不正・長すぎる場合は IP 未定義となり、代理をクライアントとして扱いません。代理は転送ヘッダーを清掃・追加してください。Fetch は `app.fetch(request, { remoteAddress: platformPeerAddress })` で信頼できる接続元を渡します。メタデータなしは IP 未定義です。任意のヘッダーをコピーしないでください。独自 `createContext(input)` は input 全体を再利用し、解決済み `input.ip` を保持します。内部 RPC は接続元で制限します。
+Node `serv.listen()` は socket の接続元を自動で渡し、既定では転送ヘッダーを無視します。`http.trustedProxies` の IP/CIDR のみ信頼し、XFF を右から左へ調べ、最初の非信頼アドレスで停止します。その左側は無視します。信頼チェーンが不正・長すぎる場合は IP 未定義となり、代理をクライアントとして扱いません。代理は転送ヘッダーを清掃・追加してください。Fetch は `app.fetch(request, { remoteAddress: platformPeerAddress })` で信頼できる接続元を渡します。メタデータなしは IP 未定義です。任意のヘッダーをコピーしないでください。独自 `createContext(input)` は input 全体を再利用し、解決済み `input.ip` を保持します。
 
 toFetch は Request・URL・文字列を標準 Request(input, init) で構築し、入力フィールドを変更せず method・headers・body・signal などを上書きします。消費済み・ロック中の本文や不正な本文指定は返却 Promise を reject します。派発前の取消しは handler を呼ばず、実行中の取消しは呼出側の待機を終了し、有効な signal をアプリへ伝えます。終了・失敗・取消しで listener を外し、取消し後に遅れて返る本文も cancel します。開始済みの外部効果は巻き戻せず、Response 返却後のストリーム終了はアプリが request.signal を消費して管理します。
 
@@ -355,7 +355,7 @@ const app = serv.createApp({
 2. 組み込み CORS 応答処理；鍵交換と preflight のアクセス判定。
 3. 組み込み `transport`（有効時）と各リクエストのアクセス判定。
 4. 独自の `middlewares`。
-5. health / refresh-cookie / OpenAPI / RPC / docs / oRPC routes
+5. health / refresh-cookie / OpenAPI / docs / oRPC routes
 
 補足：
 
@@ -426,7 +426,7 @@ const procedures = serv
 
 - `src/pipelines/*` は内部の既定実装で、公開サブパス API ではありません。
 - アプリ向けの安定した入口はルートの `@h-ai/serv`。
-- `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` などの内部 helper は独立サブパスとして公開しません。
+- `securityHeaders` / `buildHaiErrorBody` などの内部 helper は独立サブパスとして公開しません。
 
 #### httpOnly Cookie 認証（本番推奨）
 
@@ -489,7 +489,7 @@ await apiClient.init({
 
 ### API 一覧
 
-- `serv.createApp(options)`：独自 middleware、ヘルスチェック、OpenAPI、任意の文書・RPC を備えた HTTP App を作成。
+- `serv.createApp(options)`：独自 middleware、ヘルスチェック、OpenAPI、任意の文書を備えた HTTP App を作成。
 - `serv.parseRequestContext({ request })`：Bearer token + requestId を抽出し、session は設定しません。
 - `serv.listen(app, options)`：Node.js HTTP サービスを起動し、`{ server, address, close }` を返す。
 - `serv.toFetch(app)`：標準の `fetch(Request)` handler に変換。
@@ -574,7 +574,6 @@ http:
   health:
     path: /health
     readyPath: /ready
-  rpc: false
 
 cors:
   origin: https://app.example.com
@@ -601,11 +600,12 @@ transport:
 
 `ServHttpConfigInput`：
 
+ネイティブ RPC 入口、`HAI_SERV_HTTP_RPC`、`ServRpcHttpConfig` は削除しました。既存の OpenAPI/REST API、`api-client`、oRPC contract と procedure は引き続き利用できます。
+
 - `apiPrefix`：既定 `/api/v1`。
 - `health`：既定 `{ path: '/health', readyPath: '/ready' }`。
 - `openapi`：既定 `false`。`{ path: '/openapi.json' }` で有効化。
-- `docs`：既定 `false`。`{ path: '/docs' }` で有効化（`openapi` が必要）。`@scalar/api-reference` の browser bundle から `/_hai/scalar.js` を提供し、外部 CDN なしで Scalar UI を使えます。
-- `rpc`：既定 `false`。`{ prefix: '/rpc', access: 'loopback' | 'private-network' | 'gateway-only', gatewayHeader?, gatewaySecret? }` で有効化。
+- `docs`：既定 `false`。`{ path: '/docs' }` で有効化。文書ディレクトリ内の `_hai/scalar.js`（既定 `/_hai/scalar.js`）で Scalar UI を配信し、外部 CDN は不要です。スクリプトと spec の URL は相対指定です。ゲートウェイが接頭辞を保持する場合は docs/openapi も転送範囲内に配置し、接頭辞を除去する構成にも対応します。`requireAuth` は後端で検証します。
 - `cors`：origin・credentials・allowedHeaders・exposedHeaders を設定し、`serv.cors(...)` で接続。
 - `transport`：`config/_serv.yml` のトップレベル設定。`servConfig.transport` を `createApp({ transport })` に渡し、既定の鍵交換サブパスは `/_hai/key-exchange`。
 
@@ -652,7 +652,7 @@ createIamProcedures({ iam }) は公開設定、LDAP/OTP/パスワード、登録
 
 通常の procedure は認証・認可・業務の失敗と捕捉した handler 例外を HaiResult として既定で HTTP 200 で返します。`error.httpStatus` はドメインエラーのメタデータで、HTTP 応答ステータスを変更しません。クライアントは `success` と `error.code` を確認してください。未認証では `error.httpStatus=401`、DB クエリー失敗や INTERNAL_ERROR では 500 です。
 
-oRPC contract の入力検証は procedure の前に失敗すると HTTP 400 となり、ローカライズ済み body に `error.httpStatus=400` とフィールドエラーを含みます。procedure 内の `serv.validateInputOrFail` の失敗は HTTP 200 のままです。HTTP middleware、refresh-cookie、OpenAPI/RPC のアクセス確認、transport のプロトコルエラーは各自の HTTP 応答契約に従います。api-client は実際の HTTP 401、または HTTP 200 の有効な失敗 HaiResult（`success=false`、文字列の `error.code/message`、`error.httpStatus=401`）で自動更新し、成功後に一度だけ再試行します。組み込みのログイン・登録と設定された更新パスは対象外で、403/500 でも更新しません。transport 有効時は更新と再試行も同じ暗号化 fetch を使用します。
+oRPC contract の入力検証は procedure の前に失敗すると HTTP 400 となり、ローカライズ済み body に `error.httpStatus=400` とフィールドエラーを含みます。procedure 内の `serv.validateInputOrFail` の失敗は HTTP 200 のままです。HTTP middleware、refresh-cookie、OpenAPI のアクセス確認、transport のプロトコルエラーは各自の HTTP 応答契約に従います。api-client は実際の HTTP 401、または HTTP 200 の有効な失敗 HaiResult（`success=false`、文字列の `error.code/message`、`error.httpStatus=401`）で自動更新し、成功後に一度だけ再試行します。組み込みのログイン・登録と設定された更新パスは対象外で、403/500 でも更新しません。transport 有効時は更新と再試行も同じ暗号化 fetch を使用します。
 
 - 既定 procedures はすべて `HaiResult<T>` を返し、クライアントで `result.success` を確認。
 - 認証失敗 → `HaiCommonError.UNAUTHORIZED`。`.auth()` が `context.locale` でローカライズ。

package/README.md

@@ -18,7 +18,7 @@ hai-framework 的 API 服务运行时：对外暴露稳定的 HTTP App 抽象，
 - 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
 - `build()` 同步返回普通 router，可按嵌套属性选取默认 feature procedures；挂载的 contract 与所选 procedures 保持一致，未选入口不开放。
 - 缺失路由返回本地化的 HaiResult JSON 404，启用传输加密后保留 404，不误报为非 JSON 响应导致的 500。
-- 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页、可选内部 RPC endpoint
+- 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页
 - 可选传输加密：`serv.createApp({ transport: { crypto, serverKeyRing, keyStore } })` 自动挂载密钥协商与请求/响应加解密
 - 可选语音入口：`serv.createApp({ audio: { ai, verifyTicket, authorize } })` 挂载统一语音 WebSocket；连接建立即用一次性 ticket 鉴权（返回 `{ session, grant? }`，独立预鉴权超时），每帧运行时 Zod 校验 + 严格状态机，输入/积压/发送缓冲背压与级联取消；授权回调负责服务端确认操作、模型、音色、配额与并发占用
 
@@ -102,7 +102,7 @@ const handler = serv.toFetch(app)
 export default { fetch: handler }
 ```
 
-Node `serv.listen()` 自动提供 socket 对端地址；默认忽略 `X-Forwarded-For` / `X-Real-IP`。只有 `http.trustedProxies` 中列出的代理 IP/CIDR 才能提供转发头，XFF 从右向左停在首个不可信地址，忽略其左侧内容；可信链无法解析或过长时 IP 为 undefined，不能回退为代理身份。代理必须清洗或追加转发头。Fetch 平台通过 `app.fetch(request, { remoteAddress: platformPeerAddress })` 显式提供可信对端，缺失时 IP 为 undefined，不能从任意请求头复制。自定义 `createContext(input)` 复用完整 input，保留框架已解析的 `input.ip`。内部 RPC 仍按连接对端限制。
+Node `serv.listen()` 自动提供 socket 对端地址；默认忽略 `X-Forwarded-For` / `X-Real-IP`。只有 `http.trustedProxies` 中列出的代理 IP/CIDR 才能提供转发头，XFF 从右向左停在首个不可信地址，忽略其左侧内容；可信链无法解析或过长时 IP 为 undefined，不能回退为代理身份。代理必须清洗或追加转发头。Fetch 平台通过 `app.fetch(request, { remoteAddress: platformPeerAddress })` 显式提供可信对端，缺失时 IP 为 undefined，不能从任意请求头复制。自定义 `createContext(input)` 复用完整 input，保留框架已解析的 `input.ip`。
 
 toFetch 对 Request、URL、字符串统一调用标准 Request(input, init)，RequestInit 可覆盖 method、headers、body、signal 等字段；不修改原 Request 的字段，正文已消费/锁定或非法正文组合会以 Promise 拒绝。预取消和派发前取消不进入 handler，进行中取消结束调用方等待并把有效 signal 传给应用；监听器在完成/失败/取消后释放，取消后的迟到响应会取消未消费正文。取消不能回滚已经开始的外部副作用；Response 交付后的流由应用监听 request.signal 并自行关闭。
 
@@ -355,7 +355,7 @@ const app = serv.createApp({
 2. 内置 CORS 响应包装；密钥交换和预检先检查访问策略
 3. 内置 `transport`（若启用）及每次请求访问策略
 4. 你的 `middlewares`
-5. health / refresh-cookie / OpenAPI / RPC / docs / oRPC routes
+5. health / refresh-cookie / OpenAPI / docs / oRPC routes
 
 说明：
 
@@ -426,7 +426,7 @@ const procedures = serv
 
 - `src/pipelines/*` 是 `@h-ai/serv` 的内部默认实现目录，不作为公开子路径 API 承诺
 - 对应用层公开的稳定入口仍然是根入口 `@h-ai/serv`
-- `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` 等内部 helper/middleware 不作为单独子路径文档暴露
+- `securityHeaders` / `buildHaiErrorBody` 等内部 helper/middleware 不作为单独子路径文档暴露
 
 #### httpOnly Cookie 认证（推荐生产方案）
 
@@ -489,7 +489,7 @@ await apiClient.init({
 
 ### API 概览
 
-- `serv.createApp(options)`：创建 HTTP App 抽象，挂载自定义 `middlewares`、健康检查、OpenAPI handler、可选文档与 RPC
+- `serv.createApp(options)`：创建 HTTP App 抽象，挂载自定义 `middlewares`、健康检查、OpenAPI handler 与可选文档
 - `serv.parseRequestContext({ request })`：默认上下文解析（提取 Bearer token + requestId，不填充 session）
 - `serv.listen(app, options)`：在 Node.js 启动 HTTP 服务，返回 `{ server, address, close }`
 - `serv.toFetch(app)`：包装为标准 `fetch(Request)` handler
@@ -574,7 +574,6 @@ http:
   health:
     path: /health
     readyPath: /ready
-  rpc: false
 
 cors:
   origin: https://app.example.com
@@ -601,11 +600,12 @@ transport:
 
 `ServHttpConfigInput`：
 
+原生 RPC 入口及 `HAI_SERV_HTTP_RPC`、`ServRpcHttpConfig` 已删除。业务继续使用现有 OpenAPI/REST 路径和 `api-client`，底层 oRPC contract 与 procedure 保留。
+
 - `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? }`
+- `docs`：默认 `false`；启用：`{ path: '/docs' }`；文档目录下自动挂载 `_hai/scalar.js`（默认 `/_hai/scalar.js`），提供本地 Scalar UI，无需外网 CDN。页面中的脚本和 spec 使用相对地址；网关保留前缀时 docs/openapi 都应配置在转发范围内，剥离前缀时仍可用后端原路径。`requireAuth` 仍由后端校验。
 - `cors`：配置文件中的跨端 origin、credentials、allowedHeaders 与 exposedHeaders；应用通过 `serv.cors(...)` 装配。
 - `transport`：`config/_serv.yml` 顶层配置；启用后可通过 `servConfig.transport` 装配到 `createApp({ transport })`，默认密钥协商子路径 `/_hai/key-exchange`
 
@@ -652,7 +652,7 @@ const app = serv.createApp({
 
 普通 procedure 的认证、授权、业务失败和被捕获的 handler 异常都作为 `HaiResult` 输出，默认通过 HTTP 200 返回；`error.httpStatus` 是领域错误元数据，不会自动改写响应状态。客户端必须检查 `success` 与 `error.code`。例如未登录为 `error.httpStatus=401`，数据库查询失败或 INTERNAL_ERROR 为 500。
 
-oRPC contract 输入校验在 procedure 之前失败时返回 HTTP 400，本地化失败体包含 `error.httpStatus=400` 和字段错误；procedure 内 `serv.validateInputOrFail` 返回的失败仍为 HTTP 200。HTTP middleware、refresh-cookie、OpenAPI/RPC 权限与 transport 协议错误另按自身契约返回真实 HTTP 状态。api-client 在真实 HTTP 401 或 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`）后自动刷新，成功后只重试一次；内置登录、注册和配置的刷新路径除外，403/500 不刷新。启用 transport 时刷新和重试复用加密链路。
+oRPC contract 输入校验在 procedure 之前失败时返回 HTTP 400，本地化失败体包含 `error.httpStatus=400` 和字段错误；procedure 内 `serv.validateInputOrFail` 返回的失败仍为 HTTP 200。HTTP middleware、refresh-cookie、OpenAPI 权限与 transport 协议错误另按自身契约返回真实 HTTP 状态。api-client 在真实 HTTP 401 或 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`）后自动刷新，成功后只重试一次；内置登录、注册和配置的刷新路径除外，403/500 不刷新。启用 transport 时刷新和重试复用加密链路。
 
 - Default procedures 全部返回 `HaiResult<T>`，客户端直接判断 `result.success`
 - 认证失败 → `HaiCommonError.UNAUTHORIZED`（由 `.auth()` 按 `context.locale` 本地化）

package/dist/index.d.ts

@@ -138,7 +138,7 @@ type ServProcedureHandler<TInput, TOutput, TContext extends ServContext = ServCo
 /**
  * @h-ai/serv — HTTP 配置
  *
- * 提供用于控制 API 前缀、OpenAPI、docs、健康检查、内部 RPC 与传输加密策略的配置结构，
+ * 提供用于控制 API 前缀、OpenAPI、docs、健康检查与传输加密策略的配置结构，
  * 并由 zod 负责默认值填充与边界校验。
  * @module serv-config
  */
@@ -217,24 +217,6 @@ interface ServHealthHttpConfig {
     readonly path: `/${string}`;
     readonly readyPath?: `/${string}`;
 }
-/**
- * 内部 RPC endpoint 配置。
- *
- * @example
- * ```ts
- * import type { ServRpcHttpConfig } from '@h-ai/serv'
- * import { serv } from '@h-ai/serv'
- *
- * const rpc: ServRpcHttpConfig = { prefix: '/rpc', access: 'loopback' }
- * // 缺少可信连接信息时拒绝；跨节点来源通过明确网关/网络策略控制。
- * ```
- */
-interface ServRpcHttpConfig {
-    readonly prefix: `/${string}`;
-    readonly access: 'loopback' | 'private-network' | 'gateway-only';
-    readonly gatewayHeader?: string;
-    readonly gatewaySecret?: string;
-}
 /**
  * 传输加密运行时配置（对应 `config/_serv.yml`）。
  *
@@ -281,7 +263,7 @@ interface ServCorsRuntimeConfig {
  * import type { ServHttpConfig } from '@h-ai/serv'
  * import { serv } from '@h-ai/serv'
  *
- * const http: ServHttpConfig = { trustedProxies: 'auto', access: false, apiPrefix: '/api/v1', openapi: false, docs: false, health: { path: '/health' }, rpc: false }
+ * const http: ServHttpConfig = { trustedProxies: 'auto', access: false, apiPrefix: '/api/v1', openapi: false, docs: false, health: { path: '/health' } }
  * ```
  */
 interface ServHttpConfig {
@@ -293,7 +275,6 @@ interface ServHttpConfig {
     readonly openapi: false | ServOpenAPIHttpConfig;
     readonly docs: false | ServDocsHttpConfig;
     readonly health: false | ServHealthHttpConfig;
-    readonly rpc: false | ServRpcHttpConfig;
 }
 /**
  * `config/_serv.yml` 的顶层配置结构。
@@ -363,7 +344,6 @@ type ServHttpConfigInput = Partial<{
     readonly openapi: false | Partial<ServOpenAPIHttpConfig>;
     readonly docs: false | Partial<ServDocsHttpConfig>;
     readonly health: false | Partial<ServHealthHttpConfig>;
-    readonly rpc: false | Partial<ServRpcHttpConfig>;
 }>;
 /**
  * `config/_serv.yml` 的顶层输入类型。
@@ -459,16 +439,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
             readyPath: z.ZodDefault<z.ZodOptional<z.ZodCustom<`/${string}`, `/${string}`>>>;
         }, z.core.$strip>]>>;
-        rpc: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
-            prefix: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
-            access: z.ZodDefault<z.ZodEnum<{
-                loopback: "loopback";
-                "private-network": "private-network";
-                "gateway-only": "gateway-only";
-            }>>;
-            gatewayHeader: z.ZodOptional<z.ZodString>;
-            gatewaySecret: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>>;
     }, z.core.$strip>>;
     cors: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
@@ -535,12 +505,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             path: `/${string}`;
             readyPath: `/${string}`;
         };
-        rpc: false | {
-            prefix: `/${string}`;
-            access: "loopback" | "private-network" | "gateway-only";
-            gatewayHeader?: string | undefined;
-            gatewaySecret?: string | undefined;
-        };
     } | undefined;
     cors?: {
         allowedHeaders: string[];
@@ -1371,4 +1335,4 @@ declare const serv: {
     m: (key: "serv_transportPlaintextRequired" | "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationUnexpectedFields" | "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" | "serv_transportBusy" | "serv_feedbackUnavailable", 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 ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, ServRequestMetadata, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+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 ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, ServRequestMetadata, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -2,12 +2,12 @@ import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './c
 import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-I3F7RN4I.js';
 import process from 'process';
 import { upgradeWebSocket, serve } from '@hono/node-server';
+import { posix } from 'path';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { audit } from '@h-ai/audit';
 import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
 import { TRANSPORT_PLAINTEXT_RANGE, createTransportBodyPolicy, TRANSPORT_PROTOCOL, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
-import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { Buffer } from 'buffer';
@@ -548,75 +548,6 @@ function toArrayBuffer(data) {
   new Uint8Array(buffer).set(data);
   return buffer;
 }
-function readRemoteAddress(metadata) {
-  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
-    return void 0;
-  return core.access.normalizeClientIp(metadata.remoteAddress);
-}
-
-// src/pipelines/serv-pipeline-require-internal-rpc.ts
-var pipelineLogger = core.logger.child({ module: "serv", scope: "pipeline" });
-var cachedGetConnInfo;
-async function resolveGetConnInfo() {
-  if (cachedGetConnInfo !== void 0)
-    return cachedGetConnInfo;
-  try {
-    const mod = await import('@hono/node-server/conninfo');
-    cachedGetConnInfo = mod.getConnInfo;
-  } catch (cause) {
-    pipelineLogger.warn("getConnInfo unavailable in this runtime; loopback/private-network access modes will fail closed", { error: cause });
-    cachedGetConnInfo = null;
-  }
-  return cachedGetConnInfo;
-}
-var LOOPBACK_IPS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1", "localhost"]);
-function requireInternalRPC(config) {
-  return async (c, next) => {
-    const locale = resolveRequestLocale(c.req.raw.headers);
-    if (config.access === "gateway-only") {
-      const headerName = config.gatewayHeader ?? "x-hai-internal-rpc";
-      const received = c.req.header(headerName);
-      if (!config.gatewaySecret || !received || !core.string.constantTimeEqual(received, config.gatewaySecret))
-        return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-      return next();
-    }
-    const ip = await getRequestRemoteAddress(c) ?? "";
-    if (config.access === "loopback" && !isLoopbackIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    if (config.access === "private-network" && !isPrivateNetworkIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    return next();
-  };
-}
-async function getRequestRemoteAddress(c) {
-  const remoteAddress = readRemoteAddress(c.env);
-  if (remoteAddress)
-    return remoteAddress;
-  const getConnInfo = await resolveGetConnInfo();
-  if (!getConnInfo)
-    return void 0;
-  try {
-    return getConnInfo(c).remote.address;
-  } catch {
-    return void 0;
-  }
-}
-function normalizeIpAddress(ip) {
-  return ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip;
-}
-function isLoopbackIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  return LOOPBACK_IPS.has(ip) || LOOPBACK_IPS.has(normalized);
-}
-function isPrivateNetworkIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  if (isLoopbackIP(ip))
-    return true;
-  if (normalized.startsWith("10.") || normalized.startsWith("192.168."))
-    return true;
-  const second = Number(normalized.split(".")[1]);
-  return normalized.startsWith("172.") && Number.isInteger(second) && second >= 16 && second <= 31;
-}
 
 // src/pipelines/serv-pipeline-security-headers.ts
 function securityHeaders() {
@@ -627,6 +558,11 @@ function securityHeaders() {
     await next();
   };
 }
+function readRemoteAddress(metadata) {
+  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
+    return void 0;
+  return core.access.normalizeClientIp(metadata.remoteAddress);
+}
 var ApiPrefixSchema = z.custom(
   (value) => typeof value === "string" && value.startsWith("/api/"),
   "apiPrefix must start with /api/"
@@ -653,15 +589,6 @@ var HealthHttpConfigInputSchema = z.union([
     readyPath: AbsolutePathSchema.optional().default("/ready")
   })
 ]);
-var RpcHttpConfigInputSchema = z.union([
-  z.literal(false),
-  z.object({
-    prefix: AbsolutePathSchema.default("/rpc"),
-    access: z.enum(["loopback", "private-network", "gateway-only"]).default("loopback"),
-    gatewayHeader: z.string().optional(),
-    gatewaySecret: z.string().optional()
-  })
-]);
 var TransportRuntimeConfigInputSchema = z.union([
   z.literal(false),
   z.object({
@@ -688,8 +615,7 @@ var ServHttpConfigInputSchema = z.object({
   apiPrefix: ApiPrefixSchema.default("/api/v1"),
   openapi: OpenAPIHttpConfigInputSchema.default(false),
   docs: DocsHttpConfigInputSchema.default(false),
-  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" }),
-  rpc: RpcHttpConfigInputSchema.default(false)
+  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" })
 });
 var ServConfigSchema = z.object({
   server: ServerConfigInputSchema.optional(),
@@ -1402,14 +1328,13 @@ function createApp(options) {
     audioWsServers.set(app, new WebSocketServer({ noServer: true }));
   }
   mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
-  if (http.rpc !== false)
-    mountRPCRoutes(app, options.procedures, http.rpc, createContext);
   if (http.openapi !== false) {
     app.get(http.openapi.path, async (c) => c.json(await getSpec()));
   }
   if (http.docs !== false) {
     const docs = http.docs;
-    app.get(SCALAR_ROUTE, async (c) => {
+    const docsDirectory = docs.path.slice(0, docs.path.lastIndexOf("/") + 1);
+    app.get(`${docsDirectory}${SCALAR_ROUTE.slice(1)}`, async (c) => {
       const content = await getScalarScript();
       if (!content)
         return c.notFound();
@@ -1423,8 +1348,8 @@ function createApp(options) {
         if (!context.session)
           return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
       }
-      const specUrl = http.openapi === false ? void 0 : http.openapi.path;
-      return c.html(createDocsPage(await getSpec(), { specUrl }));
+      const specUrl = http.openapi === false ? void 0 : posix.relative(docsDirectory, http.openapi.path) || ".";
+      return c.html(createDocsPage(await getSpec(), { specUrl, scriptUrl: SCALAR_ROUTE.slice(1) }));
     });
   }
   return app;
@@ -1442,12 +1367,6 @@ function mountOpenAPIRoutes(app, procedures, apiPrefix, createContext) {
   const handler = new OpenAPIHandler(procedures);
   app.on([...API_METHODS], `${apiPrefix}/*`, (c, next) => handleORPC(c, next, apiPrefix, handler, createContext));
 }
-function mountRPCRoutes(app, procedures, rpcConfig, createContext) {
-  const handler = new RPCHandler(procedures);
-  const prefix = rpcConfig.prefix;
-  app.use(`${prefix}/*`, requireInternalRPC(rpcConfig));
-  app.on([...API_METHODS], `${prefix}/*`, (c, next) => handleORPC(c, next, prefix, handler, createContext));
-}
 async function handleORPC(c, next, prefix, handler, createContext) {
   const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
   const { matched, response } = await core.context.run({ requestId: context.requestId, userId: context.session?.userId, scopeId: context.scopeId }, () => handler.handle(c.req.raw, { prefix, context }));