feat: add configurable transport-independent CORS policy

2026-09-26 19:53:28 +08:00
parent 9fade3bedb
commit 800974cfff
33 changed files with 1645 additions and 23 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog

+## v0.24.0-preview（2026-09-26）
+
+- 新增可选 cors 包和 server.cors 配置；生成项目直接加载，手写项目使用 omni.WithCORS，独立 HTTP 服务可使用 Policy.Wrap。默认关闭，无新增第三方依赖。
+- 精确来源白名单、方法/请求头、暴露头、凭据和预检缓存可配置；拒绝凭据与通配来源混用、非法来源/头及歧义的重复请求头，校验错误定位具体字段。
+- 在路由和鉴权之前处理预检；实际请求仍执行原有中间件，统一响应、404/405、上传下载和流式能力保持。nethttp/native/HTTP2 共用策略。
+- 补充真实生成项目、TLS 三种 transport、20 项真实浏览器检查、race/fuzz/性能基准；同步 README、配置指南、cors 指南及 examples/cors。
+- 没有移除现有功能或修改默认跨域行为。代理已负责 CORS 的项目保持关闭，避免重复头；高级调用 Router().ServeHTTP 不经过应用外层 CORS。
+
 ## v0.23.0-preview（2026-09-26）

 - MySQL/连接池、日志、HTTP 客户端、生命周期和请求策略返回字段级安全诊断，配置加载器保留文件/变量/位置与原始错误链。
--- a/CONFIG.md
+++ b/CONFIG.md
@@ -189,3 +189,7 @@ Decoder 返回 Document（map/string/bool/json.Number/nil/[]any，XML 类标量
 5. 升级匹配的 CLI 与框架，执行 generate、generate --check、go test、go build 和 `-check-config`，再使用真实部署配置启动。

 低层 `DecodeFile(path, defaults[, loader])` 也解析显式引用，但不调用 Validate；默认值和原始 Document 都不会因失败而被部分修改。日志 Reloader 仍只允许 log.level 变化，其他静态字段变更要求重启。
+
+## 跨域配置
+
+生成项目的 `server.cors` 由本加载流程直接绑定、校验并交给 App，不需要修改生成入口。支持固定来源数组或元素内显式环境引用；非法来源定位具体数组元素。默认关闭，完整配置与行为见 [CORS 指南](cors/README.md)。
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -1,4 +1,4 @@
-# 通用业务开发指南（v0.23.0-preview）
+# 通用业务开发指南（v0.24.0-preview）

 从 [README](README.md) 创建服务后，业务主要维护 `.api`、配置、`svc.Init`、Logic、Repository 和项目中间件。本页说明通用接入能力；字段、错误码、权限、表结构和事务边界都由项目定义。

--- a/MODULES.md
+++ b/MODULES.md
@@ -22,7 +22,7 @@ app.GET("/metrics", measurements.Handler())
 // 也可以直接读取 measurements.Snapshot()。
 ```

-记录请求数、失败数、处理中数量、累计耗时与 HTTP 状态分布；返回的是 JSON 快照，并非 Prometheus 文本格式。指标接口是否暴露以及访问权限由项目配置。需要 HTTP/SQL/Redis spans 和标准 OTel exporter 时，使用 [telemetry 示例](examples/platform/main.go)。CORS 由项目中间件或代理配置，当前没有内置 CORS 模块。
+记录请求数、失败数、处理中数量、累计耗时与 HTTP 状态分布；返回的是 JSON 快照，并非 Prometheus 文本格式。指标接口是否暴露以及访问权限由项目配置。需要 HTTP/SQL/Redis spans 和标准 OTel exporter 时，使用 [telemetry 示例](examples/platform/main.go)。需要跨域时配置 `server.cors`，由框架在路由与鉴权前处理预检；默认关闭。已有代理 CORS 可继续使用，避免两处重复设置。见 [CORS 配置与示例](cors/README.md)。

 ## 缓存：cache 与 cache/redis

--- a/PROJECT.md
+++ b/PROJECT.md
@@ -1,6 +1,6 @@
 # 生成项目与文件维护边界

-v0.23.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。
+v0.24.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。

 ## 创建和日常开发

@@ -215,7 +215,7 @@ get /download (DownloadReq)

 ## 已有服务接入步骤

-每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.23.0-preview：
+每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.24.0-preview：

 1. 先保留旧服务，整理实际路由及现有响应、鉴权和超时要求。在新目录执行 `go-omni new --api /path/to/service.api --module example.com/service ./service`；不对旧入口强制覆盖。
 2. 在 `.api` 中选择 `@app(defaultResponse: ...)`，显式保留原项目的字段、成功码、错误码和 `dataMode`。需要独立回执的路由单独声明 raw/produces。普通路由、404/405 和提前返回的中间件一起验收。
--- a/README.md
+++ b/README.md
@@ -2,7 +2,9 @@

 GoOmni 是面向多个业务项目复用的 Go 后端框架：用 `.api` 定义接口、请求和返回类型，生成项目目录、HTTP 接入代码及 OpenAPI，业务代码负责 Logic 和 Repository。也可以在已有项目中直接使用 `omni.New()`，或单独引入日志、存储等模块。

-**从这份 README 开始接入。** 当前版本 **`v0.23.0-preview`**，新生成项目采用根目录入口和 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。
+**从这份 README 开始接入。** 当前版本 **`v0.24.0-preview`**，新生成项目采用根目录入口和 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。
+
+**v0.24 改动**：新增可选 CORS，生成项目通过 `server.cors` 自动接入，支持预检、错误响应和明确的来源白名单；默认关闭。[配置与规则](cors/README.md)、[可运行示例](examples/cors/README.md)。

 **v0.23 改动**：配置校验定位具体字段和安全原因；`httpc.JSON` 可选限制成功状态；`copyx.Check` 无需样本预检类型；`logx` 支持实例独立时区。[四项完整示例](examples/developerTools/README.md)。

@@ -33,6 +35,7 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 | 中间件依赖工厂、可选 Repository | `omni.gen.json` 选择 factories / none；在 `New<Name>(deps)` 写一次实现 | [配置与完整工厂示例](GENERATION.md) |
 | 路由、分组、请求上下文 | `omni.New()`、`app.GET` / `Group` / `Use`；业务使用 `context.Context` | [基本服务](examples/basic/main.go)、[已有项目接入](#已有项目按模块接入) |
 | HTTP 网络与扩展适配 | 配置 transport 为 nethttp / native / http2；自定义 Router/Runner | [网络层配置与契约](transport/README.md)、[性能与限制](PERFORMANCE.md) |
+| 浏览器跨域 CORS | `server.cors` / `omni.WithCORS`；独立 HTTP 用 `cors.New(...).Wrap(handler)` | [配置、默认值与协议边界](cors/README.md)、[鉴权与预检示例](examples/cors/README.md) |
 | HTTP 老接口桥接 | 通过官方 Handler/Middleware 适配器接入标准 `net/http`，跟踪实际响应状态 | [接入说明](MIGRATION.md)、[桥接/上传/自定义 ID 示例](examples/compatibility/main.go) |
 | 请求校验、动态 JSON、自定义标量 | `.api` 声明来源/校验/scalar；手写契约用 `contract.New[T]`；简单绑定可用 `validate.JSON/Query/URI` | [语法与例子](API.md)、[请求策略](DEVELOPMENT.md) |
 | 数组、null、原始请求、上传下载 | `.api` 声明数组/可空返回、body/multipart 与大小限制；必要时使用 Bind/Manual 扩展 | [契约示例](examples/contracts)、[含上传/回调/下载的项目](examples/managedService/README.md) |
@@ -56,6 +59,26 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 | 可选结构转换与深拷贝 | `copyx.Copy` / `Clone` / `New`；`Check[S,T]` 预检类型，Go converter 处理差异 | [下方示例](#可选结构转换与深拷贝)、[完整 copyx 指南](COPY.md)、[可运行代码](examples/copying) |
 | 自定义适配器验收 | `transporttest.Run`、`storagetest.Run` / `RunUploads` 验证扩展契约 | [网络契约测试入口](transport/transporttest/router.go)、[存储契约测试入口](storage/storagetest/contract.go) |

+## 浏览器跨域 CORS
+
+同源部署保持默认关闭；需要跨域时，在生成项目的配置文件中加入：
+
+```yaml
+server:
+  cors:
+    enabled: true
+    allowedOrigins: [https://admin.example.com, https://merchant.example.com]
+    allowedMethods: [GET, HEAD, POST, PUT, PATCH, DELETE]
+    allowedHeaders: [Authorization, Content-Type]
+    exposedHeaders: [Content-Disposition, X-Request-ID]
+    allowCredentials: false
+    maxAge: 10m
+```
+
+不需要修改 main、Logic 或 `.api`。框架在鉴权前处理合法预检；实际请求仍鉴权，401/404/405/500 保持项目响应格式并附带允许来源的跨域头。没有 Origin 的服务端回调正常处理。配置只决定浏览器读取权限，不替代登录、验签或 CSRF 防护。
+
+手写项目用 `omni.WithCORS(omni.CORSConfig{...})`，独立 HTTP 服务用 `cors.New(...).Wrap(handler)`；代理已经处理 CORS 时保持关闭。完整 [默认值与边界](cors/README.md)、[可运行示例](examples/cors/README.md)。
+
 ## 带认证的出站 HTTP

 HTTP Client 在 svc 初始化一次，业务重复使用。普通内部请求可直接选择直连和连接参数，无需手写 Transport：
@@ -128,7 +151,7 @@ module 地址是 `git.yuntuo.hk/k2safe/go-omni`。先确保本机 Go 和 Git 可

 ```sh
 export GOPRIVATE="$(go env GOPRIVATE),git.yuntuo.hk"
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.23.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.24.0-preview
 export PATH="$(go env GOPATH)/bin:$PATH"
 go-omni --help
 ```
@@ -285,7 +308,7 @@ go-omni new --api catalog.api \
 在业务项目的 **go.mod 所在目录**执行：

 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.23.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.24.0-preview
 ```

 已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。希望入口和 HTTP 接入都交给生成器的项目，按 [已有服务接入步骤](PROJECT.md#已有服务接入步骤) 在新目录生成后迁入业务代码。
@@ -611,7 +634,7 @@ go test ./...

 `main.go`、`Gen.go`、`docs/openapi.json` 和 manifest 由生成器管理，手动修改会报告冲突。Logic、Repository、中间件实现、配置和依赖装配属于项目，重复生成保留手写内容。契约变化会提示受影响的 Logic 文件和 DTO 字段，明确的签名错误会给出原签名与期望签名；生成后 `--check` 仍能检出未修复的问题。将 `.api`、`omni.gen.json`、生成文件和 `.goOmni/apiManifest.json` 一起提交，CI 同时运行 `generate --check` 与 `go test ./...`。详见 [契约变更提示与检查边界](PROJECT.md#契约变更提示)。

-CLI 与业务 module 固定使用 `v0.23.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
+CLI 与业务 module 固定使用 `v0.24.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。

 ## 按需深入

--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,4 +1,27 @@
-# v0.23.0-preview
+# v0.24.0-preview
+
+业务项目通过配置开启跨域，不需要手写 OPTIONS Handler 或逐条修改接口。
+
+- 默认关闭，在 `server.cors` 显式配置来源、方法和请求头；统一文件加载、环境引用和字段级诊断自动生效。生成项目无需修改 main、svc 或 `.api`。
+- 预检在鉴权前返回 204/403 空响应；实际请求继续鉴权、业务错误编码和路由处理。允许来源可读取 401/403/404/405/500，上传下载和流式能力保留。
+- 只支持精确 HTTP(S) 来源，公开无凭据服务可配置单一 `*`；禁止 `*` 与凭据混用。配置初始化快照、请求并发隔离、Vary 缓存分流和有界请求头处理。
+- 同一个 App 策略覆盖标准库、native 和 HTTP2；独立服务可使用 `cors.New(...).Wrap(handler)`。没有新增第三方依赖，没有移除现有功能。
+
+```sh
+go get git.yuntuo.hk/k2safe/go-omni@v0.24.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.24.0-preview
+go-omni api generate
+go-omni api generate --check
+go run . -config etc/config.yaml -check-config
+```
+
+现有项目不配置 CORS 时行为不变。代理已处理 CORS 的项目继续关闭；跨域不替代登录、权限或 CSRF 防护。通过 App/Engine/Run 接入，直接对外暴露底层 Router 会绕过应用外层策略。本轮新增 runtime 配置需 v0.24，未使用该配置的模板最低版本仍为 v0.22。
+
+[配置与规则](cors/README.md)、[可运行示例](examples/cors/README.md)、[验收与性能](reports/corsAcceptance.md) 已同步。49 个测试包全量 race、Go 1.22、vet/build、实际生成项目、三种 transport 的 TLS 场景和 20 项真实浏览器检查通过；30 秒 fuzz 约 288 万次。当前仍为 preview。
+
+---
+
+# v0.23.0-preview（历史版本）

 减少业务接入时重复维护的配置校验、HTTP 包装和类型检查。

--- a/app/app.go
+++ b/app/app.go
@@ -12,6 +12,7 @@ import (
 	"time"

 	"git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/cors"
 	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
@@ -24,6 +25,7 @@ import (
 // httpx.Router, leaving the network implementation replaceable.
 type App struct {
 	router           httpx.Router
+	handler          http.Handler
 	config           config.Config
 	middlewares      []httpx.Middleware
 	closers          []func() error
@@ -67,6 +69,11 @@ func configure(options ...config.Option) config.Config {
 }

 func newApp(router httpx.Router, settings config.Config) *App {
+	settings.CORS = settings.CORS.Clone()
+	corsPolicy, corsErr := cors.New(settings.CORS)
+	if corsErr != nil {
+		panic(config.AtField("cors", corsErr))
+	}
 	settings.Response = settings.Response.Clone()
 	settings.Errors = settings.Errors.Clone()
 	encoder, responseErr := response.New(settings.Response)
@@ -93,6 +100,7 @@ func newApp(router httpx.Router, settings config.Config) *App {
 	}
 	middlewares = append(middlewares, middleware.Recovery())
 	application := &App{router: router, config: settings, middlewares: middlewares, clientIPResolver: resolver, responseEncoder: responseEncoder}
+	application.handler = corsPolicy.Wrap(router)
 	if fallback, ok := router.(httpx.FallbackRouter); ok {
 		adaptError := func(status int, code, message string) http.Handler {
 			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -104,21 +112,23 @@ func newApp(router httpx.Router, settings config.Config) *App {
 	return application
 }

-// Router returns the transport contract used by this application.
+// Router exposes the underlying routing contract for advanced registration.
+// Serve requests through App or Engine so application CORS policy is applied.
 func (a *App) Router() httpx.Router { return a.router }

 // Engine is kept as a compatibility name for the old API. It returns a
 // standard http.Handler, so callers do not depend on a router type.
-func (a *App) Engine() http.Handler { return a.router }
+func (a *App) Engine() http.Handler { return a.handler }

 // ServeHTTP implements http.Handler for standard servers and HTTP tests.
 func (a *App) ServeHTTP(writer http.ResponseWriter, request *http.Request) {
-	a.router.ServeHTTP(writer, request)
+	a.handler.ServeHTTP(writer, request)
 }

 // Config returns the effective application configuration.
 func (a *App) Config() config.Config {
 	settings := a.config
+	settings.CORS = settings.CORS.Clone()
 	settings.Response = settings.Response.Clone()
 	settings.Errors = settings.Errors.Clone()
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
@@ -177,7 +187,7 @@ func (a *App) NewServer(address string) *http.Server {
 		}
 	}
 	cfg := a.config.HTTP
-	return &http.Server{Addr: address, Handler: a.router,
+	return &http.Server{Addr: address, Handler: a.handler,
 		ReadHeaderTimeout: cfg.ReadHeaderTimeout, ReadTimeout: cfg.ReadTimeout,
 		WriteTimeout: cfg.WriteTimeout, IdleTimeout: cfg.IdleTimeout,
 		MaxHeaderBytes: cfg.MaxHeaderBytes, ErrorLog: cfg.ErrorLog}
--- a/app/cors_test.go
+++ b/app/cors_test.go
@@ -0,0 +1,187 @@
+package app_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/internal/testutil"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+)
+
+func corsApp() *omni.App {
+	return omni.New(omni.WithCORS(omni.CORSConfig{Enabled: true, AllowedOrigins: []string{"https://web.example"}, AllowedMethods: []string{"GET", "POST", "PUT"}, AllowedHeaders: []string{"Authorization", "Content-Type"}, ExposedHeaders: []string{"Content-Disposition"}}), omni.WithResponse(response.Config{CodeType: "int32", SuccessCode: 0, ErrorCode: 999, MessageField: "msg", DataMode: "always"}))
+}
+func TestAppCORSRoutingAndErrors(t *testing.T) {
+	a := corsApp()
+	defer a.Close()
+	var middlewareCalls int
+	a.Use(func(next omni.Handler) omni.Handler {
+		return func(c *omni.Context) error { middlewareCalls++; return next(c) }
+	})
+	a.GET("/secure", func(c *omni.Context) error { return c.OK("private") }, func(next omni.Handler) omni.Handler {
+		return func(c *omni.Context) error { return omni.Unauthorized("LOGIN_REQUIRED", "login required") }
+	})
+	a.GET("/failure", func(c *omni.Context) error { return omni.Internal(errors.New("private detail")) })
+	a.GET("/panic", func(c *omni.Context) error { panic("private panic") })
+	a.Handle("OPTIONS", "/options", func(c *omni.Context) error { return c.Text(200, "ordinary options") })
+	for name, entry := range map[string]http.Handler{"App": a, "Engine": a.Engine(), "NewServer": a.NewServer("").Handler} {
+		t.Run(name, func(t *testing.T) {
+			for _, tc := range []struct {
+				method, path string
+				status       int
+			}{{"GET", "/secure", 401}, {"GET", "/failure", 500}, {"GET", "/panic", 500}, {"GET", "/absent", 404}, {"PUT", "/secure", 405}} {
+				r := httptest.NewRequest(tc.method, tc.path, nil)
+				r.Header.Set("Origin", "https://web.example")
+				w := httptest.NewRecorder()
+				entry.ServeHTTP(w, r)
+				var body map[string]any
+				err := json.Unmarshal(w.Body.Bytes(), &body)
+				if err != nil || w.Code != tc.status || w.Header().Get("Access-Control-Allow-Origin") != "https://web.example" || body["code"] != float64(999) || body["data"] != nil || body["msg"] == nil || strings.Contains(w.Body.String(), "private") {
+					t.Fatal(w.Code, w.Header(), w.Body.String(), err)
+				}
+			}
+			for _, path := range []string{"/secure", "/absent"} {
+				before := middlewareCalls
+				r := httptest.NewRequest("OPTIONS", path, nil)
+				r.Header.Set("Origin", "https://web.example")
+				r.Header.Set("Access-Control-Request-Method", "POST")
+				r.Header.Set("Access-Control-Request-Headers", "authorization,content-type")
+				w := httptest.NewRecorder()
+				entry.ServeHTTP(w, r)
+				if w.Code != 204 || w.Body.Len() != 0 || middlewareCalls != before {
+					t.Fatal(w.Code, w.Body.String(), middlewareCalls, before)
+				}
+			}
+			r := httptest.NewRequest("OPTIONS", "/options", nil)
+			w := httptest.NewRecorder()
+			entry.ServeHTTP(w, r)
+			if w.Code != 200 || w.Body.String() != "ordinary options" {
+				t.Fatal(w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+func TestAppCORSConfigIsolation(t *testing.T) {
+	cfg := config.Default()
+	cfg.CORS = omni.CORSConfig{Enabled: true, AllowedOrigins: []string{"https://one.example"}, AllowedHeaders: []string{"Authorization"}}
+	option := omni.WithConfig(cfg)
+	cfg.CORS.AllowedOrigins[0] = "https://evil.example"
+	a := omni.New(option)
+	defer a.Close()
+	b := omni.New(option)
+	defer b.Close()
+	a.Config().CORS.AllowedOrigins[0] = "https://evil.example"
+	for _, app := range []*omni.App{a, b} {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/absent", nil)
+		r.Header.Set("Origin", "https://one.example")
+		app.ServeHTTP(w, r)
+		if w.Header().Get("Access-Control-Allow-Origin") != "https://one.example" {
+			t.Fatal(w.Header())
+		}
+	}
+	defer func() {
+		if recover() == nil {
+			t.Error("invalid CORS passed direct New")
+		}
+	}()
+	omni.New(omni.WithCORS(omni.CORSConfig{Enabled: true}))
+}
+
+func TestCORSTransports(t *testing.T) {
+	for _, transport := range []string{omni.TransportNetHTTP, omni.TransportNative, omni.TransportHTTP2} {
+		t.Run(transport, func(t *testing.T) {
+			cert, key, tlsClient := testutil.CertificateFiles(t)
+			cfg := omni.CORSConfig{Enabled: true, AllowedOrigins: []string{"https://web.example"}, AllowedMethods: []string{"GET", "POST"}, AllowedHeaders: []string{"Content-Type"}, ExposedHeaders: []string{"Content-Disposition"}}
+			a := omni.New(omni.WithCORS(cfg), omni.WithTransport(transport), omni.WithTLS(cert, key))
+			var called atomic.Int32
+			a.Use(func(next omni.Handler) omni.Handler {
+				return func(c *omni.Context) error { called.Add(1); return next(c) }
+			})
+			a.POST("/upload", func(c *omni.Context) error {
+				b, err := io.ReadAll(c.Request().Body)
+				if err != nil {
+					return err
+				}
+				return c.Text(200, string(b))
+			})
+			a.GET("/download", func(c *omni.Context) error {
+				return c.WriteStream(200, "application/octet-stream", &httpx.Stream{Content: io.NopCloser(strings.NewReader("file bytes")), Name: "example.txt"})
+			})
+			listener, err := net.Listen("tcp", "127.0.0.1:0")
+			if err != nil {
+				t.Fatal(err)
+			}
+			ctx, cancel := context.WithCancel(context.Background())
+			done := make(chan error, 1)
+			go func() { done <- a.ServeContext(ctx, listener) }()
+			defer func() {
+				cancel()
+				select {
+				case err := <-done:
+					if err != nil {
+						t.Error(err)
+					}
+				case <-time.After(5 * time.Second):
+					t.Error("server did not close")
+					listener.Close()
+				}
+			}()
+			client := &http.Client{Timeout: 5 * time.Second, Transport: &http.Transport{TLSClientConfig: tlsClient, ForceAttemptHTTP2: true}}
+			defer client.CloseIdleConnections()
+			url := "https://" + listener.Addr().String()
+			for _, tc := range []struct {
+				method, path, body string
+				status             int
+			}{{"OPTIONS", "/upload", "", 204}, {"POST", "/upload", "raw upload", 200}, {"GET", "/download", "file bytes", 200}, {"GET", "/missing", "", 404}} {
+				var input io.Reader
+				if tc.method == "POST" {
+					input = strings.NewReader(tc.body)
+				}
+				r, _ := http.NewRequest(tc.method, url+tc.path, input)
+				r.Header.Set("Origin", "https://web.example")
+				if tc.method == "OPTIONS" {
+					r.Header.Set("Access-Control-Request-Method", "POST")
+					r.Header.Set("Access-Control-Request-Headers", "content-type")
+				}
+				res, err := client.Do(r)
+				if err != nil {
+					t.Fatal(err)
+				}
+				body, err := io.ReadAll(res.Body)
+				res.Body.Close()
+				if err != nil {
+					t.Fatal(err)
+				}
+				if res.StatusCode != tc.status || res.Header.Get("Access-Control-Allow-Origin") != "https://web.example" {
+					t.Fatal(res.StatusCode, res.Header)
+				}
+				if tc.status == 200 && string(body) != tc.body {
+					t.Fatal(string(body))
+				}
+				if tc.status == 204 && (len(body) != 0 || called.Load() != 0) {
+					t.Fatal("preflight reached middleware")
+				}
+				if tc.path == "/download" && (!strings.Contains(res.Header.Get("Content-Disposition"), "example.txt") || res.Header.Get("Access-Control-Expose-Headers") != "Content-Disposition") {
+					t.Fatal(res.Header)
+				}
+				if transport == omni.TransportHTTP2 && res.ProtoMajor != 2 {
+					t.Fatal(res.Proto)
+				}
+			}
+		})
+	}
+}
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -14,7 +14,7 @@ v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目

 ```sh
 # 仓库读取权限与 PATH 配置见根目录 README
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.23.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.24.0-preview
 go-omni new --module example.com/hello ./hello

 # 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
@@ -49,14 +49,14 @@ main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节

 ## 版本与迁移

-CLI 与框架依赖固定使用 v0.23.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
+CLI 与框架依赖固定使用 v0.24.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：

 ```sh
 # 在 go-omni 源码仓库中执行
 go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
 ```

-当前模板与依赖以 v0.23.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
+当前模板与依赖以 v0.24.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。

 ## 数据库迁移命令

--- a/cmd/go-omni/apigen/corsConsumer_test.go
+++ b/cmd/go-omni/apigen/corsConsumer_test.go
@@ -0,0 +1,59 @@
+package apigen
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+func TestGeneratedCORSConsumer(t *testing.T) {
+	if os.Getenv("GO_OMNI_SCAFFOLD_INTEGRATION") != "1" {
+		t.Skip("set GO_OMNI_SCAFFOLD_INTEGRATION=1")
+	}
+	dir := filepath.Join(t.TempDir(), "app")
+	api := filepath.Join(t.TempDir(), "service.api")
+	writeFile(t, api, "service corsdemo {\n@handler ping\nget /ping\n}\n")
+	o := Options{API: api, Dir: dir, Module: "example.com/corsdemo", FrameworkDir: frameworkRoot(t)}
+	if err := generateManagedTestProject(t, o); err != nil {
+		t.Fatal(err)
+	}
+	writeFile(t, filepath.Join(dir, "consumer_test.go"), readFile(t, "testdata/cors/consumer_test.go"))
+	writeFile(t, filepath.Join(dir, "etc/config.yaml"), "server:\n  log:\n    output: discard\n  cors:\n    enabled: true\n    allowedOrigins: [https://web.example]\n    allowedMethods: [GET, POST, PUT]\n    allowedHeaders: [Authorization, Content-Type]\n    maxAge: 10m\n")
+	runConsumerGo(t, dir, "mod", "tidy")
+	runConsumerGo(t, dir, "test", "-race", "-count=1", "./...")
+	runConsumerGo(t, dir, "build", ".")
+	o.API = filepath.Join(dir, "api/service.api")
+	before := snapshot(t, dir)
+	for _, mode := range []string{"dry", "generate", "check"} {
+		o.DryRun = mode == "dry"
+		o.Check = mode == "check"
+		if err := generateManagedTestProject(t, o); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if !sameFiles(before, snapshot(t, dir)) {
+		t.Fatal("regeneration changed project files")
+	}
+	if os.Getenv("GO_OMNI_RELEASE_CLI") != "" {
+		cmd := exec.Command("go", "list", "-m", "-json", frameworkModule)
+		cmd.Dir = dir
+		cmd.Env = append(os.Environ(), "GOWORK=off")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatal(err, string(out))
+		}
+		var dependency struct {
+			Version, Sum string
+			Replace      any
+		}
+		if err := json.Unmarshal(out, &dependency); err != nil {
+			t.Fatal(err)
+		}
+		if dependency.Version != os.Getenv("GO_OMNI_RELEASE_VERSION") || dependency.Replace != nil || dependency.Sum == "" {
+			t.Fatal("not a fixed remote consumer")
+		}
+		t.Logf("remote framework %s checksum %s; no local replace", dependency.Version, dependency.Sum)
+	}
+}
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -22,7 +22,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"

 // Runtime-only releases need not raise the managed template compatibility floor.
 const minimumVersion = "v0.22.0-preview"
-const currentVersion = "v0.23.0-preview"
+const currentVersion = "v0.24.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
--- a/cmd/go-omni/apigen/templates.go
+++ b/cmd/go-omni/apigen/templates.go
@@ -62,7 +62,10 @@ Ordinary Logic uses the generated Request/Response types directly. Where an
 independent business type is needed, use ordinary Go or the optional copyx package.
 Configuration loading is generator-managed in internal/config/loadGen.go. Extend fields/defaults/Validate in config.go; additional decoders belong in loader.go/NewLoader. JSON/YAML/XML use explicit ${NAME} / ${NAME:-fallback} references; fixed values are never overridden by inferred environment names. Use -check-config to validate without opening dependencies. Framework validation
 identifies fields such as server.log.level and database.port. server.log.timeZone
-optionally selects a per-logger IANA zone. See the framework CONFIG.md.
+optionally selects a per-logger IANA zone. Optional server.cors is loaded and installed
+automatically before routing/authentication; disabled by default. Configure allowedOrigins,
+allowedMethods and allowedHeaders in the selected file; no main/handler edits.
+See the framework CONFIG.md and cors/README.md.

 There are no mappings/mappingFiles settings or generated mapping files in v0.19.
 See COPY.md in the framework repository for copy policies and migration steps,
--- a/cmd/go-omni/apigen/testdata/cors/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/cors/consumer_test.go
@@ -0,0 +1,69 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"example.com/corsdemo/internal/config"
+	"example.com/corsdemo/internal/handler"
+	"example.com/corsdemo/internal/svc"
+	omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestGeneratedCORSConfiguration(t *testing.T) {
+	cfg, err := config.Load("etc/config.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	logger, err := logx.New(cfg.Server.Log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	deps, err := svc.New(context.Background(), logger, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer deps.Close()
+	a, err := handler.NewApp(deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer a.Close()
+	for _, tc := range []struct {
+		method, path string
+		status       int
+	}{{"GET", "/ping", 501}, {"GET", "/missing", 404}, {"PUT", "/ping", 405}, {"GET", "/health/live", 200}, {"GET", "/health/ready", 200}, {"GET", "/openapi.json", 200}, {"OPTIONS", "/ping", 204}} {
+		r := httptest.NewRequest(tc.method, tc.path, nil)
+		r.Header.Set("Origin", "https://web.example")
+		if tc.method == "OPTIONS" {
+			r.Header.Set("Access-Control-Request-Method", "GET")
+			r.Header.Set("Access-Control-Request-Headers", "authorization")
+		}
+		w := httptest.NewRecorder()
+		a.ServeHTTP(w, r)
+		if w.Code != tc.status || w.Header().Get("Access-Control-Allow-Origin") != "https://web.example" {
+			t.Fatal(tc, w.Code, w.Header(), w.Body.String())
+		}
+		if tc.status == 204 && (w.Body.Len() != 0 || w.Header().Get("Access-Control-Max-Age") != "600") {
+			t.Fatal(w)
+		}
+	}
+	// Startup config validation uses the normal generated run/Load, before log
+	// files or dependencies. No changes to generated main/HTTP composition.
+	path := filepath.Join(t.TempDir(), "invalid.yaml")
+	if err := os.WriteFile(path, []byte("server:\n  cors:\n    enabled: true\n    allowedOrigins: ['*']\n    allowCredentials: true\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	err = run(context.Background(), path)
+	var d *omniConfig.Error
+	if !errors.As(err, &d) || d.Field != "server.cors.allowedOrigins[0]" || !strings.Contains(d.Reason, "allowCredentials") {
+		t.Fatal(err)
+	}
+}
--- a/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
@@ -1,5 +1,6 @@
 # Only fields listed here override Default(). Environment names are explicit.
 server:
+  # Optional cross-origin access: server.cors (disabled by default). See framework cors/README.md.
  address: "${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}"
  transport: "${GO_OMNI_TRANSPORT:-nethttp}"
 {{if ne .Storage "none"}}storage:
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.23.0-preview"
+const defaultFrameworkVersion = "v0.24.0-preview"

 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.
--- a/config/config.go
+++ b/config/config.go
@@ -5,6 +5,7 @@ import (
 	"time"

 	"git.yuntuo.hk/k2safe/go-omni/contract"
+	"git.yuntuo.hk/k2safe/go-omni/cors"
 	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
@@ -28,6 +29,7 @@ type TLSConfig struct {

 // Config controls the default runtime behavior of an App.
 type Config struct {
+	CORS                 cors.Config              `json:"cors"`
 	Request              contract.RequestPolicy   `json:"request"`
 	Address              string                   `json:"address"`
 	Transport            string                   `json:"transport"`
@@ -61,6 +63,9 @@ func Default() Config {

 // Validate checks configuration values before an application starts.
 func (c Config) Validate() error {
+	if err := c.CORS.Validate(); err != nil {
+		return AtField("cors", err)
+	}
 	if err := c.Lifecycle.Validate(); err != nil {
 		return AtField("lifecycle", err)
 	}
@@ -188,12 +193,14 @@ func WithTrustedProxies(proxies ...string) Option {
 // WithConfig applies a complete configuration loaded from a file or
 // environment. Later options can still override individual fields.
 func WithConfig(settings Config) Option {
+	settings.CORS = settings.CORS.Clone()
 	settings.Response = settings.Response.Clone()
 	settings.Errors = settings.Errors.Clone()
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 	settings.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	return func(cfg *Config) {
 		*cfg = settings
+		cfg.CORS = settings.CORS.Clone()
 		cfg.Response = settings.Response.Clone()
 		cfg.Errors = settings.Errors.Clone()
 		cfg.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
@@ -201,6 +208,12 @@ func WithConfig(settings Config) Option {
 	}
 }

+// WithCORS installs an app-local CORS policy, before routing and authentication.
+func WithCORS(settings cors.Config) Option {
+	settings = settings.Clone()
+	return func(cfg *Config) { cfg.CORS = settings.Clone() }
+}
+
 // WithResponse configures this application's default JSON envelope.
 func WithResponse(settings response.Config) Option {
 	settings = settings.Clone()
--- a/config/cors_test.go
+++ b/config/cors_test.go
@@ -0,0 +1,51 @@
+package config_test
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/config"
+)
+
+type corsProject struct {
+	Server config.Config `json:"server"`
+}
+
+func (c corsProject) Validate() error { return config.AtField("server", c.Server.Validate()) }
+
+func TestCORSConfiguration(t *testing.T) {
+	t.Setenv("WEB_ORIGIN", "https://web.example")
+	for ext, source := range map[string]string{
+		"yaml": "server:\n  cors:\n    enabled: true\n    allowedOrigins:\n      - '${WEB_ORIGIN}'\n    allowedMethods: [GET, POST]\n    allowedHeaders: [Authorization, Content-Type]\n    maxAge: 10m\n",
+		"json": `{"server":{"cors":{"enabled":true,"allowedOrigins":["${WEB_ORIGIN}"],"allowedMethods":["GET","POST"],"allowedHeaders":["Authorization","Content-Type"],"maxAge":"10m"}}}`,
+		"xml":  `<config><server><cors><enabled type="bool">true</enabled><allowedOrigins type="array"><item>${WEB_ORIGIN}</item></allowedOrigins><allowedMethods type="array"><item>GET</item><item>POST</item></allowedMethods><allowedHeaders type="array"><item>Authorization</item><item>Content-Type</item></allowedHeaders><maxAge>10m</maxAge></cors></server></config>`,
+	} {
+		t.Run(ext, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "config."+ext)
+			if err := os.WriteFile(path, []byte(source), 0600); err != nil {
+				t.Fatal(err)
+			}
+			cfg, err := config.LoadProject(path, corsProject{Server: config.Default()})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !cfg.Server.CORS.Enabled || cfg.Server.CORS.AllowedOrigins[0] != "https://web.example" || cfg.Server.CORS.MaxAge != 10*time.Minute {
+				t.Fatal(cfg.Server.CORS)
+			}
+		})
+	}
+	path := filepath.Join(t.TempDir(), "bad.yaml")
+	if err := os.WriteFile(path, []byte("server:\n  cors:\n    enabled: true\n    allowedOrigins:\n      - '${WEB_ORIGIN}'\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WEB_ORIGIN", "https://user:secret@web.example")
+	_, err := config.LoadProject(path, corsProject{Server: config.Default()})
+	var d *config.Error
+	if !errors.As(err, &d) || d.Field != "server.cors.allowedOrigins[0]" || d.Env != "WEB_ORIGIN" || d.Line != 5 || strings.Contains(err.Error(), "secret") {
+		t.Fatal(err)
+	}
+}
--- a/cors/README.md
+++ b/cors/README.md
@@ -0,0 +1,82 @@
+# 可选 CORS
+
+CORS 控制浏览器能否跨源读取 HTTP 响应。默认关闭；同源反向代理可以保持关闭。模块无 Gin 或具体业务依赖，标准库/native/HTTP2 与自定义 Runner 使用相同 App 接入策略。
+
+## 生成项目只改配置
+
+在既有 `etc/config.yaml` 的 `server` 中加入，无需修改 main、svc 或每条 `.api` 路由：
+
+```yaml
+server:
+  cors:
+    enabled: true
+    allowedOrigins:
+      - https://admin.example.com
+      - https://merchant.example.com
+    allowedMethods: [GET, HEAD, POST, PUT, PATCH, DELETE]
+    allowedHeaders: [Authorization, Content-Type]
+    exposedHeaders: [X-Request-ID, Content-Disposition]
+    allowCredentials: false
+    maxAge: 10m
+```
+
+文件也可显式引用环境变量：`allowedOrigins: ["${WEB_ORIGIN}"]`。一个数组元素代表一个来源，不把逗号分隔环境文本隐式拆成多个来源。JSON/YAML/XML 走同一加载和校验；非法配置定位 `server.cors.allowedOrigins[0]` 等字段、文件及可用环境名/行列，不回显值。
+
+```sh
+go run . -config etc/config.yaml -check-config
+go run ./examples/cors # 在框架源码根目录运行独立示例
+```
+
+## 手写项目与独立 HTTP 服务
+
+```go
+app := omni.New(omni.WithCORS(omni.CORSConfig{
+    Enabled: true,
+    AllowedOrigins: []string{"https://web.example.com"},
+    AllowedMethods: []string{"GET", "POST"},
+    AllowedHeaders: []string{"Authorization", "Content-Type"},
+}))
+```
+
+已有 net/http 服务也可单独使用，不需要创建 App：
+
+```go
+policy, err := cors.New(cors.Config{
+    Enabled: true,
+    AllowedOrigins: []string{"https://web.example.com"},
+})
+if err != nil { return err }
+handler := policy.Wrap(existingHandler)
+```
+
+Config/New/WithCORS 在初始化时校验并快照配置；同一 Policy 可并发复用。`Config.Validate()` 返回 error，直接向 `omni.New` 传非法选项沿用框架初始化 panic 约定；生成项目在创建 App 前已校验。
+
+## 配置规则
+
+| 字段 | 规则 |
+| --- | --- |
+| enabled | 默认 false；关闭时直接使用原 Handler，不添加头、不拦截 OPTIONS |
+| allowedOrigins | 启用时必填。完整 HTTP(S) origin（协议＋主机＋可选端口），无路径、尾斜杠、userinfo、查询或片段。配置中的协议/主机转小写、默认 80/443 端口省略；请求匹配浏览器序列化后的来源 |
+| allowedMethods | 空列表默认 GET、HEAD、POST；填写后使用指定集合。大写方法名，拒绝浏览器禁止的 CONNECT/TRACE/TRACK，不提供方法通配符 |
+| allowedHeaders | 空列表不批准额外预检请求头。Authorization、JSON Content-Type 等按需要列出；名称忽略大小写，不提供通配符 |
+| exposedHeaders | 默认空；额外允许前端 JS 读取的响应头，例如下载文件名用 Content-Disposition。浏览器本来就可读取的安全列表不需重复填写 |
+| allowCredentials | 默认 false；跨源 Cookie 等凭据模式需要显式 true 和具体来源。单纯手动设置 Authorization 头只需列入 allowedHeaders，不必因此开启 Cookie 凭据模式 |
+| maxAge | 浏览器缓存预检结果的时长，必须非负且为整秒；0 不发送该头。浏览器可按自身上限截短 |
+
+公开无凭据 API 可使用唯一来源 `"*"`；与 `allowCredentials: true` 或其他来源并存会报错。此版本只支持 HTTP(S) 来源，拒绝 `null`、子域通配符、正则、file:// 和不透明来源。国际化域名填写浏览器发送的 ASCII/Punycode 形式；IP 使用完整标准形式。不会为匹配来源查询 DNS。
+
+## 预检、错误响应与安全边界
+
+- CORS 位于路由/业务中间件外层。只有 OPTIONS 且同时带 Origin 和 Access-Control-Request-Method 才视为预检；普通 OPTIONS 继续执行项目逻辑。
+- 合法预检返回 **204 空响应**，不进入业务中间件、鉴权、Logic 或业务响应包装。拒绝预检返回 **403 空响应**，不暴露内部原因；两者是协议响应，不受业务“失败也返回 HTTP 200”的设置影响。
+- 预检验证全局来源、方法、请求头策略，不探测路由存在性；通过不代表实际接口一定存在。实际请求仍由路由处理，可返回 404/405。
+- 实际请求继续正常鉴权；来源/方法获准时，正常响应、401/403、404/405、框架恢复的 500 都带 CORS 头，响应体、状态和错误目录不变。协议解析、TLS、网络层过载等在进入 App 前发生的拒绝不由本模块改写。
+- 未获准或没有 Origin 的实际请求仍正常进入业务，只是不添加 CORS 许可头。CORS 不等于身份认证、服务端访问控制或 CSRF 防护；服务端回调仍需项目自己的验签/鉴权。
+- 始终追加并去重 `Vary: Origin`；预检再追加请求方法/请求头的 Vary，保留原有 Vary 与 `*`。不要在下游代码覆盖这些头。代理与应用选择一处负责 CORS，避免重复头或冲突策略。
+- 不包装 ResponseWriter、不读取/缓存 body、不克隆 Request。下载、上传、Flush、Hijack 和请求上下文保留；不增加响应体大小限制或改写统一返回格式。
+- 使用 App、Engine、NewServer 或 Run/ServeContext/RunWith 接入。Router() 暴露底层路由供高级注册，单独拿 Router().ServeHTTP 服务会绕过应用的外层策略。
+- App 内业务日志/指标不统计被提前结束的预检；如需记录全部流量，在 App 外层或代理配置访问日志。不要让全局登录校验挡在 CORS 预检之前。
+
+配置最多 1024 个来源、每个最多 4096 字节；方法/请求头/暴露头各最多 128 个且名称最多 256 字节；预检请求头列表最多 128 项、8192 字节。拒绝 CRLF、歧义的重复 Origin/请求方法及非法 token。WebSocket Origin 校验、Private Network Access 扩展和云桶 CORS 不包含在本模块中，按对应服务配置。
+
+规则依据：[Fetch CORS 协议](https://fetch.spec.whatwg.org/#http-cors-protocol)、[凭据规则](https://fetch.spec.whatwg.org/#cors-protocol-and-credentials)、[缓存规则](https://fetch.spec.whatwg.org/#cors-protocol-and-http-caches)。可运行示例：[examples/cors](../examples/cors/README.md)。
--- a/cors/config.go
+++ b/cors/config.go
@@ -0,0 +1,144 @@
+// Package cors implements optional, transport-independent browser CORS policy.
+// It does not authenticate requests or provide CSRF protection.
+package cors
+
+import (
+	"net"
+	"net/netip"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/internal/configdiag"
+)
+
+// Config is disabled by default. Origins are exact HTTP(S) origins, or a single
+// "*" for public responses without credentials. Patterns and "null" are rejected.
+// Empty methods default to GET, HEAD, POST; empty header lists grant no extra
+// permissions. MaxAge is a nonnegative whole number of seconds; zero omits it.
+type Config struct {
+	Enabled          bool          `json:"enabled"`
+	AllowedOrigins   []string      `json:"allowedOrigins"`
+	AllowedMethods   []string      `json:"allowedMethods"`
+	AllowedHeaders   []string      `json:"allowedHeaders"`
+	ExposedHeaders   []string      `json:"exposedHeaders"`
+	AllowCredentials bool          `json:"allowCredentials"`
+	MaxAge           time.Duration `json:"maxAge"`
+}
+
+func (c Config) Clone() Config {
+	c.AllowedOrigins = append([]string(nil), c.AllowedOrigins...)
+	c.AllowedMethods = append([]string(nil), c.AllowedMethods...)
+	c.AllowedHeaders = append([]string(nil), c.AllowedHeaders...)
+	c.ExposedHeaders = append([]string(nil), c.ExposedHeaders...)
+	return c
+}
+
+// Validate never echoes configured values in diagnostics. Invalid settings are
+// rejected even when disabled; an empty origin list is legal only when disabled.
+func (c Config) Validate() error {
+	if c.Enabled && len(c.AllowedOrigins) == 0 {
+		return configdiag.New("allowedOrigins", "is required when CORS is enabled")
+	}
+	if c.MaxAge < 0 || c.MaxAge%time.Second != 0 {
+		return configdiag.New("maxAge", "must be a nonnegative whole number of seconds")
+	}
+	if len(c.AllowedOrigins) > 1024 {
+		return configdiag.New("allowedOrigins", "must contain at most 1024 entries")
+	}
+	for i, origin := range c.AllowedOrigins {
+		field := "allowedOrigins[" + strconv.Itoa(i) + "]"
+		if origin == "*" {
+			if c.AllowCredentials || len(c.AllowedOrigins) != 1 {
+				return configdiag.New(field, "wildcard requires a single origin entry and allowCredentials=false")
+			}
+		} else if _, ok := normalizeOrigin(origin); !ok {
+			return configdiag.New(field, "must be an HTTP(S) origin without credentials, path, query, fragment or wildcard")
+		}
+	}
+	for _, list := range []struct {
+		name   string
+		values []string
+	}{{"allowedMethods", c.AllowedMethods}, {"allowedHeaders", c.AllowedHeaders}, {"exposedHeaders", c.ExposedHeaders}} {
+		if len(list.values) > 128 {
+			return configdiag.New(list.name, "must contain at most 128 entries")
+		}
+		for i, value := range list.values {
+			field := list.name + "[" + strconv.Itoa(i) + "]"
+			if !token(value) || value == "*" {
+				return configdiag.New(field, "must be an explicit HTTP token, not a wildcard")
+			}
+			if list.name == "allowedMethods" && (value != strings.ToUpper(value) || value == "CONNECT" || value == "TRACE" || value == "TRACK") {
+				return configdiag.New(field, "must be an uppercase browser-allowed HTTP method")
+			}
+		}
+	}
+	return nil
+}
+
+// Normalize configured scheme/host case and default ports once. Request values
+// match serialized browser origins; arbitrary URL prefixes/suffixes never match.
+func normalizeOrigin(origin string) (string, bool) {
+	if len(origin) == 0 || len(origin) > 4096 {
+		return "", false
+	}
+	for _, b := range []byte(origin) {
+		if b <= 32 || b >= 127 || strings.ContainsRune("\\%?#*", rune(b)) {
+			return "", false
+		}
+	}
+	u, err := url.Parse(origin)
+	if err != nil || u.User != nil || u.Opaque != "" || u.Path != "" || u.RawQuery != "" || u.Fragment != "" || u.Host == "" {
+		return "", false
+	}
+	scheme, host := strings.ToLower(u.Scheme), strings.ToLower(u.Hostname())
+	if (scheme != "http" && scheme != "https") || host == "" || strings.HasSuffix(u.Host, ":") {
+		return "", false
+	}
+	if strings.Contains(host, ":") {
+		ip, err := netip.ParseAddr(host)
+		if err != nil || !ip.Is6() || ip.Zone() != "" {
+			return "", false
+		}
+		host = "[" + ip.String() + "]"
+		if ip.Is4In6() {
+			// Browsers serialize mapped IPv4 as hex IPv6 pieces; netip.String
+			// uses a dotted-decimal tail instead.
+			b := ip.As16()
+			host = "[::ffff:" + strconv.FormatUint(uint64(b[12])<<8|uint64(b[13]), 16) + ":" + strconv.FormatUint(uint64(b[14])<<8|uint64(b[15]), 16) + "]"
+		}
+	} else {
+		if strings.ContainsAny(u.Host, "[]") {
+			return "", false
+		}
+		for _, b := range []byte(host) {
+			if !(b >= 'a' && b <= 'z' || b >= '0' && b <= '9' || b == '.' || b == '-') {
+				return "", false
+			}
+		}
+	}
+	port := u.Port()
+	if port != "" {
+		n, err := strconv.Atoi(port)
+		if err != nil || n < 1 || n > 65535 {
+			return "", false
+		}
+		if !(scheme == "https" && n == 443 || scheme == "http" && n == 80) {
+			host = net.JoinHostPort(strings.Trim(host, "[]"), strconv.Itoa(n))
+		}
+	}
+	return scheme + "://" + host, true
+}
+
+func token(s string) bool {
+	if s == "" || len(s) > 256 {
+		return false
+	}
+	for _, b := range []byte(s) {
+		if !(b >= 'a' && b <= 'z' || b >= 'A' && b <= 'Z' || b >= '0' && b <= '9' || strings.ContainsRune("!#$%&'*+-.^_`|~", rune(b))) {
+			return false
+		}
+	}
+	return true
+}
--- a/cors/cors.go
+++ b/cors/cors.go
@@ -0,0 +1,187 @@
+package cors
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Policy is immutable after New and safe to share between concurrent requests.
+type Policy struct {
+	enabled, wildcard, credentials                    bool
+	origins, methods, headers                         map[string]struct{}
+	allowMethods, allowHeaders, exposeHeaders, maxAge string
+}
+
+// New validates and snapshots policy. It performs no network or DNS operations.
+func New(c Config) (*Policy, error) {
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	p := &Policy{enabled: c.Enabled, credentials: c.AllowCredentials}
+	if !c.Enabled {
+		return p, nil
+	}
+	p.origins = make(map[string]struct{}, len(c.AllowedOrigins))
+	for _, origin := range c.AllowedOrigins {
+		if origin == "*" {
+			p.wildcard = true
+			continue
+		}
+		normalized, _ := normalizeOrigin(origin)
+		p.origins[normalized] = struct{}{}
+	}
+	methods := c.AllowedMethods
+	if len(methods) == 0 {
+		methods = []string{http.MethodGet, http.MethodHead, http.MethodPost}
+	}
+	p.methods, p.allowMethods = compileList(methods, false)
+	p.headers, p.allowHeaders = compileList(c.AllowedHeaders, true)
+	_, p.exposeHeaders = compileList(c.ExposedHeaders, true)
+	if c.MaxAge > 0 {
+		p.maxAge = strconv.FormatInt(int64(c.MaxAge/time.Second), 10)
+	}
+	return p, nil
+}
+
+func compileList(values []string, header bool) (map[string]struct{}, string) {
+	set := make(map[string]struct{}, len(values))
+	list := make([]string, 0, len(values))
+	for _, value := range values {
+		key := value
+		if header {
+			key = strings.ToLower(value)
+			value = http.CanonicalHeaderKey(value)
+		}
+		if _, exists := set[key]; exists {
+			continue
+		}
+		set[key] = struct{}{}
+		list = append(list, value)
+	}
+	return set, strings.Join(list, ", ")
+}
+
+// Wrap installs CORS outside routing/authentication. Only actual CORS preflights
+// are short-circuited. Actual requests always continue through normal handlers;
+// an unlisted Origin receives no permission to read the response in a browser.
+// The original ResponseWriter, Request and body pass through without buffering.
+func (p *Policy) Wrap(next http.Handler) http.Handler {
+	if next == nil {
+		panic("cors: nil handler")
+	}
+	if p == nil {
+		panic("cors: nil policy")
+	}
+	if !p.enabled {
+		return next
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h := w.Header()
+		vary(h, "Origin")
+		origins := r.Header.Values("Origin")
+		// An OPTIONS request without Origin or Access-Control-Request-Method is
+		// ordinary application traffic, including user-defined OPTIONS handlers.
+		requestedMethods := r.Header.Values("Access-Control-Request-Method")
+		preflight := r.Method == http.MethodOptions && len(origins) > 0 && len(requestedMethods) > 0
+		if preflight {
+			vary(h, "Access-Control-Request-Method")
+			vary(h, "Access-Control-Request-Headers")
+		}
+		if len(origins) != 1 || !p.allowsOrigin(origins[0]) {
+			if preflight {
+				w.WriteHeader(http.StatusForbidden)
+				return
+			}
+			next.ServeHTTP(w, r)
+			return
+		}
+		if preflight {
+			if len(requestedMethods) != 1 || !p.allowsMethod(requestedMethods[0]) || !p.allowsHeaders(r.Header.Values("Access-Control-Request-Headers")) {
+				w.WriteHeader(http.StatusForbidden)
+				return
+			}
+			p.allowOrigin(h, origins[0])
+			h.Set("Access-Control-Allow-Methods", p.allowMethods)
+			if p.allowHeaders != "" {
+				h.Set("Access-Control-Allow-Headers", p.allowHeaders)
+			}
+			if p.maxAge != "" {
+				h.Set("Access-Control-Max-Age", p.maxAge)
+			}
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		// Match the actual method too: this grants response access, not permission
+		// to execute a side effect. Authentication/CSRF checks remain in the app.
+		if p.allowsMethod(r.Method) {
+			p.allowOrigin(h, origins[0])
+			if p.exposeHeaders != "" {
+				h.Set("Access-Control-Expose-Headers", p.exposeHeaders)
+			}
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (p *Policy) allowsOrigin(origin string) bool {
+	if !p.wildcard {
+		_, ok := p.origins[origin]
+		return ok
+	}
+	normalized, ok := normalizeOrigin(origin)
+	return ok && normalized == origin
+}
+func (p *Policy) allowsMethod(method string) bool { _, ok := p.methods[method]; return ok }
+func (p *Policy) allowOrigin(h http.Header, origin string) {
+	if p.wildcard {
+		origin = "*"
+	}
+	h.Set("Access-Control-Allow-Origin", origin)
+	if p.credentials {
+		h.Set("Access-Control-Allow-Credentials", "true")
+	}
+}
+func (p *Policy) allowsHeaders(lines []string) bool {
+	count, size := 0, 0
+	for _, line := range lines {
+		size += len(line)
+		if size > 8192 {
+			return false
+		}
+		// Parse a header list without allocating an attacker-sized split slice.
+		for {
+			name, rest, more := strings.Cut(line, ",")
+			name = strings.Trim(name, " \t")
+			count++
+			if count > 128 || !token(name) {
+				return false
+			}
+			if _, ok := p.headers[strings.ToLower(name)]; !ok {
+				return false
+			}
+			if !more {
+				break
+			}
+			line = rest
+		}
+	}
+	return true
+}
+func vary(h http.Header, name string) {
+	for _, line := range h.Values("Vary") {
+		for {
+			v, rest, more := strings.Cut(line, ",")
+			v = strings.TrimSpace(v)
+			if v == "*" || strings.EqualFold(v, name) {
+				return
+			}
+			if !more {
+				break
+			}
+			line = rest
+		}
+	}
+	h.Add("Vary", name)
+}
--- a/cors/cors_test.go
+++ b/cors/cors_test.go
@@ -0,0 +1,303 @@
+package cors
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func exampleConfig() Config {
+	return Config{Enabled: true, AllowedOrigins: []string{"https://admin.example", "https://merchant.example"}, AllowedMethods: []string{"GET", "POST", "DELETE"}, AllowedHeaders: []string{"Authorization", "Content-Type"}, ExposedHeaders: []string{"X-Request-ID", "Content-Disposition"}, MaxAge: 10 * time.Minute}
+}
+
+func TestPolicyPreflightAndActual(t *testing.T) {
+	for _, tc := range []struct {
+		name, method, origin, requestedMethod, requestedHeaders string
+		status                                                  int
+		called, allowed                                         bool
+	}{
+		{"preflight", "OPTIONS", "https://admin.example", "POST", "authorization, CONTENT-TYPE", 204, false, true},
+		{"no request headers", "OPTIONS", "https://admin.example", "DELETE", "", 204, false, true},
+		{"unknown origin", "OPTIONS", "https://other.example", "POST", "authorization", 403, false, false},
+		{"suffix attack", "OPTIONS", "https://admin.example.evil", "POST", "", 403, false, false},
+		{"scheme mismatch", "OPTIONS", "http://admin.example", "POST", "", 403, false, false},
+		{"port mismatch", "OPTIONS", "https://admin.example:444", "POST", "", 403, false, false},
+		{"opaque origin", "OPTIONS", "null", "POST", "", 403, false, false},
+		{"unknown method", "OPTIONS", "https://admin.example", "PATCH", "", 403, false, false},
+		{"case sensitive method", "OPTIONS", "https://admin.example", "post", "", 403, false, false},
+		{"unknown header", "OPTIONS", "https://admin.example", "POST", "X-Internal", 403, false, false},
+		{"trailing empty header", "OPTIONS", "https://admin.example", "POST", "Authorization,", 403, false, false},
+		{"control header", "OPTIONS", "https://admin.example", "POST", "Authorization\r\nX-Evil", 403, false, false},
+		{"duplicate allowed header", "OPTIONS", "https://admin.example", "POST", "Authorization, authorization", 204, false, true},
+		{"oversized list", "OPTIONS", "https://admin.example", "POST", strings.Repeat("Authorization,", 129) + "Authorization", 403, false, false},
+		{"actual error response", "GET", "https://merchant.example", "", "", 401, true, true},
+		{"actual denied origin still authenticates", "POST", "https://other.example", "", "", 401, true, false},
+		{"actual denied method still authenticates", "PUT", "https://admin.example", "", "", 401, true, false},
+		{"server callback", "POST", "", "", "", 401, true, false},
+		{"ordinary OPTIONS", "OPTIONS", "https://admin.example", "", "", 401, true, false},
+		{"OPTIONS without Origin", "OPTIONS", "", "POST", "", 401, true, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			policy, err := New(exampleConfig())
+			if err != nil {
+				t.Fatal(err)
+			}
+			called := false
+			h := policy.Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				called = true
+				w.WriteHeader(401)
+				io.WriteString(w, "authentication required")
+			}))
+			r := httptest.NewRequest(tc.method, "http://api.example/resource", nil)
+			if tc.origin != "" {
+				r.Header.Set("Origin", tc.origin)
+			}
+			if tc.requestedMethod != "" {
+				r.Header.Set("Access-Control-Request-Method", tc.requestedMethod)
+			}
+			if tc.requestedHeaders != "" {
+				r.Header.Set("Access-Control-Request-Headers", tc.requestedHeaders)
+			}
+			w := httptest.NewRecorder()
+			w.Header().Add("Vary", "Accept-Encoding")
+			h.ServeHTTP(w, r)
+			if w.Code != tc.status || called != tc.called {
+				t.Fatalf("status=%d called=%v", w.Code, called)
+			}
+			if got := w.Header().Get("Access-Control-Allow-Origin"); (got != "") != tc.allowed || tc.allowed && got != tc.origin {
+				t.Fatal(w.Header())
+			}
+			if !strings.Contains(strings.Join(w.Header().Values("Vary"), ","), "Origin") || !strings.Contains(strings.Join(w.Header().Values("Vary"), ","), "Accept-Encoding") {
+				t.Fatal(w.Header())
+			}
+			if !tc.called {
+				if w.Body.Len() != 0 {
+					t.Fatal("preflight wrapped in business response")
+				}
+				if !strings.Contains(strings.Join(w.Header().Values("Vary"), ","), "Access-Control-Request-Headers") {
+					t.Fatal(w.Header())
+				}
+				if tc.allowed && (w.Header().Get("Access-Control-Max-Age") != "600" || !strings.Contains(w.Header().Get("Access-Control-Allow-Headers"), "Authorization")) {
+					t.Fatal(w.Header())
+				}
+			} else if w.Body.String() != "authentication required" {
+				t.Fatal(w.Body.String())
+			}
+			if tc.called && tc.allowed && w.Header().Get("Access-Control-Expose-Headers") != "X-Request-Id, Content-Disposition" {
+				t.Fatal(w.Header())
+			}
+		})
+	}
+}
+
+func TestPolicyValidation(t *testing.T) {
+	for _, origin := range []string{"https://admin.example/", "https://user:password@admin.example", "null", "https://*.example", "https://admin.example?secret", "https://admin.example#secret", "file://host", "https://host:", "https://host:0", "https://host:65536", "https://host%2eevil", "https://host\r\nX: value", "https://例子.example", "https://[localhost]", "https://[::1%25zone]"} {
+		c := exampleConfig()
+		c.AllowedOrigins = []string{origin}
+		err := c.Validate()
+		if err == nil || strings.Contains(err.Error(), origin) {
+			t.Fatalf("invalid origin accepted or exposed: %q %v", origin, err)
+		}
+	}
+	for _, change := range []func(*Config){
+		func(c *Config) { c.AllowedOrigins = nil },
+		func(c *Config) { c.AllowedOrigins = []string{"*"}; c.AllowCredentials = true },
+		func(c *Config) { c.AllowedOrigins = []string{"*", "https://admin.example"} },
+		func(c *Config) { c.AllowedHeaders = []string{"*"} },
+		func(c *Config) { c.ExposedHeaders = []string{"header\r\n"} },
+		func(c *Config) { c.AllowedMethods = []string{"get"} },
+		func(c *Config) { c.AllowedMethods = []string{"TRACE"} },
+		func(c *Config) { c.MaxAge = -time.Second },
+		func(c *Config) { c.MaxAge = time.Millisecond },
+	} {
+		c := exampleConfig()
+		change(&c)
+		if _, err := New(c); err == nil {
+			t.Fatal(c)
+		}
+	}
+	if err := (Config{}).Validate(); err != nil {
+		t.Fatal(err)
+	}
+	for input, want := range map[string]string{"https://[::ffff:192.0.2.1]": "https://[::ffff:c000:201]", "https://[::ffff:c000:201]": "https://[::ffff:c000:201]", "https://ADMIN.EXAMPLE:443": "https://admin.example", "http://localhost:80": "http://localhost", "http://localhost:8080": "http://localhost:8080", "https://[::1]:443": "https://[::1]", "http://[::1]:8080": "http://[::1]:8080"} {
+		got, ok := normalizeOrigin(input)
+		if !ok || got != want {
+			t.Fatalf("%q => %q %v", input, got, ok)
+		}
+	}
+}
+
+func TestPolicyCredentialsWildcardAndDuplicates(t *testing.T) {
+	for _, credentials := range []bool{false, true} {
+		c := exampleConfig()
+		c.AllowCredentials = credentials
+		if !credentials {
+			c.AllowedOrigins = []string{"*"}
+		}
+		p, _ := New(c)
+		for _, origin := range []string{"https://admin.example", "null", "https://admin.example/path", "https://bad\r\n"} {
+			r := httptest.NewRequest("GET", "/", nil)
+			r.Header.Set("Origin", origin)
+			w := httptest.NewRecorder()
+			p.Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) })).ServeHTTP(w, r)
+			if origin != "https://admin.example" {
+				if w.Header().Get("Access-Control-Allow-Origin") != "" {
+					t.Fatal(w.Header())
+				}
+				continue
+			}
+			want := "*"
+			if credentials {
+				want = origin
+			}
+			if w.Header().Get("Access-Control-Allow-Origin") != want || (w.Header().Get("Access-Control-Allow-Credentials") == "true") != credentials {
+				t.Fatal(w.Header())
+			}
+		}
+	}
+	p, _ := New(exampleConfig())
+	for _, header := range []string{"Origin", "Access-Control-Request-Method"} {
+		r := httptest.NewRequest("OPTIONS", "/", nil)
+		r.Header.Set("Origin", "https://admin.example")
+		r.Header.Set("Access-Control-Request-Method", "POST")
+		r.Header.Add(header, r.Header.Get(header))
+		w := httptest.NewRecorder()
+		p.Wrap(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("ambiguous preflight reached handler") })).ServeHTTP(w, r)
+		if w.Code != 403 || w.Header().Get("Access-Control-Allow-Origin") != "" {
+			t.Fatal(w.Code, w.Header())
+		}
+	}
+}
+
+func TestPolicyPreservesHTTPAndSnapshot(t *testing.T) {
+	c := exampleConfig()
+	p, _ := New(c)
+	c.AllowedOrigins[0] = "https://evil.example"
+	c.AllowedHeaders[0] = "X-Evil"
+	r := httptest.NewRequest("GET", "/", strings.NewReader("request"))
+	r.Header.Set("Origin", "https://admin.example")
+	type key struct{}
+	r = r.WithContext(context.WithValue(r.Context(), key{}, "kept"))
+	w := httptest.NewRecorder()
+	w.Header().Set("Vary", "Accept-Encoding, origin")
+	next := http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if writer != w || request != r || request.Context().Value(key{}) != "kept" {
+			t.Fatal("HTTP capabilities replaced")
+		}
+		io.WriteString(writer, "chunk")
+		writer.(http.Flusher).Flush()
+	})
+	p.Wrap(next).ServeHTTP(w, r)
+	if !w.Flushed || w.Body.String() != "chunk" || w.Header().Get("Access-Control-Allow-Origin") != "https://admin.example" || len(w.Header().Values("Vary")) != 1 {
+		t.Fatal(w)
+	}
+	for _, prior := range []string{"*", "Accept-Encoding, Origin"} {
+		h := http.Header{"Vary": {prior}}
+		vary(h, "Origin")
+		if !reflect.DeepEqual(h.Values("Vary"), []string{prior}) {
+			t.Fatal(h)
+		}
+	}
+	disabled, _ := New(Config{})
+	if reflect.ValueOf(disabled.Wrap(next)).Pointer() != reflect.ValueOf(next).Pointer() {
+		t.Fatal("disabled policy not passthrough")
+	}
+	var wg sync.WaitGroup
+	h := p.Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) }))
+	for i := 0; i < 32; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			for j := 0; j < 100; j++ {
+				r := httptest.NewRequest("GET", "/", nil)
+				origin := "https://admin.example"
+				if i%2 == 1 {
+					origin = "https://merchant.example"
+				}
+				r.Header.Set("Origin", origin)
+				w := httptest.NewRecorder()
+				h.ServeHTTP(w, r)
+				if w.Header().Get("Access-Control-Allow-Origin") != origin {
+					t.Error("cross-request origin leak")
+				}
+			}
+		}(i)
+	}
+	wg.Wait()
+}
+
+func FuzzCORSHeaders(f *testing.F) {
+	f.Add("https://admin.example", "POST", "authorization, content-type")
+	f.Add("https://admin.example.evil", "POST", "")
+	f.Add("null", "GET", "\r\n")
+	p, _ := New(exampleConfig())
+	h := p.Wrap(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { panic("preflight reached business") }))
+	f.Fuzz(func(t *testing.T, origin, method, headers string) {
+		r := httptest.NewRequest("OPTIONS", "/", nil)
+		r.Header.Set("Origin", origin)
+		r.Header.Set("Access-Control-Request-Method", method)
+		if headers != "" {
+			r.Header.Set("Access-Control-Request-Headers", headers)
+		}
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, r)
+		if w.Code != 204 && w.Code != 403 {
+			t.Fatal(w.Code)
+		}
+		if w.Body.Len() != 0 {
+			t.Fatal("unexpected body")
+		}
+		if value := w.Header().Get("Access-Control-Allow-Origin"); value != "" {
+			if value != "https://admin.example" && value != "https://merchant.example" {
+				t.Fatal("untrusted reflection")
+			}
+		}
+	})
+}
+
+type benchmarkWriter struct{ header http.Header }
+
+func (w benchmarkWriter) Header() http.Header         { return w.header }
+func (w benchmarkWriter) Write(p []byte) (int, error) { return len(p), nil }
+func (w benchmarkWriter) WriteHeader(int)             {}
+func BenchmarkCORS(b *testing.B) {
+	for _, mode := range []string{"disabled", "noOrigin", "allowed", "denied", "preflight", "wildcard"} {
+		b.Run(mode, func(b *testing.B) {
+			c := exampleConfig()
+			if mode == "disabled" {
+				c.Enabled = false
+			}
+			if mode == "wildcard" {
+				c.AllowedOrigins = []string{"*"}
+			}
+			p, _ := New(c)
+			h := p.Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) }))
+			r := httptest.NewRequest("GET", "/", nil)
+			r.Header.Set("Origin", "https://admin.example")
+			if mode == "noOrigin" {
+				r.Header.Del("Origin")
+			}
+			if mode == "denied" {
+				r.Header.Set("Origin", "https://other.example")
+			}
+			if mode == "preflight" {
+				r.Method = "OPTIONS"
+				r.Header.Set("Access-Control-Request-Method", "POST")
+				r.Header.Set("Access-Control-Request-Headers", "authorization, content-type")
+			}
+			w := benchmarkWriter{make(http.Header)}
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				clear(w.header)
+				h.ServeHTTP(w, r)
+			}
+		})
+	}
+}
--- a/examples/cors/README.md
+++ b/examples/cors/README.md
@@ -0,0 +1,17 @@
+# CORS 与正常鉴权
+
+在框架根目录运行：
+
+```sh
+go run ./examples/cors
+WEB_ORIGIN=https://admin.example go run ./examples/cors
+```
+
+仅监听临时 localhost 端口，不依赖数据库或外部服务。配置由统一 LoadProject 加载，示例模拟浏览器 Origin/预检请求头，依次检查：
+
+- OPTIONS 预检返回 204，无需登录。
+- 实际 GET 未登录仍返回 401，前端可读取这条错误响应。
+- 示例凭据通过后返回 200。
+- 404 也保留允许来源的 CORS 响应头。
+
+示例 Token 仅用于展示，项目使用自身鉴权实现。CORS 不验证 Token，也不保证其他客户端不能调用 API。完整规则与配置见 [cors](../../cors/README.md)。
--- a/examples/cors/config.yaml
+++ b/examples/cors/config.yaml
@@ -0,0 +1,10 @@
+server:
+  cors:
+    enabled: true
+    allowedOrigins:
+      - "${WEB_ORIGIN:-https://web.example}"
+    allowedMethods: [GET, POST]
+    allowedHeaders: [Authorization, Content-Type]
+    exposedHeaders: [X-Request-ID]
+    allowCredentials: false
+    maxAge: 10m
--- a/examples/cors/main.go
+++ b/examples/cors/main.go
@@ -0,0 +1,76 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/config"
+)
+
+type Config struct {
+	Server config.Config `json:"server"`
+}
+
+func (c Config) Validate() error { return config.AtField("server", c.Server.Validate()) }
+
+func run(path string) error {
+	cfg, err := config.LoadProject(path, Config{Server: config.Default()})
+	if err != nil {
+		return err
+	}
+	a := omni.New(omni.WithConfig(cfg.Server))
+	defer a.Close()
+	a.GET("/private", func(c *omni.Context) error {
+		if c.Header("Authorization") != "Bearer example-only" {
+			return omni.Unauthorized("LOGIN_REQUIRED", "login required")
+		}
+		return c.OK("authenticated")
+	})
+	server := httptest.NewServer(a)
+	defer server.Close()
+	client := &http.Client{Timeout: 3 * time.Second}
+	defer client.CloseIdleConnections()
+	for _, tc := range []struct {
+		method, path, auth string
+		status             int
+	}{{"OPTIONS", "/private", "", 204}, {"GET", "/private", "", 401}, {"GET", "/private", "Bearer example-only", 200}, {"GET", "/missing", "", 404}} {
+		r, _ := http.NewRequest(tc.method, server.URL+tc.path, nil)
+		r.Header.Set("Origin", cfg.Server.CORS.AllowedOrigins[0])
+		if tc.method == "OPTIONS" {
+			r.Header.Set("Access-Control-Request-Method", "GET")
+			r.Header.Set("Access-Control-Request-Headers", "authorization")
+		}
+		if tc.auth != "" {
+			r.Header.Set("Authorization", tc.auth)
+		}
+		res, err := client.Do(r)
+		if err != nil {
+			return err
+		}
+		_, readErr := io.Copy(io.Discard, res.Body)
+		closeErr := res.Body.Close()
+		if err := errors.Join(readErr, closeErr); err != nil {
+			return err
+		}
+		if res.StatusCode != tc.status || res.Header.Get("Access-Control-Allow-Origin") == "" {
+			return fmt.Errorf("unexpected CORS response: %d", res.StatusCode)
+		}
+		fmt.Printf("%s %s -> %d, CORS allowed\n", tc.method, tc.path, res.StatusCode)
+	}
+	return nil
+}
+func main() {
+	path := flag.String("config", "examples/cors/config.yaml", "selected configuration file")
+	flag.Parse()
+	if err := run(*path); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
--- a/examples/managedService/go.mod
+++ b/examples/managedService/go.mod
@@ -2,7 +2,7 @@ module example.com/managed

 go 1.22.0

-require git.yuntuo.hk/k2safe/go-omni v0.23.0-preview
+require git.yuntuo.hk/k2safe/go-omni v0.24.0-preview

 require (
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
--- a/examples/userService/go.mod
+++ b/examples/userService/go.mod
@@ -3,7 +3,7 @@ module example.com/userService
 go 1.22.0

 require (
-	git.yuntuo.hk/k2safe/go-omni v0.23.0-preview
+	git.yuntuo.hk/k2safe/go-omni v0.24.0-preview
 	github.com/go-sql-driver/mysql v1.9.3
 )

--- a/omni.go
+++ b/omni.go
@@ -6,6 +6,7 @@ import (
 	"git.yuntuo.hk/k2safe/go-omni/app"
 	"git.yuntuo.hk/k2safe/go-omni/auth"
 	"git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/cors"
 	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
@@ -27,6 +28,7 @@ type APIError = apierrors.APIError
 type Config = config.Config
 type TLSConfig = config.TLSConfig
 type HTTPConfig = config.HTTPConfig
+type CORSConfig = cors.Config
 type EndpointsConfig = config.EndpointsConfig
 type EndpointConfig = config.EndpointConfig
 type HealthEndpointConfig = config.HealthEndpointConfig
@@ -70,6 +72,8 @@ func WithTransport(name string) Option { return config.WithTransport(name) }

 func WithHTTPConfig(settings HTTPConfig) Option { return config.WithHTTPConfig(settings) }

+func WithCORS(settings CORSConfig) Option { return config.WithCORS(settings) }
+
 func WithTLS(certFile, keyFile string) Option { return config.WithTLS(certFile, keyFile) }

 func WithLogConfig(settings LogConfig) Option { return config.WithLogConfig(settings) }
--- a/reports/corsAcceptance.md
+++ b/reports/corsAcceptance.md
@@ -0,0 +1,61 @@
+# v0.24 CORS 验收（2026-09-26）
+
+新增通用、可选的跨域策略。没有修改接入项目，没有连接业务数据库或对线上服务器进行压测。
+
+## 回归
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：49 个有测试的包通过，包含实际生成消费者和既有生命周期、错误目录、配置、上传下载等回归。
+- 最后补充 IPv4-mapped IPv6 来源序列化后，cors/config/app 的 race 复测通过。
+- Go 1.22.12 的 cors/config/app 测试通过；`go vet ./...`、`go build ./...` 通过。
+- managedService 重生成检查、race、根目录 build 通过；userService race 通过。没有提供外部数据库配置的测试按原规则跳过。
+- 实际生成的 CORS 消费者只修改配置，不修改 main、svc、handler；构建/race、重复生成、dry-run、check、业务文件字节保留通过。
+- `FuzzCORSHeaders` 运行 30 秒、4 worker，执行 2,877,406 次，通过。输入覆盖来源、方法和预检请求头，不等于穷尽所有协议组合。
+- `examples/cors` 使用本地临时监听端口验证 204、401、200、404，通过。
+
+| 范围 | 已验证场景 |
+| --- | --- |
+| 默认与配置 | 默认关闭保持原 Handler；JSON/YAML/XML 一致；显式环境引用；配置错误定位 server.cors 具体字段及文件/环境名/可用位置，不输出值 |
+| 来源 | 精确协议/域名/端口、默认端口规范化、IPv6、恶意后缀、null/路径/CRLF 拒绝；通配来源禁止凭据；重复 Origin 拒绝 |
+| 预检 | 204 空响应，拒绝为 403；不进入业务鉴权；方法/头校验、大小与数量限制；普通 OPTIONS 仍进入项目 Handler |
+| 实际响应 | 业务鉴权保留；自定义数字响应、401/500/panic、404/405 保留跨域头和原响应；不允许来源仅不授予浏览器读取权限 |
+| 标准能力 | 原 Request/Context/Body/ResponseWriter 不替换，Flush 等能力保留；Vary 追加/去重，已有值和通配 Vary 保留 |
+| transport | nethttp/native/HTTP2 使用真实本地 TLS；预检、原始上传、流式下载、暴露文件名、404 与关闭；HTTP2 确认协议协商 |
+| 隔离 | 输入配置、Option、Config() 返回值的切片变更不改变已构建策略；32 个并发调用者各执行 100 次检查，race 通过 |
+| 生成项目 | 未实现 Logic 的 501、404/405、健康检查、OpenAPI 和预检采用同一配置；非法凭据/通配组合在启动前报错 |
+
+## 浏览器
+
+通过 Codex In-app Browser，在两个不同的临时 localhost 页面分别执行 10 项真实 fetch 检查，共 20 项通过。记录见 [corsBrowser.json](corsBrowser.json)。
+
+允许来源能读取正常响应、401、404、下载文件名，Authorization 触发的预检通过；不允许的请求头/方法被浏览器拦截。未列入白名单的页面无法读取私有 API；无凭据通配 API 可读取，带 `credentials: include` 的通配请求被拦截。凭据模式测试使用临时演示请求，未设置或使用真实登录 Cookie。
+
+复现：在框架根目录 `go run ./scripts/corsBrowser`，打开终端输出的两个页面地址并点击 Run checks。脚本只监听 127.0.0.1，接收退出信号或五分钟后关闭。它用于浏览器协议验证，不是部署服务。本次临时监听已停止。
+
+## 性能
+
+Go 1.27.1、darwin/arm64、Apple M2 Max，无 race；每场景三轮、benchtime=300ms，表中取中位数。[原始结果](corsBenchmark.txt)。
+
+| 场景 | 时间/次 | 分配/次 |
+| --- | ---: | ---: |
+| 关闭 CORS | 3.357 ns | 0 B / 0 allocs |
+| 开启，无 Origin | 108.2 ns | 16 B / 1 alloc |
+| 精确来源允许，含两个暴露头 | 231.5 ns | 48 B / 3 allocs |
+| 来源不允许 | 130.4 ns | 16 B / 1 alloc |
+| 允许预检 | 589.7 ns | 176 B / 7 allocs |
+| 通配来源，无凭据 | 510.3 ns | 216 B / 5 allocs |
+
+关闭时直接返回原 Handler，表中是基准循环与下游空 Handler 的耗时，不能理解为新增延迟。开启时使用预建请求、复用 Header map 的测试 Writer；不包含网络、TLS 或业务处理，不能换算成实际服务 QPS。精确白名单只查初始化时建立的表；通配模式还会验证传入来源是否合法，因此更慢。请求和响应体不进入本模块内存缓冲。
+
+```sh
+go test ./cors -run '^$' -bench BenchmarkCORS -benchmem -benchtime=300ms -count=3
+go test ./cors -run '^$' -fuzz '^FuzzCORSHeaders$' -fuzztime=30s -parallel=4
+GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./cmd/go-omni/apigen -run '^TestGeneratedCORSConsumer$'
+```
+
+## 边界
+
+预检按应用策略判断，不探测每条路由。业务访问日志和指标不统计被 CORS 提前结束的预检，可在代理或 App 外层记录。网络解析/TLS/网络过载等进入 App 前的拒绝不由 CORS 改写。
+
+默认关闭，同源反向代理可继续使用原部署方式。只支持 HTTP(S) 精确来源或单一无凭据通配来源，不提供子域通配/正则/null 来源。WebSocket Origin、Private Network Access 和对象存储自身的 CORS 属于其他接口，本轮不包含。
+
+不批准来源不等于阻止服务端执行实际请求，项目的身份认证、权限和 CSRF 策略仍然必要。代理和应用只选择一处负责 CORS，下游不能覆盖许可头或 Vary。详细用法见 [cors 指南](../cors/README.md)。
--- a/reports/corsBenchmark.txt
+++ b/reports/corsBenchmark.txt
@@ -0,0 +1,24 @@
+goos: darwin
+goarch: arm64
+pkg: git.yuntuo.hk/k2safe/go-omni/cors
+cpu: Apple M2 Max
+BenchmarkCORS/disabled-12         	98300086	         3.347 ns/op	       0 B/op	       0 allocs/op
+BenchmarkCORS/disabled-12         	100000000	         3.650 ns/op	       0 B/op	       0 allocs/op
+BenchmarkCORS/disabled-12         	105484652	         3.357 ns/op	       0 B/op	       0 allocs/op
+BenchmarkCORS/noOrigin-12         	 3340696	       111.6 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/noOrigin-12         	 3420523	       108.2 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/noOrigin-12         	 3297222	       108.2 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/allowed-12          	 1557544	       232.6 ns/op	      48 B/op	       3 allocs/op
+BenchmarkCORS/allowed-12          	 1552413	       230.4 ns/op	      48 B/op	       3 allocs/op
+BenchmarkCORS/allowed-12          	 1561892	       231.5 ns/op	      48 B/op	       3 allocs/op
+BenchmarkCORS/denied-12           	 2723037	       130.5 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/denied-12           	 2756702	       129.4 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/denied-12           	 2777206	       130.4 ns/op	      16 B/op	       1 allocs/op
+BenchmarkCORS/preflight-12        	  638340	       588.4 ns/op	     176 B/op	       7 allocs/op
+BenchmarkCORS/preflight-12        	  623992	       591.8 ns/op	     176 B/op	       7 allocs/op
+BenchmarkCORS/preflight-12        	  592320	       589.7 ns/op	     176 B/op	       7 allocs/op
+BenchmarkCORS/wildcard-12         	  708910	       510.3 ns/op	     216 B/op	       5 allocs/op
+BenchmarkCORS/wildcard-12         	  739617	       506.8 ns/op	     216 B/op	       5 allocs/op
+BenchmarkCORS/wildcard-12         	  707361	       510.6 ns/op	     216 B/op	       5 allocs/op
+PASS
+ok  	git.yuntuo.hk/k2safe/go-omni/cors	8.971s
--- a/reports/corsBrowser.json
+++ b/reports/corsBrowser.json
@@ -0,0 +1,137 @@
+{
+  "browser": "Codex In-app Browser",
+  "passed": true,
+  "allowed": {
+    "allowedPage": true,
+    "passed": true,
+    "checks": [
+      {
+        "name": "simple GET",
+        "pass": true,
+        "status": 200,
+        "body": "hello"
+      },
+      {
+        "name": "401 readable",
+        "pass": true,
+        "status": 401,
+        "body": "{\"code\":\"LOGIN_REQUIRED\",\"message\":\"login required\",\"requestId\":\"8e1c6e6f5b5188f2409cc4ea8ef00b31\"}\n"
+      },
+      {
+        "name": "authorization preflight",
+        "pass": true,
+        "status": 200,
+        "body": "authenticated"
+      },
+      {
+        "name": "unknown header rejected",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "unknown method rejected",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "404 readable",
+        "pass": true,
+        "status": 404,
+        "body": "{\"code\":\"NOT_FOUND\",\"message\":\"route not found\",\"requestId\":\"6a0acbdabaa5e41d862f921dc2f9fdf3\"}\n"
+      },
+      {
+        "name": "credentials mode allowed",
+        "pass": true,
+        "status": 200,
+        "body": "hello"
+      },
+      {
+        "name": "wildcard without credentials",
+        "pass": true,
+        "status": 200,
+        "body": "public"
+      },
+      {
+        "name": "wildcard credentials blocked",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "exposed download header",
+        "pass": true,
+        "status": 200,
+        "body": "file bytes"
+      }
+    ]
+  },
+  "denied": {
+    "allowedPage": false,
+    "passed": true,
+    "checks": [
+      {
+        "name": "simple GET",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "401 readable",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "authorization preflight",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "unknown header rejected",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "unknown method rejected",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "404 readable",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "credentials mode allowed",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "wildcard without credentials",
+        "pass": true,
+        "status": 200,
+        "body": "public"
+      },
+      {
+        "name": "wildcard credentials blocked",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      },
+      {
+        "name": "exposed download header",
+        "pass": true,
+        "blocked": true,
+        "error": "TypeError"
+      }
+    ]
+  },
+  "scope": "20 loopback checks; credentials mode exercised without setting or inspecting cookies"
+}
--- a/scripts/corsBrowser/main.go
+++ b/scripts/corsBrowser/main.go
@@ -0,0 +1,121 @@
+// Run from the framework root; open the printed URLs and click Run checks.
+// All listeners are loopback-only and stop after five minutes or SIGINT/SIGTERM.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+func run() error {
+	var listeners []net.Listener
+	defer func() {
+		for _, l := range listeners {
+			l.Close()
+		}
+	}()
+	for i := 0; i < 4; i++ {
+		l, err := net.Listen("tcp", "127.0.0.1:0")
+		if err != nil {
+			return err
+		}
+		listeners = append(listeners, l)
+	}
+	url := func(i int) string { return "http://" + listeners[i].Addr().String() }
+	app := omni.New(omni.WithCORS(omni.CORSConfig{Enabled: true, AllowedOrigins: []string{url(0)}, AllowedMethods: []string{"GET", "POST"}, AllowedHeaders: []string{"Authorization", "Content-Type"}, ExposedHeaders: []string{"Content-Disposition"}, AllowCredentials: true}))
+	defer app.Close()
+	app.GET("/text", func(c *omni.Context) error { return c.Text(200, "hello") })
+	app.GET("/private", func(c *omni.Context) error {
+		if c.Header("Authorization") != "Bearer example-only" {
+			return omni.Unauthorized("LOGIN_REQUIRED", "login required")
+		}
+		return c.Text(200, "authenticated")
+	})
+	app.GET("/download", func(c *omni.Context) error {
+		c.SetResponseHeader("Content-Disposition", "attachment; filename=example.txt")
+		return c.Text(200, "file bytes")
+	})
+	public := omni.New(omni.WithCORS(omni.CORSConfig{Enabled: true, AllowedOrigins: []string{"*"}}))
+	defer public.Close()
+	public.GET("/text", func(c *omni.Context) error { return c.Text(200, "public") })
+	page := func(allowed bool) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.URL.Path != "/" {
+				http.NotFound(w, r)
+				return
+			}
+			data, _ := json.Marshal(map[string]any{"api": url(2), "publicApi": url(3), "allowed": allowed})
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			io.WriteString(w, strings.Replace(pageSource, "CONFIG_PLACEHOLDER", string(data), 1))
+		})
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancel()
+	errors := make(chan error, 4)
+	var servers []*http.Server
+	for i, h := range []http.Handler{page(true), page(false), app, public} {
+		s := &http.Server{Handler: h, ReadHeaderTimeout: 3 * time.Second, ReadTimeout: 5 * time.Second, WriteTimeout: 5 * time.Second}
+		servers = append(servers, s)
+		go func(l net.Listener) { errors <- s.Serve(l) }(listeners[i])
+	}
+	defer func() {
+		for _, s := range servers {
+			s.Close()
+		}
+	}()
+	fmt.Printf("Allowed page: %s\nDenied page: %s\n", url(0), url(1))
+	select {
+	case <-ctx.Done():
+		return nil
+	case err := <-errors:
+		if err != http.ErrServerClosed {
+			return err
+		}
+		return nil
+	}
+}
+
+const pageSource = `<!doctype html><meta charset="utf-8"><title>GoOmni CORS browser checks</title>
+<h1>GoOmni CORS browser checks</h1><p>Loopback-only, synthetic data; no accounts or credentials required.</p>
+<button id="run">Run checks</button><pre id="results">Not started</pre>
+<script>
+const cfg=CONFIG_PLACEHOLDER;
+document.querySelector('#run').onclick=async()=>{
+ const results=[];const out=document.querySelector('#results');out.textContent='Running';
+ async function check(name,path,options,expected,blocked=false,header=false){
+  try{const r=await fetch(path,options);const body=await r.text();
+   results.push({name,pass:!blocked&&r.status===expected&&(!header||r.headers.get('Content-Disposition')==='attachment; filename=example.txt'),status:r.status,body});
+  }catch(e){results.push({name,pass:blocked&&e.name==='TypeError',blocked:true,error:e.name});}
+ }
+ await check('simple GET',cfg.api+'/text',{},200,!cfg.allowed);
+ await check('401 readable',cfg.api+'/private',{},401,!cfg.allowed);
+ await check('authorization preflight',cfg.api+'/private',{headers:{Authorization:'Bearer example-only'}},200,!cfg.allowed);
+ await check('unknown header rejected',cfg.api+'/private',{headers:{'X-Not-Allowed':'example'}},0,true);
+ await check('unknown method rejected',cfg.api+'/text',{method:'DELETE'},0,true);
+ await check('404 readable',cfg.api+'/missing',{},404,!cfg.allowed);
+ await check('credentials mode allowed',cfg.api+'/text',{credentials:'include'},200,!cfg.allowed);
+ await check('wildcard without credentials',cfg.publicApi+'/text',{},200);
+ await check('wildcard credentials blocked',cfg.publicApi+'/text',{credentials:'include'},0,true);
+ await check('exposed download header',cfg.api+'/download',{},200,!cfg.allowed,cfg.allowed);
+ out.textContent=JSON.stringify({allowedPage:cfg.allowed,passed:results.every(r=>r.pass),checks:results},null,2);
+};
+</script>`
--- a/scripts/verifyManagedRelease.py
+++ b/scripts/verifyManagedRelease.py
@@ -124,7 +124,7 @@ def main():
        checks += ["sharedGoCatalogExport", "documentOnlyErrorSelection", "workspaceCheckNoWrites", "staleCatalogRejected", "twoIndependentServiceBuilds"]

        env.update(GO_OMNI_SCAFFOLD_INTEGRATION="1", GO_OMNI_RELEASE_CLI=str(cli), GO_OMNI_RELEASE_VERSION=args.version)
-        tests = ["TestManagedGeneratedProject", "TestErrorInheritanceConsumer", "TestErrorParamsConsumer", "TestCompatibilityConsumer", "TestBusinessGeneratedProject", "TestPrimitiveArrayConsumer", "TestCopyxThreeEndpointConsumer", "TestGeneratedConfigurationConsumer"]
+        tests = ["TestManagedGeneratedProject", "TestErrorInheritanceConsumer", "TestErrorParamsConsumer", "TestCompatibilityConsumer", "TestBusinessGeneratedProject", "TestPrimitiveArrayConsumer", "TestCopyxThreeEndpointConsumer", "TestGeneratedConfigurationConsumer", "TestGeneratedCORSConsumer"]
        print("Running generated consumers against the remote framework, including lifecycle failure cleanup", flush=True)
        output = run(["go", "test", "-race", "-count=1", "-json", "-timeout=240s", "./cmd/go-omni/apigen", "-run", "^(" + "|".join(tests) + ")$"], ROOT, env)
        events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
@@ -161,13 +161,16 @@ def main():
        for package, expected in {
            "copyx": {"TestCheckTypesAndEmptyCollections", "TestCheckRulesAndConverterBoundaries", "TestCopierCheckConcurrentAndOptionsIsolation"},
            "logx": {"TestLoggerTimeZoneIsolation", "TestLoggerTimeZoneValidationAndDST", "TestLoggerTimeZoneConcurrentChildren"},
+            "cors": {"TestPolicyPreflightAndActual", "TestPolicyValidation", "TestPolicyCredentialsWildcardAndDuplicates", "TestPolicyPreservesHTTPAndSnapshot"},
+            "app": {"TestAppCORSRoutingAndErrors", "TestAppCORSConfigIsolation", "TestCORSTransports"},
        }.items():
            output = run(["go", "test", "-race", "-count=1", "-json", MODULE + "/" + package], starter, env)
            events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
            passed = {event.get("Test") for event in events if event.get("Action") == "pass"}
            assert expected <= passed
        checks += ["remotePreciseModuleDiagnostics", "remoteJSONSuccessStatuses", "remoteRejectedStatusBodyCleanup",
-                   "remoteCopyTypePreflight", "remoteEmptyCollectionTypeRejection", "remoteLoggerTimeZoneIsolation"]
+                   "remoteCopyTypePreflight", "remoteEmptyCollectionTypeRejection", "remoteLoggerTimeZoneIsolation",
+                   "remoteCORSPolicyRace", "remoteCORSErrorResponses", "remoteCORSTransports", "generatedCORSConfigOnly"]

        checks += ["flatFieldComposition", "copyxThreeEndpointConsumer", "explicitNullAndMoneyPolicies", "fieldAdditionWithoutCopyRuleChanges", "middlewareFactoryInjectionAndCleanup", "optionalRepositoryPreservesBusiness"]

@@ -188,6 +191,8 @@ def main():
    sources += [str(p.relative_to(ROOT)) for p in (ROOT / "logx").glob("*.go")]
    sources += ["internal/configdiag/error.go", "database/mysql/mysql.go", "database/connector.go", "database/database.go", "contract/policy.go"]
    sources += [str(p.relative_to(ROOT)) for p in (ROOT / "examples/developerTools").iterdir() if p.is_file()]
+    sources += [str(p.relative_to(ROOT)) for p in (ROOT / "cors").glob("*.go")]
+    sources += ["app/cors_test.go", "cmd/go-omni/apigen/corsConsumer_test.go", "cmd/go-omni/apigen/testdata/cors/consumer_test.go", "examples/cors/main.go", "examples/cors/config.yaml", "scripts/corsBrowser/main.go"]
    report = {"passed": True, "frameworkVersion": args.version, "frameworkSum": dependency["Sum"],
              "freshModuleCache": True, "noLocalReplace": True,
              "durationSeconds": round(time.monotonic() - started, 2), "checks": checks,