@h-ai/serv 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.en.md

@@ -4,9 +4,11 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/ai](../ai/README.en.md) · [@h-ai/api-contract](../api-contract/README.en.md) · [@h-ai/core](../core/README.en.md) · [@h-ai/crypto](../crypto/README.en.md) · [@h-ai/iam](../iam/README.en.md) · [@h-ai/storage](../storage/README.en.md)
 
-> hai-framework's API service runtime: a stable public HTTP App abstraction that mounts `@h-ai/api-contract` contracts as cross-platform HTTP APIs. Hono is an internal implementation detail.
+## Introduction
 
-## Capabilities
+hai-framework's API service runtime: a stable public HTTP App abstraction that mounts `@h-ai/api-contract` contracts as cross-platform HTTP APIs. Hono is an internal implementation detail.
+
+## Core features
 
 - Start with `serv.createApp(...)` → `serv.listen(app, { port })`; applications need not import Hono.
 - Flat API: `serv.createApp / serv.implement / serv.listen / serv.toFetch / serv.generateSpec / ...`.
@@ -22,7 +24,9 @@
 
 > Lifecycle: `@h-ai/serv` is a stateless HTTP App assembler and needs no `init()` / `close()`. Initialize `iam` / `storage` / `ai` / `crypto` before app creation, then release them in reverse order through `serv.listen(..., { onClose })`. `serv.createApp()` throws immediately on startup configuration errors such as transport manager creation failure.
 
-## Quick start
+## Getting started
+
+### Quick start
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -64,7 +68,7 @@ serv.listen(app, {
 // 5) 优雅关闭由 serv 托管，无需手动注册 process.once('SIGINT', ...)
 ```
 
-### host / port configuration
+#### host / port configuration
 
 Host/port come from `server` in `config/_serv.yml`: `HOST` / `PORT` environment variables > configuration > `127.0.0.1:3000`. The default `127.0.0.1` is local-only; use `0.0.0.0` to expose a container:
 
@@ -77,7 +81,7 @@ server:
 
 Pass the resolved `server` to `serv.listen`; explicit `host` / `port` arguments can also override it.
 
-### Fetch Runtime（Workers / Bun / Deno）
+#### Fetch Runtime（Workers / Bun / Deno）
 
 ```ts
 const handler = serv.toFetch(app)
@@ -86,7 +90,7 @@ 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.
 
-### Audio WebSocket: tickets and server authorization
+#### Audio WebSocket: tickets and server authorization
 
 Audio connections require short-lived, one-time tickets. Issue them through an authenticated HTTP endpoint (recommended: `iam.ticket.issue`) and consume atomically in `verifyTicket` (recommended: `iam.ticket.consume`). Authentication runs at connection time with a separate timeout; no business frames are processed beforehand. The framework stores the returned `ServSession` and optional `grant`, then calls `authorize` to approve paid parameters:
 
@@ -112,7 +116,7 @@ const app = serv.createApp({
 - `onSessionEnd` runs at most once after success, failure, or disconnection to release concurrency slots.
 - Browser `createAIClient({ audio: { url, getTicket } })` puts only one-time `ticket` in the WebSocket URL. `getTicket(request)` receives the operation summary (`operation` / `model`) for a tightly bound ticket. Never pass ordinary IAM access tokens.
 
-### Transport encryption (shared with `@h-ai/crypto`)
+#### Transport encryption (shared with `@h-ai/crypto`)
 
 serv does not expose its own encryption factory; the server manager comes from `crypto.transport`. Applications only pass the top-level `crypto` handle:
 
@@ -204,7 +208,7 @@ const app = serv.createApp({
 
 > **Security**: with `transport` enabled, business requests need valid `X-Client-Id` except `excludePaths` and key exchange. Missing/unknown clientId returns 400. Unencryptable bodies, non-JSON responses, or encryption size limits return errors rather than forwarding plaintext business data.
 
-### Token authentication (`iam` / `refreshCookie`)
+#### Token authentication (`iam` / `refreshCookie`)
 
 Pass the top-level `iam` handle to `serv.createApp` to derive:
 
@@ -246,7 +250,7 @@ const app = serv.createApp({
 })
 ```
 
-### Custom procedures (authentication + permissions)
+#### Custom procedures (authentication + permissions)
 
 ```ts
 const procedures = serv
@@ -260,7 +264,7 @@ const procedures = serv
   .build()
 ```
 
-### Advanced pipelines (HTTP middleware + context + route guards)
+#### Advanced pipelines (HTTP middleware + context + route guards)
 
 `@h-ai/serv` pipelines have three layers and extension points:
 
@@ -268,7 +272,7 @@ const procedures = serv
 2. **Context**: customize through `verifyToken` / `createContext` / `serv.buildAuthContextFactory()`.
 3. **Route guards**: declare authentication/authorization with `.auth()` / `.permission()` / `.role()`.
 
-#### 1) Custom HTTP middleware
+##### 1) Custom HTTP middleware
 
 Use `middlewares` for **HTTP cross-cutting logic** such as logging, tracing, rate limits, CORS, and tenant headers, or WebSocket/file/binary endpoints unsuited to JSON/oRPC contracts. Reuse `serv.cors(...)` for common CORS needs:
 
@@ -336,7 +340,7 @@ Notes:
 - Expose custom response headers such as `X-Encrypted` explicitly through `serv.cors({ exposedHeaders: [...] })` for browsers.
 - This layer works with HTTP middleware context and returns **HTTP Response**, not `HaiResult`.
 
-#### 2) Custom context pipelines
+##### 2) Custom context pipelines
 
 To reuse `Bearer token -> session` and add tenant, workspace, or source-system fields,
 prefer `serv.buildAuthContextFactory()` to assemble a custom `createContext`:
@@ -363,7 +367,7 @@ Choose the appropriate extension:
 - Add fields to default authentication context: use `buildAuthContextFactory(...) + createContext`.
 - Replace context construction entirely: use `createContext` directly.
 
-#### 3) Route guard
+##### 3) Route guard
 
 Public procedures use `.route(path, handler)`. For guarded routes, use
 `.route(path).auth/permission/role().handle(handler)`：
@@ -396,7 +400,7 @@ Public API boundaries:
 - The stable application-facing entry remains `@h-ai/serv`.
 - Internal helpers such as `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` are not documented as separate subpath exports.
 
-### httpOnly cookie authentication (recommended for production)
+#### httpOnly cookie authentication (recommended for production)
 
 httpOnly cookie mode stores refresh tokens in server-managed cookies unreadable to browser JavaScript, reducing XSS exposure.
 
@@ -455,7 +459,7 @@ await apiClient.init({
 
 > **Cookie attributes**: `HttpOnly; SameSite=Strict; Secure` in production; `Path` is limited to `{apiPrefix}/auth/refresh`.
 
-## API overview
+### API overview
 
 - `serv.createApp(options)`: create the HTTP App with custom middleware, health checks, OpenAPI, optional docs, and RPC.
 - `serv.parseRequestContext({ request })`: extract Bearer token + requestId without populating session.
@@ -482,7 +486,7 @@ Additional root types / named exports:
 
 > Transport encryption is a `createApp` option delegated internally to `crypto.transport`, not a flat `serv.xxx` API.
 
-## Configuration
+### Configuration
 
 `@h-ai/serv` does not scan YAML itself. Load `config/_serv.yml` through `@h-ai/core` and pass the result to `serv.createApp()`.
 
@@ -597,7 +601,7 @@ const app = serv.createApp({
 
 In production, empty or `*` `_serv.yml` `cors.origin` fails startup. Web and Capacitor/Tauri origins use exact normalized full-Origin matching to prevent suffix spoofing. Production also enforces Secure refresh cookies and disables OpenAPI/docs; configuration controls nonproduction endpoints.
 
-## Configuration driven authentication
+### Configuration driven authentication
 
 Agreements support configuration-loaded userAgreementMarkdown/privacyPolicyMarkdown and URLs. Markdown takes priority for the same agreement and is safely rendered in a modal.
 
@@ -605,7 +609,7 @@ createIamProcedures({ iam }) implements public config, password/LDAP/OTP login,
 
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
-## Error handling
+### Error handling
 
 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.
 
@@ -656,7 +660,7 @@ const procedures = serv
 
 > When downstream modules (such as `iam.user.xxx()`) return `HaiResult` directly, serv forwards `error.message` unchanged. `HaiError` holds only the final `message`, not `messageKey/params`, so **serv cannot generically retranslate arbitrary downstream errors**. Request-level localization must receive locale at the module that creates the error message.
 
-## Tests
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/serv test

package/README.ja.md

@@ -4,9 +4,11 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/ai](../ai/README.ja.md) · [@h-ai/api-contract](../api-contract/README.ja.md) · [@h-ai/core](../core/README.ja.md) · [@h-ai/crypto](../crypto/README.ja.md) · [@h-ai/iam](../iam/README.ja.md) · [@h-ai/storage](../storage/README.ja.md)
 
-> hai-framework の API サービスランタイム。公開 HTTP App 抽象を通じて `@h-ai/api-contract` を複数プラットフォームから使える HTTP API として提供します。Hono は内部実装です。
+## 概要
 
-## 機能概要
+hai-framework の API サービスランタイム。公開 HTTP App 抽象を通じて `@h-ai/api-contract` を複数プラットフォームから使える HTTP API として提供します。Hono は内部実装です。
+
+## 主な機能
 
 - `serv.createApp(...)` → `serv.listen(app, { port })` で起動。アプリは Hono を import する必要がありません。
 - フラットな API：`serv.createApp / serv.implement / serv.listen / serv.toFetch / serv.generateSpec / ...`。
@@ -22,7 +24,9 @@
 
 > ライフサイクル：`@h-ai/serv` は状態を持たない HTTP App の構成機能で、`init()` / `close()` は不要です。app 作成前に `iam` / `storage` / `ai` / `crypto` などを初期化し、`serv.listen(..., { onClose })` で逆順に解放します。`serv.createApp()` は transport 管理器の生成失敗など起動設定のエラーを即座に throw します。
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -64,7 +68,7 @@ serv.listen(app, {
 // 5) 优雅关闭由 serv 托管，无需手动注册 process.once('SIGINT', ...)
 ```
 
-### host / port 設定
+#### host / port 設定
 
 host/port は `config/_serv.yml` の `server` で指定し、`HOST` / `PORT` 環境変数 > 設定ファイル > `127.0.0.1:3000` の順です。既定の `127.0.0.1` はローカル専用で、コンテナー外に公開する場合は `0.0.0.0` にします：
 
@@ -77,7 +81,7 @@ server:
 
 解決済みの `server` を `serv.listen` に渡します。`host` / `port` の明示的な指定で上書きすることもできます。
 
-### Fetch Runtime（Workers / Bun / Deno）
+#### Fetch Runtime（Workers / Bun / Deno）
 
 ```ts
 const handler = serv.toFetch(app)
@@ -86,7 +90,7 @@ 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 は接続元で制限します。
 
-### Audio WebSocket：ticket とサーバー認可
+#### Audio WebSocket：ticket とサーバー認可
 
 音声接続には短期・単回 ticket が必要です。認証済み HTTP endpoint で発行（推奨：`iam.ticket.issue`）し、`verifyTicket` でアトミックに消費します（推奨：`iam.ticket.consume`）。接続直後に独立 timeout で認証し、認証前に業務フレームを処理しません。返された `ServSession` と任意の `grant` を保存してから `authorize` で有料パラメーターを確認します：
 
@@ -112,7 +116,7 @@ const app = serv.createApp({
 - `onSessionEnd` は成功・失敗・切断後に最大 1 回呼び、同時実行枠の解放に使用。
 - ブラウザーの `createAIClient({ audio: { url, getTicket } })` は単回 `ticket` のみを URL に付けます。`getTicket(request)` は `operation` / `model` の概要から今回の操作専用 ticket を発行できます。通常の IAM access token は渡さないでください。
 
-### 通信暗号化（`@h-ai/crypto` と共通）
+#### 通信暗号化（`@h-ai/crypto` と共通）
 
 serv 独自の暗号化ファクトリーはなく、`crypto.transport` から管理器を作成します。利用側はトップレベルの `crypto` のみを渡します：
 
@@ -204,7 +208,7 @@ const app = serv.createApp({
 
 > **安全方針**：`transport` 有効時は `excludePaths` と鍵交換以外で有効な `X-Client-Id` が必要です。不足・未知の clientId は 400、暗号化不能・非 JSON 応答・上限超過はエラーになり、平文の業務データは渡しません。
 
-### Token 認証（`iam` / `refreshCookie`）
+#### Token 認証（`iam` / `refreshCookie`）
 
 `serv.createApp` にトップレベルの `iam` を渡すと、次を自動構成します：
 
@@ -246,7 +250,7 @@ const app = serv.createApp({
 })
 ```
 
-### 独自 procedure（認証 + 権限）
+#### 独自 procedure（認証 + 権限）
 
 ```ts
 const procedures = serv
@@ -260,7 +264,7 @@ const procedures = serv
   .build()
 ```
 
-### 高度なパイプライン（HTTP middleware + context + route guard）
+#### 高度なパイプライン（HTTP middleware + context + route guard）
 
 `@h-ai/serv` のパイプラインは 3 層で、それぞれの拡張入口があります：
 
@@ -268,7 +272,7 @@ const procedures = serv
 2. **context 層**：`verifyToken` / `createContext` / `serv.buildAuthContextFactory()` で拡張。
 3. **route guard 層**：`.auth()` / `.permission()` / `.role()` で認証・認可を宣言。
 
-#### 1) 独自 HTTP middleware
+##### 1) 独自 HTTP middleware
 
 ログ・trace・レート制限・CORS・テナントヘッダーなどの **HTTP 共通処理**、または JSON/oRPC contract に適さない WebSocket・ファイル・バイナリー endpoint には `middlewares` を使います。一般的な CORS は `serv.cors(...)` を再利用できます：
 
@@ -336,7 +340,7 @@ const app = serv.createApp({
 - ブラウザーが `X-Encrypted` などを読む場合は `serv.cors({ exposedHeaders: [...] })` で明示的に公開。
 - この層は HTTP middleware context を操作し、`HaiResult` ではなく **HTTP Response** を返します。
 
-#### 2) 独自 context パイプライン
+##### 2) 独自 context パイプライン
 
 `Bearer token -> session` を再利用し、テナント・workspace・送信元などの項目を追加する場合は、
 `serv.buildAuthContextFactory()` で独自の `createContext` を構成してください：
@@ -363,7 +367,7 @@ const app = serv.createApp({
 - 既定の認証 context に項目を追加：`buildAuthContextFactory(...) + createContext`。
 - context 生成全体を置換：直接 `createContext`。
 
-#### 3) Route guard
+##### 3) Route guard
 
 公開 procedure は `.route(path, handler)` を使い、ガードが必要な場合は次を使います：
 `.route(path).auth/permission/role().handle(handler)`：
@@ -396,7 +400,7 @@ const procedures = serv
 - アプリ向けの安定した入口はルートの `@h-ai/serv`。
 - `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` などの内部 helper は独立サブパスとして公開しません。
 
-### httpOnly Cookie 認証（本番推奨）
+#### httpOnly Cookie 認証（本番推奨）
 
 httpOnly cookie モードは refresh token をサーバー管理の Cookie に保存し、ブラウザー JS から読めなくして XSS による漏洩を抑えます。
 
@@ -455,7 +459,7 @@ await apiClient.init({
 
 > **Cookie 属性**：本番は `HttpOnly; SameSite=Strict; Secure`。`Path` は `{apiPrefix}/auth/refresh` に限定。
 
-## API 一覧
+### API 一覧
 
 - `serv.createApp(options)`：独自 middleware、ヘルスチェック、OpenAPI、任意の文書・RPC を備えた HTTP App を作成。
 - `serv.parseRequestContext({ request })`：Bearer token + requestId を抽出し、session は設定しません。
@@ -482,7 +486,7 @@ await apiClient.init({
 
 > 通信暗号化は `createApp` の設定機能で、内部で `crypto.transport` に委譲します。`serv.xxx` の独立 API ではありません。
 
-## 設定
+### 設定
 
 `@h-ai/serv` 自体は YAML を走査しません。`@h-ai/core` で `config/_serv.yml` を読み、解析結果を `serv.createApp()` に渡してください。
 
@@ -597,7 +601,7 @@ const app = serv.createApp({
 
 本番では `_serv.yml` の `cors.origin` が空・`*` なら起動に失敗します。Web・Capacitor/Tauri は正規化済み Origin 全体を厳密照合し、末尾偽装を防ぎます。本番は Secure refresh cookie を強制し OpenAPI/docs を無効化します。非本番の endpoint は設定ファイルで決めます。
 
-## 設定による認証画面
+### 設定による認証画面
 
 規約は設定の userAgreementMarkdown/privacyPolicyMarkdown または URL を使用できます。同じ規約は Markdown 本文を優先して安全な Modal で描画します。
 
@@ -605,7 +609,7 @@ createIamProcedures({ iam }) は公開設定、LDAP/OTP/パスワード、登録
 
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
-## エラー処理
+### エラー処理
 
 通常の procedure は認証・認可・業務の失敗と捕捉した handler 例外を HaiResult として既定で HTTP 200 で返します。`error.httpStatus` はドメインエラーのメタデータで、HTTP 応答ステータスを変更しません。クライアントは `success` と `error.code` を確認してください。未認証では `error.httpStatus=401`、DB クエリー失敗や INTERNAL_ERROR では 500 です。
 
@@ -656,7 +660,7 @@ const procedures = serv
 
 > `iam.user.xxx()` など下流が直接 `HaiResult` を返す場合、serv は `error.message` をそのまま渡します。`HaiError` は最終 `message` のみで `messageKey/params` を持たないため、**serv の境界で任意の下流エラーを汎用的に再翻訳することはできません**。リクエストごとの i18n はエラーを生成するモジュールで locale を受け取る必要があります。
 
-## テスト
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/serv test
@@ -664,6 +668,6 @@ pnpm --filter @h-ai/serv typecheck
 pnpm --filter @h-ai/serv lint
 ```
 
-## License
+## ライセンス
 
 Apache-2.0

package/README.md

@@ -4,9 +4,11 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/ai](../ai/README.md) · [@h-ai/api-contract](../api-contract/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/crypto](../crypto/README.md) · [@h-ai/iam](../iam/README.md) · [@h-ai/storage](../storage/README.md)
 
-> hai-framework 的 API 服务运行时：对外暴露稳定的 HTTP App 抽象，把 `@h-ai/api-contract` 契约挂载为跨端可访问的 HTTP API；Hono 仅作为内部运行时实现。
+## 简介
 
-## 能力概览
+hai-framework 的 API 服务运行时：对外暴露稳定的 HTTP App 抽象，把 `@h-ai/api-contract` 契约挂载为跨端可访问的 HTTP API；Hono 仅作为内部运行时实现。
+
+## 核心功能清单
 
 - 一行启动：`serv.createApp(...)` → `serv.listen(app, { port })`，应用代码不需要 import Hono
 - 扁平 API（最小知识）：`serv.createApp / serv.implement / serv.listen / serv.toFetch / serv.generateSpec / ...`
@@ -22,7 +24,9 @@
 
 > 生命周期说明：`@h-ai/serv` 本身是无状态 HTTP App 装配器，不需要 `init()` / `close()`；请在创建 app 前初始化 `iam` / `storage` / `ai` / `crypto` 等依赖，并在 `serv.listen(..., { onClose })` 中反向释放它们。`serv.createApp()` 遇到启动期配置错误（例如 transport manager 创建失败）会 fail-fast 抛出，便于进程启动阶段暴露问题。
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -64,7 +68,7 @@ serv.listen(app, {
 // 5) 优雅关闭由 serv 托管，无需手动注册 process.once('SIGINT', ...)
 ```
 
-### host / port 配置
+#### host / port 配置
 
 host/port 统一由 `config/_serv.yml` 的 `server` 提供，优先级：`HOST` / `PORT` 环境变量 > 配置文件 > 默认 `127.0.0.1:3000`。默认 `127.0.0.1` 仅本机可达，容器对外暴露时改为 `0.0.0.0`：
 
@@ -77,7 +81,7 @@ server:
 
 应用把解析后的 `server` 传给 `serv.listen`（`serv.listen` 也可直接传 `host` / `port` 显式覆盖）。
 
-### Fetch Runtime（Workers / Bun / Deno）
+#### Fetch Runtime（Workers / Bun / Deno）
 
 ```ts
 const handler = serv.toFetch(app)
@@ -86,7 +90,7 @@ 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 仍按连接对端限制。
 
-### Audio WebSocket：ticket 与服务端授权
+#### Audio WebSocket：ticket 与服务端授权
 
 语音入口必须使用短期、一次性 ticket。应用通过已登录 HTTP endpoint 签发 ticket（推荐 `iam.ticket.issue`），并在 `verifyTicket` 中原子消费（推荐 `iam.ticket.consume`）；连接建立即完成鉴权（独立预鉴权超时），未鉴权不处理任何业务帧。框架保存返回的 `ServSession` 与可选 `grant`，再调用 `authorize` 确认付费参数：
 
@@ -112,7 +116,7 @@ const app = serv.createApp({
 - `onSessionEnd` 在成功、失败或断连后至多调用一次，供应用释放并发占用。
 - 浏览器 `createAIClient({ audio: { url, getTicket } })` 只把一次性 `ticket` 放入 WebSocket URL；`getTicket(request)` 接收本次操作摘要（`operation` / `model`），可签发与本次操作严格绑定的票据；禁止传普通 IAM access token。
 
-### 传输加密（与 `@h-ai/crypto` 统一）
+#### 传输加密（与 `@h-ai/crypto` 统一）
 
 serv 不暴露本地传输加密工厂；统一从 `crypto.transport` 创建服务端管理器。使用方只需传入顶层 `crypto` 句柄：
 
@@ -204,7 +208,7 @@ const app = serv.createApp({
 
 > **安全策略**：启用 `transport` 后，除 `excludePaths` 与密钥协商端点外，业务请求必须携带有效 `X-Client-Id`。缺失或未知 clientId 会返回 400；响应体无法加密、非 JSON 业务响应或超过单次加密上限时返回错误，不会明文透传业务数据。
 
-### Token 认证（`iam` / `refreshCookie`）
+#### Token 认证（`iam` / `refreshCookie`）
 
 `serv.createApp` 推荐直接传入顶层 `iam` 句柄，自动派生两件事：
 
@@ -246,7 +250,7 @@ const app = serv.createApp({
 })
 ```
 
-### 自定义 procedure（认证 + 权限）
+#### 自定义 procedure（认证 + 权限）
 
 ```ts
 const procedures = serv
@@ -260,7 +264,7 @@ const procedures = serv
   .build()
 ```
 
-### 高级：自定义 pipeline（HTTP middleware + context + route guard）
+#### 高级：自定义 pipeline（HTTP middleware + context + route guard）
 
 `@h-ai/serv` 的“pipeline”分三层，分别对应三种扩展方式：
 
@@ -268,7 +272,7 @@ const procedures = serv
 2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 定制请求上下文。
 3. **route guard 层**：通过 `.auth()` / `.permission()` / `.role()` 声明认证授权。
 
-#### 1) 自定义 HTTP middleware
+##### 1) 自定义 HTTP middleware
 
 当你需要加请求日志、trace、限流、CORS、租户头校验等 **HTTP 层横切逻辑**，或挂载不适合进入 JSON/oRPC contract 的 WebSocket、文件和二进制端点时，使用 `middlewares`。常见 CORS 场景可直接复用 `serv.cors(...)`：
 
@@ -336,7 +340,7 @@ const app = serv.createApp({
 - 浏览器若需读取自定义响应头（例如 transport 的 `X-Encrypted`），请通过 `serv.cors({ exposedHeaders: [...] })` 显式暴露
 - 这一层直接操作 HTTP middleware context，返回的是 **HTTP Response**，不是 `HaiResult`
 
-#### 2) 自定义 context pipeline
+##### 2) 自定义 context pipeline
 
 如果你只想复用 `Bearer token -> session` 这一段逻辑，再额外补充租户、工作区、来源系统等字段，
 优先用 `serv.buildAuthContextFactory()` 组装自定义 `createContext`：
@@ -363,7 +367,7 @@ const app = serv.createApp({
 - 想在默认认证上下文之上追加字段：用 `buildAuthContextFactory(...) + createContext`
 - 想完全接管上下文构造：直接用 `createContext`
 
-#### 3) Route guard
+##### 3) Route guard
 
 公开 procedure 使用 `.route(path, handler)`；需要 guard 时使用
 `.route(path).auth/permission/role().handle(handler)`：
@@ -396,7 +400,7 @@ const procedures = serv
 - 对应用层公开的稳定入口仍然是根入口 `@h-ai/serv`
 - `securityHeaders` / `requireInternalRPC` / `buildHaiErrorBody` 等内部 helper/middleware 不作为单独子路径文档暴露
 
-### httpOnly Cookie 认证（推荐生产方案）
+#### httpOnly Cookie 认证（推荐生产方案）
 
 httpOnly cookie 模式将 refresh token 存储在服务端管理的 cookie 中（浏览器 JS 无法读取），避免 XSS 风险。
 
@@ -455,7 +459,7 @@ await apiClient.init({
 
 > **Cookie 规格**：`HttpOnly; SameSite=Strict; Secure`（生产）；`Path` 限制为 `{apiPrefix}/auth/refresh`。
 
-## API 概览
+### API 概览
 
 - `serv.createApp(options)`：创建 HTTP App 抽象，挂载自定义 `middlewares`、健康检查、OpenAPI handler、可选文档与 RPC
 - `serv.parseRequestContext({ request })`：默认上下文解析（提取 Bearer token + requestId，不填充 session）
@@ -482,7 +486,7 @@ await apiClient.init({
 
 > 传输加密不作为 `serv.xxx` 扁平 API 暴露；它是 `createApp` 的配置能力，内部委托 `crypto.transport`。
 
-## 配置
+### 配置
 
 `@h-ai/serv` 本身不主动扫描 YAML；推荐由 `@h-ai/core` 统一加载 `config/_serv.yml`，再把解析结果传给 `serv.createApp()`。
 
@@ -597,7 +601,7 @@ const app = serv.createApp({
 
 生产环境下 `_serv.yml` 的 `cors.origin` 为空或为 `*` 会在启动时失败；Web 与 Capacitor/Tauri Origin 均按规范化后的完整 Origin 精确匹配，避免后缀伪造。生产环境同时强制 Secure refresh cookie 并关闭 OpenAPI/docs，配置文件仍决定非生产环境具体挂载哪些端点。
 
-## 配置驱动认证页面
+### 配置驱动认证页面
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
@@ -605,7 +609,7 @@ const app = serv.createApp({
 
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
-## 错误处理
+### 错误处理
 
 普通 procedure 的认证、授权、业务失败和被捕获的 handler 异常都作为 `HaiResult` 输出，默认通过 HTTP 200 返回；`error.httpStatus` 是领域错误元数据，不会自动改写响应状态。客户端必须检查 `success` 与 `error.code`。例如未登录为 `error.httpStatus=401`，数据库查询失败或 INTERNAL_ERROR 为 500。
 
@@ -656,7 +660,7 @@ const procedures = serv
 
 > 如果错误来自下游业务模块（如 `iam.user.xxx()`）且该模块已经直接返回 `HaiResult`，serv 会原样透传它的 `error.message`。当前 `HaiError` 只携带最终 `message`，不携带 `messageKey/params`，因此 **serv 边界无法对任意下游错误再做一次通用 i18n 重翻译**；要支持请求级 i18n，必须在创建该错误消息的模块里就拿到 locale。
 
-## 测试
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/serv test
@@ -664,6 +668,6 @@ pnpm --filter @h-ai/serv typecheck
 pnpm --filter @h-ai/serv lint
 ```
 
-## License
+## 许可证
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/serv",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework service runtime powered by Hono and oRPC.",
   "license": "Apache-2.0",
   "exports": {
@@ -35,9 +35,9 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "peerDependencies": {
-    "@h-ai/ai": "0.1.0-alpha.65",
-    "@h-ai/iam": "0.1.0-alpha.65",
-    "@h-ai/storage": "0.1.0-alpha.65"
+    "@h-ai/ai": "0.1.0-alpha.67",
+    "@h-ai/iam": "0.1.0-alpha.67",
+    "@h-ai/storage": "0.1.0-alpha.67"
   },
   "peerDependenciesMeta": {
     "@h-ai/ai": {
@@ -51,9 +51,9 @@
     }
   },
   "dependencies": {
-    "@h-ai/api-contract": "0.1.0-alpha.65",
-    "@h-ai/core": "0.1.0-alpha.65",
-    "@h-ai/crypto": "0.1.0-alpha.65",
+    "@h-ai/api-contract": "0.1.0-alpha.67",
+    "@h-ai/core": "0.1.0-alpha.67",
+    "@h-ai/crypto": "0.1.0-alpha.67",
     "@hono/node-server": "^2.1.4",
     "@orpc/openapi": "^1.15.5",
     "@orpc/server": "^1.15.5",
@@ -64,9 +64,9 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@h-ai/ai": "0.1.0-alpha.65",
-    "@h-ai/iam": "0.1.0-alpha.65",
-    "@h-ai/storage": "0.1.0-alpha.65",
+    "@h-ai/ai": "0.1.0-alpha.67",
+    "@h-ai/iam": "0.1.0-alpha.67",
+    "@h-ai/storage": "0.1.0-alpha.67",
     "@types/node": "^26.6.5",
     "@types/ws": "^8.18.2",
     "rimraf": "^6.1.3",