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

package/dist/{serv-context-CatIx8r-.d.ts → serv-context-BUrtWoFC.d.ts}

@@ -1,16 +1,17 @@
 import { HaiResult, Logger } from '@h-ai/core';
 
 /**
- * @h-ai/serv — Refresh Token httpOnly Cookie 传输中间件
+ * @h-ai/serv — Refresh Token 浏览器 / 原生传输
  *
- * **职责边界**：本文件 **仅** 负责 `refresh token` 的 cookie 化传输，不涉及 access token 校验。
+ * **职责边界**：本文件 **仅** 负责 `refresh token` 的传输，不涉及 access token 校验。
  * - access token 校验由 `serv-context.ts` 的 `buildAuthContextFactory` 统一处理
- * - 本文件只关心：浏览器场景下，refresh token 不应写入 JS 可读存储（防 XSS），改走 httpOnly cookie
+ * - 浏览器使用 httpOnly cookie，避免 refresh token 进入 JS 可读存储
+ * - 经过应用可信来源校验的原生客户端可改用 JSON body，交由系统安全存储持久化
  *
  * **挂载的路由**：
- * - login / register / loginWithOtp：拦截 oRPC 成功响应，从响应体提取 refresh token → Set-Cookie，并从响应体擦除
- * - logout：拦截 oRPC 成功响应，清除 Cookie（Max-Age=0）
- * - refresh：**专属路由**（不走 oRPC），从 Cookie 读取 refresh token → 调用 `onRefresh` → 更新 Cookie
+ * - login / register / loginWithOtp：浏览器写 Cookie 并擦除响应 token；受信原生请求保留响应 token
+ * - logout：浏览器清除 Cookie（Max-Age=0）；原生客户端自行清理安全存储
+ * - refresh：**专属路由**（不走 oRPC），按请求来源从 Cookie 或 JSON body 读取并轮换 token
  *
  * **Cookie 规格**：`HttpOnly; SameSite=Strict; Secure`（生产）/ 无 Secure（开发）
  * Cookie Path 限制为 `{apiPrefix}/auth/refresh`，最小化浏览器自动发送范围（避免 CSRF 攻击面）。
@@ -28,9 +29,20 @@ interface RefreshTokenPair {
     readonly tokenType?: string;
 }
 /**
- * Refresh Token Cookie 传输配置。
+ * 原生客户端的 refresh token body 传输配置。
  *
- * 传入 `serv.createApp({ refreshCookie: ... })` 后自动管理 refresh token cookie。
+ * 浏览器继续使用 httpOnly cookie；只有经过应用可信来源校验的原生请求，才允许在
+ * JSON body 中接收和返回 refresh token。`isRequest` 必须同时校验客户端标识与 Origin，
+ * 不能仅信任可伪造的单个请求头。
+ */
+interface NativeRefreshTokenTransportConfig {
+    /** 判断当前请求是否来自受信原生客户端。 */
+    readonly isRequest: (request: Request) => boolean;
+}
+/**
+ * Refresh Token 传输配置。
+ *
+ * 传入 `serv.createApp({ refreshCookie: ... })` 后自动管理浏览器 cookie，并可选启用受信原生 body 通道。
  * access token 仍然走 `Authorization: Bearer <token>`；本配置只改变 refresh token 的传输通道。
  *
  * 刷新回调来源（优先级从高到低）：
@@ -51,6 +63,13 @@ interface RefreshCookieConfig {
      * - 本地 HTTP 开发设为 `false` 可让 Cookie 在 HTTP 下正常工作。
      */
     readonly secure?: boolean;
+    /**
+     * 为受信原生客户端启用 JSON body 传输。
+     *
+     * 启用后，匹配请求的登录、注册与刷新响应保留 `refreshToken`，刷新请求从
+     * `{ refreshToken }` body 读取凭证，且不读写浏览器 Cookie。
+     */
+    readonly nativeTokenTransport?: NativeRefreshTokenTransportConfig;
     /**
      * 自定义刷新回调（高级用法）。
      * 未提供时使用顶层 `iam.session.refresh`；两者均缺失时 `createApp` 会抛错。
@@ -121,7 +140,7 @@ type CreateServContext = (input: CreateServContextInput) => ServContext | Promis
  *
  * - 提取 `x-request-id` / `accept-language` / `x-forwarded-for` / `x-real-ip` / `user-agent`
  * - 从 `Authorization: Bearer <token>` 提取 `accessToken`
- * - **不会**读取 refresh token：refresh token 若启用 `refreshCookie`，只走 httpOnly cookie
+ * - **不会**读取 refresh token：refresh token 若启用 `refreshCookie`，只走专属刷新路由
  *
  * `session` 字段始终为 `undefined`：若需会话填充，请使用 {@link buildAuthContextFactory}
  * 或直接通过 `serv.createApp({ iam })` 让框架自动选择合适工厂。
@@ -140,7 +159,7 @@ declare function parseRequestContext(input: CreateServContextInput): ServContext
  * 4. 下游 `requireAuth` / `requirePermission` / `requireRole` 据此判断 401/403
  *
  * refresh token **不参与**这里的认证流程：它只在 access token 过期后，被 `/auth/refresh`
- * 从 httpOnly cookie 中读出，用于换发新的 access token。
+ * 从浏览器 httpOnly cookie 或受信原生 JSON body 中读出，用于换发新的 access token。
  *
  * **安全保证**：
  * - 每个请求都会重新调用 `verifyToken`（不缓存），用户被撤权后立即生效
@@ -152,4 +171,4 @@ declare function parseRequestContext(input: CreateServContextInput): ServContext
  */
 declare function buildAuthContextFactory(verifyToken: (accessToken: string) => Promise<HaiResult<ServSession>>): CreateServContext;
 
-export { type CreateServContext as C, type RefreshCookieConfig as R, type ServSession as S, type ServContext as a, type ServIam as b, buildAuthContextFactory as c, type CreateServContextInput as d, type RefreshTokenPair as e, parseRequestContext as p };
+export { type CreateServContext as C, type NativeRefreshTokenTransportConfig as N, type RefreshCookieConfig as R, type ServSession as S, type ServContext as a, type ServIam as b, buildAuthContextFactory as c, type CreateServContextInput as d, type RefreshTokenPair as e, parseRequestContext as p };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/serv",
   "type": "module",
-  "version": "0.1.0-alpha.44",
+  "version": "0.1.0-alpha.46",
   "description": "Hai Framework service runtime powered by Hono and oRPC.",
   "license": "Apache-2.0",
   "exports": {
@@ -32,9 +32,9 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@h-ai/ai": "0.1.0-alpha.44",
-    "@h-ai/iam": "0.1.0-alpha.44",
-    "@h-ai/storage": "0.1.0-alpha.44"
+    "@h-ai/iam": "0.1.0-alpha.46",
+    "@h-ai/storage": "0.1.0-alpha.46",
+    "@h-ai/ai": "0.1.0-alpha.46"
   },
   "peerDependenciesMeta": {
     "@h-ai/ai": {
@@ -56,9 +56,9 @@
     "@scalar/api-reference": "^1.57.1",
     "hono": "^4.12.18",
     "zod": "^4.4.3",
-    "@h-ai/api-contract": "0.1.0-alpha.44",
-    "@h-ai/crypto": "0.1.0-alpha.44",
-    "@h-ai/core": "0.1.0-alpha.44"
+    "@h-ai/api-contract": "0.1.0-alpha.46",
+    "@h-ai/core": "0.1.0-alpha.46",
+    "@h-ai/crypto": "0.1.0-alpha.46"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
@@ -66,9 +66,9 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7",
-    "@h-ai/ai": "0.1.0-alpha.44",
-    "@h-ai/iam": "0.1.0-alpha.44",
-    "@h-ai/storage": "0.1.0-alpha.44"
+    "@h-ai/iam": "0.1.0-alpha.46",
+    "@h-ai/ai": "0.1.0-alpha.46",
+    "@h-ai/storage": "0.1.0-alpha.46"
   },
   "scripts": {
     "build": "tsup",