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

package/README.md

@@ -7,6 +7,7 @@
 - 一行启动：`serv.createApp(...)` → `serv.listen(app, { port })`，应用代码不需要 import Hono
 - 扁平 API（最小知识）：`serv.listen / serv.toFetch / serv.requireAuth / serv.requirePermission / serv.generateSpec / ...`
 - 自定义 pipeline：`createApp({ middlewares })` 挂 HTTP middleware；procedure wrapper 复用根入口导出的共享类型
+- 只读 Storage 资源：`serv.storageAssets(...)` 统一处理安全 key、MIME 白名单、GET/HEAD、ETag 与缓存头
 - 默认 feature procedures：`createIamProcedures()`、`createStorageProcedures()`、`createAiProcedures()`
 - 内置安全响应头、健康检查、可选 OpenAPI JSON、可选 Scalar 文档页、可选内部 RPC endpoint
 - 可选传输加密：`serv.createApp({ transport: { crypto } })` 自动挂载密钥协商与请求/响应加解密
@@ -284,10 +285,13 @@ const app = serv.createApp({
     },
     {
       path: '/assets/*',
-      // 路径级 middleware 可以终结请求；响应仍经过内置 securityHeaders。
-      middleware: c => c.body(imageBytes, 200, {
-        'Content-Type': 'image/png',
-        'Cache-Control': 'public, max-age=31536000, immutable',
+      middleware: serv.storageAssets({
+        storage,
+        pathPrefix: '/assets/',
+        keyPattern: /^public\/[\w-]+\.png$/,
+        allowedContentTypes: ['image/png'],
+        cacheControl: 'public, max-age=31536000, immutable',
+        crossOriginResourcePolicy: 'cross-origin',
       }),
     },
   ],
@@ -306,7 +310,8 @@ const app = serv.createApp({
 - `middlewares` 按数组顺序注册
 - `path` 省略时默认 `'*'`
 - 由于 `middlewares` 先于 `transport` 执行，CORS preflight 或二进制端点可以直接短路；短路响应仍带内置安全头，但不会经过 transport
-- 文件端点的允许方法、路径校验、MIME、缓存和访问授权由应用显式决定；框架不内置头像等业务概念
+- 公开只读文件优先使用 `serv.storageAssets(...)`；应用仍须显式提供 key/MIME 白名单、缓存与跨域策略，框架不内置头像等业务概念
+- 私有资源、Range 下载或动态授权继续使用自定义 middleware/procedure，不应套用公开资源 helper
 - 若需要读取解密后的业务 body，请改用 context / procedure 层扩展
 - 浏览器若需读取自定义响应头（例如 transport 的 `X-Encrypted`），请通过 `serv.cors({ exposedHeaders: [...] })` 显式暴露
 - 这一层直接操作 HTTP middleware context，返回的是 **HTTP Response**，不是 `HaiResult`
@@ -394,6 +399,7 @@ httpOnly cookie 模式将 refresh token 存储在服务端管理的 cookie 中
   `serv.parseRequestContext()` / `extractBearerToken()` 解析的就是它；`buildAuthContextFactory()` 校验的也是它。
 - `refreshToken`：长期凭证。启用 `refreshCookie` 后，它不会再暴露给前端 JS，而是只保存在浏览器的 httpOnly cookie 中。
   它**不会**被 `extractBearerToken()` 读取，只会在 `/auth/refresh` 被服务端取出，用来换发新的 access token。
+  受信原生客户端可通过 `nativeTokenTransport` 改用 JSON body，但必须同时校验客户端标识与 Origin。
 
 **工作原理：**
 
@@ -402,6 +408,9 @@ httpOnly cookie 模式将 refresh token 存储在服务端管理的 cookie 中
 3. Access token 过期时，浏览器自动携带 cookie 访问 `/auth/refresh`
 4. 服务端读取 cookie → 调用 `onRefresh` → 返回新 access token + 更新 cookie（响应体不暴露 refresh token）
 
+原生客户端匹配 `nativeTokenTransport.isRequest` 后，登录/注册/刷新响应会保留轮换后的
+`refreshToken`，刷新请求从 `{ refreshToken }` body 读取，且整个流程不读写浏览器 Cookie。
+
 **服务端配置：**
 
 ```ts
@@ -416,6 +425,12 @@ const app = serv.createApp({
     // maxAge: 30 * 24 * 3600,          // 默认 30 天
     // secure: true,                    // 默认在 NODE_ENV=production 时开启
     // onRefresh: customFn,             // 可覆盖 iam.session.refresh。
+    nativeTokenTransport: {
+      // 必须 fail-closed：同时校验平台标识与允许的原生 Origin。
+      isRequest: request =>
+        request.headers.get('x-client-platform') === 'capacitor'
+        && security.isNativeOrigin(request.headers.get('origin') ?? ''),
+    },
   },
   // ✅ 无需再传 verifyToken，iam.session.verifyToken 自动用于填充 context.session
 })
@@ -440,6 +455,7 @@ await apiClient.init({
 - `serv.listen(app, options)`：在 Node.js 启动 HTTP 服务，返回 `{ server, address, close }`
 - `serv.toFetch(app)`：包装为标准 `fetch(Request)` handler
 - `serv.generateSpec(contract, options)`：由 contract 生成 OpenAPI 3.1 spec
+- `serv.storageAssets(config)`：创建只读 Storage 资源 middleware，内置 key/MIME 白名单、GET/HEAD 与 ETag
 - `serv.requireAuth(handler)`：procedure 认证包装器（`context.session` 为空 → UNAUTHORIZED）
 - `serv.requirePermission(perm, handler)`：procedure 权限包装器（缺失权限 → FORBIDDEN）
 - `serv.requireRole(role, handler)`：procedure 角色包装器（缺失角色 → FORBIDDEN）
@@ -454,6 +470,7 @@ await apiClient.init({
 - HTTP App 抽象：`serv.createApp()` 返回具备 `fetch/request` 能力的公开应用对象；内部是否使用 Hono 不影响应用代码
 - `ServMiddlewareMount`：`createApp({ middlewares })` 的挂载项类型（`{ path?, middleware }`）
 - `ServMiddleware` / `ServProcedureWrapper` / `ServGuardedProcedureWrapper`：自定义 pipeline 时复用的共享类型
+- `NativeRefreshTokenTransportConfig` / `ServStorageAssetsConfig`：原生 Token 通道与只读资源 middleware 配置
 
 > 传输加密不作为 `serv.xxx` 扁平 API 暴露；它是 `createApp` 的配置能力，内部委托 `crypto.transport`。
 

package/dist/features/ai.d.ts

@@ -3,7 +3,7 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import * as _orpc_server from '@orpc/server';
 import { AIFunctions } from '@h-ai/ai';
-import { a as ServContext } from '../serv-context-CatIx8r-.js';
+import { a as ServContext } from '../serv-context-BUrtWoFC.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_server from '@orpc/server';
 import { IamFunctions } from '@h-ai/iam';
 export { TokenPair } from '@h-ai/iam';
-import { a as ServContext } from '../serv-context-CatIx8r-.js';
+import { a as ServContext } from '../serv-context-BUrtWoFC.js';
 import '@h-ai/core';
 
 /** IAM 默认 procedures 依赖。 */

package/dist/features/storage.d.ts

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

package/dist/index.d.ts

@@ -3,13 +3,14 @@ import { HaiResult, ValidationFormError } from '@h-ai/core';
 import { Router, implement } from '@orpc/server';
 import { AIFunctions, AudioWsStartMessage, AudioFormat } from '@h-ai/ai';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
-import { S as ServSession, a as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-CatIx8r-.js';
-export { d as CreateServContextInput, e as RefreshTokenPair } from './serv-context-CatIx8r-.js';
+import { S as ServSession, a as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, p as parseRequestContext, c as buildAuthContextFactory } from './serv-context-BUrtWoFC.js';
+export { d as CreateServContextInput, N as NativeRefreshTokenTransportConfig, e as RefreshTokenPair } from './serv-context-BUrtWoFC.js';
 import { MiddlewareHandler } from 'hono';
 import { z, ZodType } from 'zod';
 import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
 import { ServerType } from '@hono/node-server';
 import { AddressInfo } from 'node:net';
+import { StorageFunctions } from '@h-ai/storage';
 
 /**
  * @h-ai/serv — 统一语音 WebSocket 接入
@@ -323,9 +324,9 @@ interface ServHttpApp {
  *
  * - **`iam`**（推荐）：单一顶层引用。提供后 serv 自动：
  *   1. 使用 `iam.session.verifyToken` 填充 `context.session` → `requireAuth/Permission/Role` 生效
- *   2. 若同时启用 `refreshCookie`，使用 `iam.session.refresh` 实现 cookie 刷新
+ *   2. 若同时启用 `refreshCookie`，使用 `iam.session.refresh` 实现 refresh token 轮换
  *
- * - **`refreshCookie`**（可选）：opt-in httpOnly cookie 传输 refresh token。与 `iam` 正交：
+ * - **`refreshCookie`**（可选）：浏览器默认用 httpOnly cookie；受信原生客户端可配置 body 通道。与 `iam` 正交：
  *   `iam` 决定 *谁* 验证 token，`refreshCookie` 决定 refresh token *怎么* 传输。
  *
  * - **`verifyToken`**（高级）：不使用 IAM 模块的逆脱口。优先于 `iam.session.verifyToken`。
@@ -355,7 +356,7 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
      */
     readonly iam?: ServIam;
     /**
-     * 启用 httpOnly Cookie 传输 refresh token（opt-in）。
+     * 启用 refresh token 传输（opt-in）：浏览器使用 httpOnly Cookie，可选配置受信原生 body 通道。
      * 需配合 `iam` 或 `refreshCookie.onRefresh` 使用。
      */
     readonly refreshCookie?: RefreshCookieConfig;
@@ -772,6 +773,57 @@ interface ServRuntimeSecurityPolicy {
  */
 declare function createRuntimeSecurityPolicy(input: ServRuntimeSecurityPolicyInput): ServRuntimeSecurityPolicy;
 
+/**
+ * @h-ai/serv — Storage 只读资源 middleware
+ *
+ * 将经过路径与 MIME 白名单校验的 `@h-ai/storage` 文件作为 HTTP 资源返回，
+ * 统一处理 GET/HEAD、ETag 与缓存响应头，不包含头像等业务领域概念。
+ * @module serv-storage-assets
+ */
+
+/** 可由只读资源 middleware 使用的最小 Storage 能力。 */
+interface StorageAssetSource {
+    readonly file: Pick<StorageFunctions['file'], 'get' | 'head'>;
+}
+/** Storage 只读资源 middleware 配置。 */
+interface ServStorageAssetsConfig {
+    /** 已初始化的 Storage 模块或等价文件读取能力。 */
+    readonly storage: StorageAssetSource;
+    /**
+     * 从请求 pathname 中移除的路由前缀，例如 `/api/v1/assets/`。
+     * 是否挂载通配符仍由 `createApp({ middlewares })` 的 `path` 决定。
+     */
+    readonly pathPrefix: `/${string}`;
+    /** 允许访问的完整 Storage key 白名单；框架仍会先拒绝路径穿越与非法 key。 */
+    readonly keyPattern: RegExp;
+    /** 允许返回的 MIME 白名单。 */
+    readonly allowedContentTypes: readonly string[];
+    /** Cache-Control 响应头，默认 `no-store`。 */
+    readonly cacheControl?: string;
+    /** 可选的 Cross-Origin-Resource-Policy 响应头。 */
+    readonly crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin';
+}
+/**
+ * 创建由 Storage 提供内容的只读资源 middleware。
+ *
+ * 仅允许 GET/HEAD；非法路径、非白名单 MIME 与 Storage 读取失败统一返回 404，
+ * 避免向外暴露文件是否存在或后端错误细节。
+ *
+ * @param config - Storage、路径、key、MIME 与缓存策略。
+ * @returns 可挂载到 `serv.createApp({ middlewares })` 的 middleware。
+ * @example
+ * ```ts
+ * const middleware = serv.storageAssets({
+ *   storage,
+ *   pathPrefix: '/api/v1/avatar-assets/',
+ *   keyPattern: /^avatars\/[\w-]+\/[\w-]+\.webp$/,
+ *   allowedContentTypes: ['image/webp'],
+ *   cacheControl: 'public, max-age=31536000, immutable',
+ * })
+ * ```
+ */
+declare function storageAssets(config: ServStorageAssetsConfig): ServMiddleware;
+
 /**
  * @h-ai/serv — 校验工具
  *
@@ -848,6 +900,7 @@ declare const serv: {
     listen: typeof listen;
     toFetch: typeof toFetch;
     cors: typeof cors;
+    storageAssets: typeof storageAssets;
     createRuntimeSecurityPolicy: typeof createRuntimeSecurityPolicy;
     generateSpec: typeof generateSpec;
     /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
@@ -862,4 +915,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 AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, ServSession, type 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 ServGuardedProcedureWrapper, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, type ServProcedureWrapper, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -759,7 +759,8 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
     maxAge: config.maxAge ?? 30 * 24 * 3600,
     isSecure: config.secure ?? process2.env.NODE_ENV === "production",
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_PATHS.refresh}`,
-    onRefresh
+    onRefresh,
+    nativeTokenTransport: config.nativeTokenTransport
   };
 }
 function buildSetCookieHeader(name, value, path, maxAge, secure) {
@@ -809,7 +810,14 @@ function stripRefreshTokenFromPair(tokens) {
   };
 }
 function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
-  const { cookieName, maxAge, isSecure, refreshCookiePath, onRefresh } = resolveRefreshCookieConfig(apiPrefix, config, iam);
+  const {
+    cookieName,
+    maxAge,
+    isSecure,
+    refreshCookiePath,
+    onRefresh,
+    nativeTokenTransport
+  } = resolveRefreshCookieConfig(apiPrefix, config, iam);
   const loginPaths = [
     `${apiPrefix}${IAM_AUTH_PATHS.login}`,
     `${apiPrefix}${IAM_AUTH_PATHS.loginWithOtp}`,
@@ -817,6 +825,7 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
   ];
   for (const path of loginPaths) {
     app.post(path, async (c, next) => {
+      const useNativeTokenTransport = nativeTokenTransport?.isRequest(c.req.raw) === true;
       await next();
       if (c.res.status !== 200)
         return;
@@ -827,11 +836,13 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
         const body = JSON.parse(bodyText);
         if (body.success) {
           const refreshToken = extractRefreshTokenFromData(body.data);
-          if (refreshToken)
-            headers.append("Set-Cookie", buildSetCookieHeader(cookieName, refreshToken, refreshCookiePath, maxAge, isSecure));
-          body.data = stripRefreshTokenFromData(body.data);
-          responseBody = JSON.stringify(body);
-          headers.delete("Content-Length");
+          if (!useNativeTokenTransport) {
+            if (refreshToken)
+              headers.append("Set-Cookie", buildSetCookieHeader(cookieName, refreshToken, refreshCookiePath, maxAge, isSecure));
+            body.data = stripRefreshTokenFromData(body.data);
+            responseBody = JSON.stringify(body);
+            headers.delete("Content-Length");
+          }
         }
       } catch {
       }
@@ -839,6 +850,7 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
     });
   }
   app.post(`${apiPrefix}${IAM_AUTH_PATHS.logout}`, async (c, next) => {
+    const useNativeTokenTransport = nativeTokenTransport?.isRequest(c.req.raw) === true;
     await next();
     if (c.res.status !== 200)
       return;
@@ -846,14 +858,15 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
     const headers = new Headers(c.res.headers);
     try {
       const body = JSON.parse(bodyText);
-      if (body.success)
+      if (body.success && !useNativeTokenTransport)
         headers.append("Set-Cookie", buildClearCookieHeader(cookieName, refreshCookiePath));
     } catch {
     }
     c.res = new Response(bodyText, { status: c.res.status, statusText: c.res.statusText, headers });
   });
   app.post(`${apiPrefix}${IAM_AUTH_PATHS.refresh}`, async (c) => {
-    const refreshToken = getCookie(c, cookieName);
+    const useNativeTokenTransport = nativeTokenTransport?.isRequest(c.req.raw) === true;
+    const refreshToken = useNativeTokenTransport ? await readRefreshTokenFromBody(c.req.raw) : getCookie(c, cookieName);
     if (!refreshToken) {
       const locale = resolveRequestLocale(c.req.raw.headers);
       return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale })), 401);
@@ -861,16 +874,21 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
     const result = await onRefresh(refreshToken);
     if (!result.success) {
       const status = result.error.httpStatus ?? 401;
-      const clearCookie = buildClearCookieHeader(cookieName, refreshCookiePath);
+      const headers = new Headers({ "Content-Type": "application/json" });
+      if (!useNativeTokenTransport)
+        headers.set("Set-Cookie", buildClearCookieHeader(cookieName, refreshCookiePath));
       return new Response(JSON.stringify({ success: false, error: result.error }), {
         status,
-        headers: {
-          "Content-Type": "application/json",
-          "Set-Cookie": clearCookie
-        }
+        headers
       });
     }
     const tokens = result.data;
+    if (useNativeTokenTransport) {
+      return new Response(JSON.stringify({ success: true, data: { tokens } }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
     const setCookie = buildSetCookieHeader(cookieName, tokens.refreshToken, refreshCookiePath, maxAge, isSecure);
     return new Response(JSON.stringify({ success: true, data: { tokens: stripRefreshTokenFromPair(tokens) } }), {
       status: 200,
@@ -881,6 +899,10 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
     });
   });
 }
+async function readRefreshTokenFromBody(request) {
+  const body = await request.json().catch(() => void 0);
+  return typeof body?.refreshToken === "string" && body.refreshToken.length > 0 ? body.refreshToken : void 0;
+}
 var SCALAR_ROUTE = "/_hai/scalar.js";
 var SCALAR_BROWSER_ENTRY_FALLBACK = "./dist/browser/standalone.js";
 var scalarScriptCache;
@@ -1470,6 +1492,68 @@ function tryNormalizeNativeOrigin(value) {
   return ["capacitor:", "tauri:"].includes(url.protocol) ? `${url.protocol}//${url.host}` : url.origin;
 }
 
+// src/serv-storage-assets.ts
+function storageAssets(config) {
+  const pathPrefix = config.pathPrefix.endsWith("/") ? config.pathPrefix : `${config.pathPrefix}/`;
+  const allowedKeyPattern = new RegExp(config.keyPattern.source, config.keyPattern.flags.replace(/[gy]/g, ""));
+  const allowedContentTypes = new Set(config.allowedContentTypes);
+  return async (c) => {
+    const request = c.req.raw;
+    const path = new URL(request.url).pathname;
+    if (request.method !== "GET" && request.method !== "HEAD")
+      return c.body(null, 405, { Allow: "GET, HEAD" });
+    if (!path.startsWith(pathPrefix))
+      return notFound(c);
+    const key = decodeStorageAssetKey(path.slice(pathPrefix.length), allowedKeyPattern);
+    if (!key)
+      return notFound(c);
+    const metadata = await config.storage.file.head(key);
+    if (!metadata.success || !allowedContentTypes.has(metadata.data.contentType))
+      return notFound(c);
+    const headers = {
+      "Cache-Control": config.cacheControl ?? "no-store",
+      "Content-Length": String(metadata.data.size),
+      "Content-Type": metadata.data.contentType,
+      ...config.crossOriginResourcePolicy ? { "Cross-Origin-Resource-Policy": config.crossOriginResourcePolicy } : {},
+      ...metadata.data.etag ? { ETag: metadata.data.etag } : {}
+    };
+    if (metadata.data.etag && matchesEtag(request.headers.get("if-none-match"), metadata.data.etag))
+      return c.body(null, 304, headers);
+    if (request.method === "HEAD")
+      return c.body(null, 200, headers);
+    const file = await config.storage.file.get(key);
+    if (!file.success)
+      return notFound(c);
+    return c.body(Uint8Array.from(file.data).buffer, 200, headers);
+  };
+}
+function decodeStorageAssetKey(value, allowedKeyPattern) {
+  try {
+    const key = decodeURIComponent(value);
+    if (key.length === 0 || key.length > 1024 || key.startsWith("/") || key.includes("\\") || key.includes("\0") || key.split("/").some((segment) => segment === "." || segment === "..")) {
+      return void 0;
+    }
+    const match = allowedKeyPattern.exec(key);
+    return match?.[0] === key ? key : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function matchesEtag(ifNoneMatch, etag) {
+  if (!ifNoneMatch)
+    return false;
+  if (ifNoneMatch.trim() === "*")
+    return true;
+  const expected = normalizeEtag(etag);
+  return ifNoneMatch.split(",").some((candidate) => normalizeEtag(candidate) === expected);
+}
+function normalizeEtag(value) {
+  return value.trim().replace(/^W\//i, "");
+}
+function notFound(c) {
+  return c.body(null, 404, { "Cache-Control": "no-store" });
+}
+
 // src/serv-main.ts
 var serv = {
   // 应用与上下文
@@ -1481,6 +1565,7 @@ var serv = {
   listen,
   toFetch,
   cors,
+  storageAssets,
   createRuntimeSecurityPolicy,
   // OpenAPI / 导出
   generateSpec,