@h-ai/serv 0.1.0-alpha.61 → 0.1.0-alpha.62

package/README.en.md

@@ -84,6 +84,8 @@ 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.
+
 ### 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:
@@ -152,6 +154,7 @@ When using `@h-ai/core` and `ServConfigSchema` with `config/_serv.yml`, transpor
 ```yaml
 # config/_serv.yml
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
 
 transport:
@@ -205,10 +208,10 @@ const app = serv.createApp({
 
 Pass the top-level `iam` handle to `serv.createApp` to derive:
 
-- **Access token verification**: `iam.session.verifyToken` fills `context.session` on every request without caching.
+- **Access token verification**: `iam.auth.verifyToken` fills `context.session` on every request without caching.
 - **Refresh rotation**: with `refreshCookie`, `iam.session.refresh` becomes the httpOnly-cookie refresh callback.
 
-**Context factory precedence**: explicit `createContext` > `verifyToken` > `iam.session.verifyToken` > metadata-only default.
+**Context factory precedence**: explicit `createContext` > `verifyToken` > `iam.auth.verifyToken` > metadata-only default.
 
 ```ts
 // 推荐：传入 iam，一行打开认证与 Cookie 刷新
@@ -233,7 +236,7 @@ const app = serv.createApp({
   createContext: async ({ request }) => {
     const base = serv.parseRequestContext({ request })
     // 手动填充 session（serv 不再自动填充）
-    const result = await iam.session.verifyToken(base.accessToken ?? '')
+    const result = await iam.auth.verifyToken(base.accessToken ?? '')
     return {
       ...base,
       session: result.success ? result.data : undefined,
@@ -339,16 +342,16 @@ To reuse `Bearer token -> session` and add tenant, workspace, or source-system f
 prefer `serv.buildAuthContextFactory()` to assemble a custom `createContext`:
 
 ```ts
-const baseContext = serv.buildAuthContextFactory(token => iam.session.verifyToken(token))
+const baseContext = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
 
 const app = serv.createApp({
   contract,
   procedures,
-  createContext: async ({ request }) => {
-    const context = await baseContext({ request })
+  createContext: async (input) => {
+    const context = await baseContext(input)
     return {
       ...context,
-      tenantId: request.headers.get('x-tenant-id') ?? null,
+      tenantId: input.request.headers.get('x-tenant-id') ?? null,
     }
   },
 })
@@ -436,7 +439,7 @@ const app = serv.createApp({
         && security.isNativeOrigin(request.headers.get('origin') ?? ''),
     },
   },
-  // ✅ 无需再传 verifyToken，iam.session.verifyToken 自动用于填充 context.session
+  // ✅ 无需再传 verifyToken，iam.auth.verifyToken 自动用于填充 context.session
 })
 ```
 
@@ -518,6 +521,7 @@ server:
   port: 3000
 
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json

package/README.ja.md

@@ -84,6 +84,8 @@ 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 は接続元で制限します。
+
 ### Audio WebSocket：ticket とサーバー認可
 
 音声接続には短期・単回 ticket が必要です。認証済み HTTP endpoint で発行（推奨：`iam.ticket.issue`）し、`verifyTicket` でアトミックに消費します（推奨：`iam.ticket.consume`）。接続直後に独立 timeout で認証し、認証前に業務フレームを処理しません。返された `ServSession` と任意の `grant` を保存してから `authorize` で有料パラメーターを確認します：
@@ -152,6 +154,7 @@ await apiClient.init({
 ```yaml
 # config/_serv.yml
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
 
 transport:
@@ -205,10 +208,10 @@ const app = serv.createApp({
 
 `serv.createApp` にトップレベルの `iam` を渡すと、次を自動構成します：
 
-- **access token 検証**：各リクエストで `iam.session.verifyToken` を呼び `context.session` を設定（キャッシュなし）。
+- **access token 検証**：各リクエストで `iam.auth.verifyToken` を呼び `context.session` を設定（キャッシュなし）。
 - **refresh token の更新**：`refreshCookie` 有効時、`iam.session.refresh` を httpOnly cookie 更新処理に使用。
 
-**context の優先順位**：明示的 `createContext` > `verifyToken` > `iam.session.verifyToken` > メタデータのみの既定解析。
+**context の優先順位**：明示的 `createContext` > `verifyToken` > `iam.auth.verifyToken` > メタデータのみの既定解析。
 
 ```ts
 // 推荐：传入 iam，一行打开认证与 Cookie 刷新
@@ -233,7 +236,7 @@ const app = serv.createApp({
   createContext: async ({ request }) => {
     const base = serv.parseRequestContext({ request })
     // 手动填充 session（serv 不再自动填充）
-    const result = await iam.session.verifyToken(base.accessToken ?? '')
+    const result = await iam.auth.verifyToken(base.accessToken ?? '')
     return {
       ...base,
       session: result.success ? result.data : undefined,
@@ -339,16 +342,16 @@ const app = serv.createApp({
 `serv.buildAuthContextFactory()` で独自の `createContext` を構成してください：
 
 ```ts
-const baseContext = serv.buildAuthContextFactory(token => iam.session.verifyToken(token))
+const baseContext = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
 
 const app = serv.createApp({
   contract,
   procedures,
-  createContext: async ({ request }) => {
-    const context = await baseContext({ request })
+  createContext: async (input) => {
+    const context = await baseContext(input)
     return {
       ...context,
-      tenantId: request.headers.get('x-tenant-id') ?? null,
+      tenantId: input.request.headers.get('x-tenant-id') ?? null,
     }
   },
 })
@@ -436,7 +439,7 @@ const app = serv.createApp({
         && security.isNativeOrigin(request.headers.get('origin') ?? ''),
     },
   },
-  // ✅ 无需再传 verifyToken，iam.session.verifyToken 自动用于填充 context.session
+  // ✅ 无需再传 verifyToken，iam.auth.verifyToken 自动用于填充 context.session
 })
 ```
 
@@ -518,6 +521,7 @@ server:
   port: 3000
 
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json

package/README.md

@@ -84,6 +84,8 @@ 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 仍按连接对端限制。
+
 ### Audio WebSocket：ticket 与服务端授权
 
 语音入口必须使用短期、一次性 ticket。应用通过已登录 HTTP endpoint 签发 ticket（推荐 `iam.ticket.issue`），并在 `verifyTicket` 中原子消费（推荐 `iam.ticket.consume`）；连接建立即完成鉴权（独立预鉴权超时），未鉴权不处理任何业务帧。框架保存返回的 `ServSession` 与可选 `grant`，再调用 `authorize` 确认付费参数：
@@ -152,6 +154,7 @@ await apiClient.init({
 ```yaml
 # config/_serv.yml
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
 
 transport:
@@ -205,10 +208,10 @@ const app = serv.createApp({
 
 `serv.createApp` 推荐直接传入顶层 `iam` 句柄，自动派生两件事：
 
-- **access token 校验**：每个请求调用 `iam.session.verifyToken` 填充 `context.session`（不缓存）。
+- **access token 校验**：每个请求调用 `iam.auth.verifyToken` 填充 `context.session`（不缓存）。
 - **refresh token 轮换**：启用 `refreshCookie` 后，自动使用 `iam.session.refresh` 作为 httpOnly cookie 刷新回调。
 
-**上下文工厂优先级**：显式 `createContext` > `verifyToken` > `iam.session.verifyToken` > 默认仅解析元数据。
+**上下文工厂优先级**：显式 `createContext` > `verifyToken` > `iam.auth.verifyToken` > 默认仅解析元数据。
 
 ```ts
 // 推荐：传入 iam，一行打开认证与 Cookie 刷新
@@ -233,7 +236,7 @@ const app = serv.createApp({
   createContext: async ({ request }) => {
     const base = serv.parseRequestContext({ request })
     // 手动填充 session（serv 不再自动填充）
-    const result = await iam.session.verifyToken(base.accessToken ?? '')
+    const result = await iam.auth.verifyToken(base.accessToken ?? '')
     return {
       ...base,
       session: result.success ? result.data : undefined,
@@ -339,16 +342,16 @@ const app = serv.createApp({
 优先用 `serv.buildAuthContextFactory()` 组装自定义 `createContext`：
 
 ```ts
-const baseContext = serv.buildAuthContextFactory(token => iam.session.verifyToken(token))
+const baseContext = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
 
 const app = serv.createApp({
   contract,
   procedures,
-  createContext: async ({ request }) => {
-    const context = await baseContext({ request })
+  createContext: async (input) => {
+    const context = await baseContext(input)
     return {
       ...context,
-      tenantId: request.headers.get('x-tenant-id') ?? null,
+      tenantId: input.request.headers.get('x-tenant-id') ?? null,
     }
   },
 })
@@ -436,7 +439,7 @@ const app = serv.createApp({
         && security.isNativeOrigin(request.headers.get('origin') ?? ''),
     },
   },
-  // ✅ 无需再传 verifyToken，iam.session.verifyToken 自动用于填充 context.session
+  // ✅ 无需再传 verifyToken，iam.auth.verifyToken 自动用于填充 context.session
 })
 ```
 
@@ -518,6 +521,7 @@ server:
   port: 3000
 
 http:
+  trustedProxies: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json

package/dist/features/ai.d.ts

@@ -2,7 +2,7 @@ import * as _orpc_server from '@orpc/server';
 import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { AIFunctions } from '@h-ai/ai';
-import { S as ServContext } from '../serv-context-CkbS0M9G.js';
+import { S as ServContext } from '../serv-context-CWzyrsdq.js';
 import '@h-ai/core';
 
 /** AI 默认 procedures 依赖。 */

package/dist/features/iam.d.ts

@@ -4,7 +4,7 @@ import * as zod from 'zod';
 import * as _orpc_contract from '@orpc/contract';
 import { IamFunctions } from '@h-ai/iam';
 export { TokenPair } from '@h-ai/iam';
-import { S as ServContext } from '../serv-context-CkbS0M9G.js';
+import { S as ServContext } from '../serv-context-CWzyrsdq.js';
 import '@h-ai/core';
 
 /** IAM 默认 procedures 依赖。 */
@@ -480,6 +480,7 @@ declare function createIamProcedures(deps: IamProcedureDeps): {
         list: _orpc_server.Procedure<ServContext & {}, any, zod.ZodObject<{
             page: zod.ZodOptional<zod.ZodCoercedNumber<unknown>>;
             pageSize: zod.ZodOptional<zod.ZodCoercedNumber<unknown>>;
+            roleCode: zod.ZodOptional<zod.ZodString>;
             search: zod.ZodOptional<zod.ZodString>;
             enabled: zod.ZodPipe<zod.ZodOptional<zod.ZodEnum<{
                 true: "true";

package/dist/features/storage.d.ts

@@ -2,7 +2,7 @@ import * as _orpc_server from '@orpc/server';
 import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { StorageFunctions } from '@h-ai/storage';
-import { S as ServContext } from '../serv-context-CkbS0M9G.js';
+import { S as ServContext } from '../serv-context-CWzyrsdq.js';
 import '@h-ai/core';
 
 /** Storage 默认 procedures 依赖。 */

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { HaiResult, ValidationFormError } from '@h-ai/core';
 import { AIFunctions, AudioWsStartMessage, AudioFormat } from '@h-ai/ai';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
 import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router, ContractRouter, Context, ContractProcedure, InferSchemaInput, InferSchemaOutput, UnlaziedRouter } from '@orpc/server';
-import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-CkbS0M9G.js';
-export { d as CreateServContextInput, N as NativeRefreshTokenTransportConfig, e as RefreshTokenPair } from './serv-context-CkbS0M9G.js';
+import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, c as ServRequestMetadata, p as parseRequestContext, d as buildAuthContextFactory } from './serv-context-CWzyrsdq.js';
+export { e as CreateServContextInput, N as NativeRefreshTokenTransportConfig, f as RefreshTokenPair } from './serv-context-CWzyrsdq.js';
 import { MiddlewareHandler } from 'hono';
 import { z, ZodType } from 'zod';
 import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
@@ -128,6 +128,8 @@ interface ServCorsRuntimeConfig {
 }
 /** ServHttpApp 的 HTTP 挂载配置。 */
 interface ServHttpConfig {
+    /** 可信任的连接代理 IP/CIDR；默认空数组，不采纳转发头。 */
+    readonly trustedProxies: readonly string[];
     readonly apiPrefix: `/api/${string}`;
     readonly openapi: false | ServOpenAPIHttpConfig;
     readonly docs: false | ServDocsHttpConfig;
@@ -151,6 +153,7 @@ type ServTransportRuntimeConfigInput = Partial<{
 }>;
 /** `serv.createApp` 接受的 HTTP 配置入参类型。 */
 type ServHttpConfigInput = Partial<{
+    readonly trustedProxies: readonly string[];
     readonly apiPrefix: `/api/${string}`;
     readonly openapi: false | Partial<ServOpenAPIHttpConfig>;
     readonly docs: false | Partial<ServDocsHttpConfig>;
@@ -171,6 +174,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     http: z.ZodOptional<z.ZodObject<{
+        trustedProxies: z.ZodDefault<z.ZodArray<z.ZodString>>;
         apiPrefix: z.ZodDefault<z.ZodCustom<`/api/${string}`, `/api/${string}`>>;
         openapi: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
             path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
@@ -217,6 +221,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         port: number;
     } | undefined;
     http?: {
+        trustedProxies: string[];
         apiPrefix: `/api/${string}`;
         openapi: false | {
             path: `/${string}`;
@@ -327,7 +332,7 @@ interface ServMiddlewareMount {
  * - `request`：测试 / 本地直连时发起 in-process 请求，避免消费方 import Hono。
  */
 interface ServHttpApp {
-    readonly fetch: (request: Request) => Response | Promise<Response>;
+    readonly fetch: (request: Request, metadata?: ServRequestMetadata) => Response | Promise<Response>;
     readonly request: (input: RequestInfo | URL, init?: RequestInit) => Response | Promise<Response>;
 }
 /**
@@ -336,13 +341,13 @@ interface ServHttpApp {
  * **认证 / 会话填充设计**（遵循最小知识原则）：
  *
  * - **`iam`**（推荐）：单一顶层引用。提供后 serv 自动：
- *   1. 使用 `iam.session.verifyToken` 填充 `context.session` → route guard 生效
+ *   1. 使用 `iam.auth.verifyToken` 填充 `context.session` → route guard 生效
  *   2. 若同时启用 `refreshCookie`，使用 `iam.session.refresh` 实现 refresh token 轮换
  *
  * - **`refreshCookie`**（可选）：浏览器默认用 httpOnly cookie；受信原生客户端可配置 body 通道。与 `iam` 正交：
  *   `iam` 决定 *谁* 验证 token，`refreshCookie` 决定 refresh token *怎么* 传输。
  *
- * - **`verifyToken`**（高级）：不使用 IAM 模块的逆脱口。优先于 `iam.session.verifyToken`。
+ * - **`verifyToken`**（高级）：不使用 IAM 模块的逆脱口。优先于 `iam.auth.verifyToken`。
  *
  * - **`createContext`**（高级）：完全接管上下文构造，设置后 serv **不再**自动填充 session，
  *   由调用方负责。
@@ -362,7 +367,7 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
      */
     readonly middlewares?: readonly ServMiddlewareMount[];
     /**
-     * IAM 模块引用（推荐）。提供后 serv 自动使用 `iam.session.verifyToken` 填充 session，
+     * IAM 模块引用（推荐）。提供后 serv 自动使用 `iam.auth.verifyToken` 填充 session，
      * 以及在 `refreshCookie` 启用时使用 `iam.session.refresh` 实现 cookie 刷新。
      *
      * 类型上要求 {@link ServIam}（`iam` 可以直接传入，结构类型保证兼容）。
@@ -374,7 +379,7 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
      */
     readonly refreshCookie?: RefreshCookieConfig;
     /**
-     * 高级：自定义访问令牌校验回调，覆盖 `iam.session.verifyToken`。
+     * 高级：自定义访问令牌校验回调，覆盖 `iam.auth.verifyToken`。
      * 不使用 IAM 模块的场景下使用。
      */
     readonly verifyToken?: (token: string) => Promise<HaiResult<ServSession>>;
@@ -915,4 +920,4 @@ declare const serv: {
     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 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 };
+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, ServRequestMetadata, 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

@@ -8,6 +8,7 @@ import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { Buffer } from 'buffer';
+import { BlockList, isIP } from 'net';
 import { z } from 'zod';
 import { getCookie } from 'hono/cookie';
 import { readFile } from 'fs/promises';
@@ -520,6 +521,70 @@ 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 normalizeClientIp(metadata.remoteAddress);
+}
+function normalizeClientIp(value) {
+  if (!value)
+    return void 0;
+  const address = value.trim();
+  if (!isIP(address))
+    return void 0;
+  const mapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  return mapped?.[1] ?? address;
+}
+function addProxy(blockList, entry) {
+  const [address, prefix, extra] = entry.split("/");
+  const family = address ? isIP(address) : 0;
+  if (!family || extra !== void 0)
+    throw new Error("trustedProxies entries must be IP addresses or CIDRs");
+  const type = family === 4 ? "ipv4" : "ipv6";
+  if (prefix === void 0) {
+    blockList.addAddress(address, type);
+    return;
+  }
+  const bits = Number(prefix);
+  if (!/^\d+$/.test(prefix) || bits < 0 || bits > (family === 4 ? 32 : 128))
+    throw new Error("Invalid trustedProxies CIDR prefix");
+  blockList.addSubnet(address, bits, type);
+}
+function isTrustedProxyEntry(entry) {
+  try {
+    addProxy(new BlockList(), entry);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createClientIpResolver(trustedProxies) {
+  const proxies = new BlockList();
+  for (const entry of trustedProxies)
+    addProxy(proxies, entry);
+  const trusted = (address) => proxies.check(address, isIP(address) === 4 ? "ipv4" : "ipv6");
+  return (request, remoteAddress) => {
+    const peer = normalizeClientIp(remoteAddress);
+    if (!peer || !trusted(peer))
+      return peer;
+    const forwarded = request.headers.get("x-forwarded-for");
+    if (forwarded === null) {
+      const realIp = request.headers.get("x-real-ip");
+      return realIp === null ? peer : normalizeClientIp(realIp);
+    }
+    const chain = forwarded.split(",");
+    if (chain.length > 32)
+      return void 0;
+    let current = peer;
+    for (let index = chain.length - 1; index >= 0 && trusted(current); index--) {
+      const address = normalizeClientIp(chain[index]);
+      if (!address)
+        return void 0;
+      current = address;
+    }
+    return current;
+  };
+}
 var DEFAULT_LOCALE = "zh-CN";
 function resolveRequestLocale(headers) {
   const get = (name) => {
@@ -586,6 +651,9 @@ function requireInternalRPC(config) {
   };
 }
 async function getRequestRemoteAddress(c) {
+  const remoteAddress = readRemoteAddress(c.env);
+  if (remoteAddress)
+    return remoteAddress;
   const getConnInfo = await resolveGetConnInfo();
   if (!getConnInfo)
     return void 0;
@@ -676,6 +744,7 @@ var CorsRuntimeConfigInputSchema = z.object({
   credentials: z.boolean().default(false)
 });
 var ServHttpConfigInputSchema = z.object({
+  trustedProxies: z.array(z.string().trim().refine(isTrustedProxyEntry, "Expected an IP address or CIDR")).default([]),
   apiPrefix: ApiPrefixSchema.default("/api/v1"),
   openapi: OpenAPIHttpConfigInputSchema.default(false),
   docs: DocsHttpConfigInputSchema.default(false),
@@ -719,8 +788,6 @@ function resolveServTransportRuntimeConfig(input = false) {
   return TransportRuntimeConfigInputSchema.parse(input);
 }
 var HEADER_REQUEST_ID = "x-request-id";
-var HEADER_FORWARDED_FOR = "x-forwarded-for";
-var HEADER_REAL_IP = "x-real-ip";
 var HEADER_AUTHORIZATION = "authorization";
 var HEADER_USER_AGENT = "user-agent";
 function extractBearerToken(value) {
@@ -734,8 +801,7 @@ function extractBearerToken(value) {
 function parseRequestContext(input) {
   const headers = input.request.headers;
   const requestId = headers.get(HEADER_REQUEST_ID) ?? core.id.uuid();
-  const forwardedFor = headers.get(HEADER_FORWARDED_FOR);
-  const ip = headers.get(HEADER_REAL_IP) ?? forwardedFor?.split(",")[0]?.trim();
+  const ip = normalizeClientIp(Object.hasOwn(input, "ip") ? input.ip : input.remoteAddress);
   const locale = resolveRequestLocale(headers);
   const accessToken = extractBearerToken(headers.get(HEADER_AUTHORIZATION));
   return {
@@ -1160,8 +1226,10 @@ function createApp(options) {
     core.i18n.coreM("core_errorNotFound", { locale: resolveRequestLocale(c.req.raw.headers) })
   ), 404));
   const iamRef = options.iam;
-  const verifyToken = options.verifyToken ?? (iamRef ? (token) => iamRef.session.verifyToken(token) : void 0);
-  const createContext = options.createContext ?? (verifyToken ? buildAuthContextFactory(verifyToken) : parseRequestContext);
+  const verifyToken = options.verifyToken ?? (iamRef ? (token) => iamRef.auth.verifyToken(token) : void 0);
+  const contextFactory = options.createContext ?? (verifyToken ? buildAuthContextFactory(verifyToken) : parseRequestContext);
+  const resolveIp = createClientIpResolver(http.trustedProxies);
+  const createContext = (input) => contextFactory({ ...input, ip: resolveIp(input.request, input.remoteAddress) });
   let cachedSpec;
   const getSpec = () => {
     cachedSpec ??= generateSpec(options.contract, { apiPrefix: http.apiPrefix });
@@ -1224,7 +1292,7 @@ function createApp(options) {
     });
     app.get(docs.path, async (c) => {
       if (docs.requireAuth) {
-        const context = await createContext({ request: c.req.raw });
+        const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
         if (!context.session)
           return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
       }
@@ -1254,7 +1322,7 @@ function mountRPCRoutes(app, procedures, rpcConfig, createContext) {
   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 });
+  const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
   const { matched, response } = await handler.handle(c.req.raw, { prefix, context });
   if (!matched) {
     await next();
@@ -1321,7 +1389,13 @@ function listen(app, options = {}) {
   const port = options.port ?? DEFAULT_SERV_PORT;
   const audioServer = audioWsServers.get(app);
   const server = serve(
-    { fetch: app.fetch, hostname: host, port, websocket: audioServer ? { server: audioServer } : void 0 },
+    {
+      // 保留原 bindings 对象，WebSocket 升级状态由 Node adapter 在同一对象上共享。
+      fetch: (request, bindings) => app.fetch(request, Object.assign(bindings, { remoteAddress: bindings.incoming.socket.remoteAddress })),
+      hostname: host,
+      port,
+      websocket: audioServer ? { server: audioServer } : void 0
+    },
     options.onListening
   );
   const handle = {