fix(server): match browser extension CORS origins by scheme+authority

Applies the maintainer-reviewed implementation from PR #850 (eachann1024)
onto current dev. URL.origin serializes every extension scheme as "null"
per WHATWG URL 4.7, so the old origin-equality check in isExtraAllowedOrigin
admitted ANY browser extension whenever one was allowlisted. comparableOrigin
now keeps WHATWG origins for normal schemes and compares protocol//host for
authority-based opaque origins; hostless opaque origins keep exact-string
fallback. Covers both planes through the shared predicate: data-plane
/v1/* and management /api/* (preflight + GUI session issuance).

Beyond the PR: management-plane preflight assertions (/api/settings
accept + cross-extension reject) folded from the wt4 audit; locale docs
re-based onto the configuration/server.md subpages (docs split 7fdb2cb)
with the Firefox/Safari UUID-rotation caveat (per-install / per-launch
regeneration — MDN, Mozilla bug 1717671, WebKit bug 244330).

Tests: 69/69 server-auth + server-loopback-host-gate; typecheck green.

Author: lidge-jun

devlog/_plan/260802_wt4_server_config_security/011_wp1_execution_notes.md

@@ -0,0 +1,23 @@
+# wp1 execution notes (P-phase stale check, 2026-08-02)
+
+## Stale check results
+
+- `010_implementation.md` line refs: auth-cors.ts `isExtraAllowedOrigin` confirmed live at :81-89 in the pre-fix form; `setCorsOrigin` :21. `origin_rejected` sites in `src/server/index.ts` = 10 (grep-confirmed), all funneled through `isAllowedRequestOrigin`/`isAllowedManagementOrigin` → both call `isExtraAllowedOrigin`, so ONE predicate fix covers every data-plane + management-plane rejection site.
+- Bun URL behavior verified locally (primary proof): `chrome-extension://abc123/page.html`, `moz-extension://u-u-i-d/`, `safari-web-extension://UUID/` all serialize `.origin` as `"null"` with `host` populated.
+- Docs drift: `docs-site` configuration reference was split into domain subpages (commit 7fdb2cb8e). The `corsAllowOrigins` row now lives at `docs-site/src/content/docs/<locale>/reference/configuration/server.md` (:19-20) for all five locales (EN, zh-cn, ko, ja, ru). The PR #850 doc hunks DO NOT APPLY to current dev — docs must be re-based onto the subpage rows.
+- PR #850 state: OPEN, CONFLICTING vs dev. Maintainer review blocker (locale doc drift) was already fixed by the contributor in a346ad60, so the fetched diff head is review-clean. Code+test hunks APPLY CLEAN to dev@478354ee8 (`git apply --check --include='src/**' --include='tests/**'`).
+
+## wp1 execution decision
+
+Apply the maintainer-reviewed PR #850 diff for `src/server/auth-cors.ts`, `src/types.ts`, `tests/server-auth.test.ts`, `tests/server-loopback-host-gate.test.ts` verbatim (credit eachann1024), then re-write the five `server.md` rows by hand in the new subpage location with the same content the PR used (authority-based extension origins supported; `*` is not a wildcard).
+
+Rationale: the implementation is small, already maintainer-reviewed, and its test shape (live server preflight + data-plane + unit-level cross-scheme and `*` rejection) matches the acceptance criteria in `010_implementation.md` exactly. Hand-rewriting an equivalent fix would add risk, not value.
+
+## Acceptance (carried from 010, mapped to PR tests)
+
+1. Configured extension ID passes preflight + `/v1/models` — covered by the new `server-auth.test.ts` case (204 + allow-origin echo; 200 data-plane).
+2. Different extension ID rejected — covered (403 live; false unit).
+3. Cross-scheme isolation (`moz-extension://<same-id>` rejected) — covered by unit test.
+4. `*` rejected — covered by unit test.
+5. Non-extension behavior unchanged — existing `server-auth` / `server-loopback-host-gate` suites must stay green.
+6. Docs: five locale `server.md` rows updated; locales must not contradict EN.

docs-site/src/content/docs/ja/reference/configuration/server.md

@@ -16,7 +16,7 @@ description: リスナー、リモート アクセス、アドミッション 
 | `connectTimeoutMs?` | `number` | `200000` |試行ごとの DNS/TCP/TLS/最終ヘッダーの期限。本体が生成される前に終了します。 |
 | `shutdownTimeoutMs?` | `number` | `5000` |アクティブなターンが中止される前の正常な排出期限。 |
 | `websockets?` | `boolean` | `false` |応答 WebSocket パスとして `supports_websockets` をアドバタイズします。 False は HTTP/SSE を維持します。 |
-| `corsAllowOrigins?` | `string[]` | `[]` |追加の正確な CORS 起点。ループバック起点は常に許可されます。 |
+| `corsAllowOrigins?` | `string[]` | `[]` | 追加の正確な CORS origin。ループバック origin は常に許可します。`chrome-extension://<extension-id>` など authority ベースのブラウザー拡張 origin に対応し、`*` はワイルドカードではありません。Firefox と Safari は拡張 UUID を（インストール/ブラウザー起動ごとに）再生成するため、origin が変わったらエントリを更新してください。 |
 | `apiKeys?` | `OcxApiKey[]` | `[]` |生成された `ocx_…` 資格情報は、非ループバック バインドでの管理およびデータ プレーン認証によって受け入れられました。ダッシュボードで管理。 |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` |無効 |アーカイブされたセッションのクリーンアップ ポリシーをオプトインします。暗黙的に有効になることはありません。 |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` |排除可能なアプリ所有のログ、キャッシュ、BLOB、および継続ペイロードの MiB の上限。範囲は 64 ～ 4096。 RSSキャップではありません。 |

docs-site/src/content/docs/ko/reference/configuration/server.md

@@ -16,7 +16,7 @@ description: 리스너, 원격 접근, admission 키, 타임아웃, 저장소, 
 | `connectTimeoutMs?` | `number` | `200000` | 시도별 DNS/TCP/TLS/최종 헤더 기한입니다. 본문 생성 전에 끝납니다. |
 | `shutdownTimeoutMs?` | `number` | `5000` | 진행 중인 turn을 중단하기 전에 허용하는 정상 종료 드레인 기한입니다. |
 | `websockets?` | `boolean` | `false` | Responses WebSocket 경로에 `supports_websockets`를 광고합니다. `false`이면 HTTP/SSE를 유지합니다. |
-| `corsAllowOrigins?` | `string[]` | `[]` | 추가로 허용할 정확한 CORS origin입니다. 루프백 origin은 항상 허용됩니다. |
+| `corsAllowOrigins?` | `string[]` | `[]` | CORS에서 추가로 허용할 정확한 origin입니다. 루프백 origin은 항상 허용됩니다. `chrome-extension://<extension-id>` 같은 authority 기반 브라우저 확장 origin을 지원하며, `*`는 와일드카드가 아닙니다. Firefox와 Safari는 확장 UUID를 (설치/브라우저 실행 때마다) 새로 만드므로 origin이 바뀌면 항목을 갱신하세요. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | 비루프백 바인드에서 관리 API와 데이터 플레인 인증이 허용하는 생성된 `ocx_…` 자격 증명입니다. 대시보드에서 관리합니다. |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | 선택적으로 활성화하는 보관 세션 정리 정책입니다. 절대 암묵적으로 활성화되지 않습니다. |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | 제거 가능한 앱 소유 로그, 캐시, blob, continuation payload에 대한 MiB 단위 상한입니다. 범위는 64–4096이며 RSS 상한은 아닙니다. |

docs-site/src/content/docs/reference/configuration/server.md

@@ -17,7 +17,7 @@ runs helper features around provider requests.
 | `connectTimeoutMs?` | `number` | `200000` | Per-attempt DNS/TCP/TLS/final-header deadline; it ends before body generation. |
 | `shutdownTimeoutMs?` | `number` | `5000` | Graceful drain deadline before active turns are aborted. |
 | `websockets?` | `boolean` | `false` | Advertise `supports_websockets` for the Responses WebSocket path. False keeps HTTP/SSE. |
-| `corsAllowOrigins?` | `string[]` | `[]` | Additional exact CORS origins. Loopback origins are always allowed. |
+| `corsAllowOrigins?` | `string[]` | `[]` | Additional exact origins allowed by CORS. Loopback origins are always allowed. Authority-based browser extension origins such as `chrome-extension://<extension-id>` are supported; `*` is not a wildcard. Firefox and Safari regenerate the extension UUID (per install / per browser launch), so update the entry when the origin changes. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | Generated `ocx_…` credentials accepted by management and data-plane auth on non-loopback binds. Dashboard-managed. |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | Opt-in archived-session cleanup policy. Never enabled implicitly. |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | Cap in MiB for evictable app-owned logs, caches, blobs, and continuation payloads. Range 64–4096; not an RSS cap. |

docs-site/src/content/docs/ru/reference/configuration/server.md

@@ -17,7 +17,7 @@ description: Listener, удалённый доступ, admission key, тайм
 | `connectTimeoutMs?` | `number` | `200000` | Дедлайн одной попытки DNS/TCP/TLS/final-header; он завершается до генерации тела ответа. |
 | `shutdownTimeoutMs?` | `number` | `5000` | Дедлайн graceful-drain до принудительного прерывания активных turn'ов. |
 | `websockets?` | `boolean` | `false` | Объявлять `supports_websockets` для WebSocket-пути Responses. Значение false удерживает HTTP/SSE. |
-| `corsAllowOrigins?` | `string[]` | `[]` | Дополнительные точные CORS-origin'ы. Loopback-origin'ы разрешены всегда. |
+| `corsAllowOrigins?` | `string[]` | `[]` | Дополнительные точные origin, разрешённые CORS. Loopback-origin разрешены всегда. Поддерживаются authority-based origin браузерных расширений, например `chrome-extension://<extension-id>`; `*` не является маской. Firefox и Safari пересоздают UUID расширения (при каждой установке/запуске браузера), поэтому обновляйте запись при смене origin. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | Сгенерированные credentials `ocx_…`, принимаемые для management и data-plane auth на не-loopback bind'ах. Управляются через дашборд. |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | Opt-in policy очистки архивированных сессий. Никогда не включается неявно. |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | Лимит в MiB для eviction-friendly app-owned log'ов, cache'ей, blob'ов и continuation payload'ов. Это не RSS-cap. Диапазон 64–4096. |

docs-site/src/content/docs/zh-cn/reference/configuration/server.md

@@ -17,7 +17,7 @@ description: 监听、远程访问、准入密钥、超时、存储、侧车、
 | `connectTimeoutMs?` | `number` | `200000` | 每次尝试的 DNS/TCP/TLS/最终响应头截止时间；它在正文生成之前结束。 |
 | `shutdownTimeoutMs?` | `number` | `5000` | 优雅停机截止时间，超过后会中止仍在进行中的请求。 |
 | `websockets?` | `boolean` | `false` | 为 Responses WebSocket 路径声明 `supports_websockets`。设为 false 会保留 HTTP/SSE。 |
-| `corsAllowOrigins?` | `string[]` | `[]` | 额外的精确 CORS 来源。回环来源始终允许。 |
+| `corsAllowOrigins?` | `string[]` | `[]` | CORS 额外允许的精确 origin。loopback origin 始终允许；支持 `chrome-extension://<扩展 ID>` 等基于 authority 的浏览器扩展 origin，`*` 不是通配符。Firefox 和 Safari 会（每次安装/启动浏览器时）重新生成扩展 UUID，origin 变化后请更新该条目。 |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | 管理平面和非回环绑定上的数据平面身份验证可接受的已生成 `ocx_…` 凭据。由仪表板管理。 |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | 可选启用的归档会话清理策略。不会被隐式启用。 |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | 可逐出应用自有日志、缓存、blob 和续传载荷的内存上限，单位 MiB。范围 64–4096；不是 RSS 上限。 |

src/server/auth-cors.ts

@@ -80,15 +80,28 @@ export function isAllowedRequestOrigin(req: Request, config: OcxConfig): boolean
 
 function isExtraAllowedOrigin(origin: string, cfg: OcxConfig): boolean {
   if (!cfg.corsAllowOrigins?.length) return false;
+  const parsedOrigin = comparableOrigin(origin);
   return cfg.corsAllowOrigins.some(allowed => {
-    try {
-      return new URL(allowed).origin === new URL(origin).origin;
-    } catch {
-      return allowed === origin;
-    }
+    const parsedAllowed = comparableOrigin(allowed);
+    return parsedOrigin !== null && parsedAllowed !== null
+      ? parsedAllowed === parsedOrigin
+      : allowed === origin;
   });
 }
 
+function comparableOrigin(value: string): string | null {
+  try {
+    const parsed = new URL(value);
+    if (parsed.origin !== "null") return parsed.origin;
+    // WHATWG URL exposes authority-based custom schemes (for example browser
+    // extensions) as opaque `null` origins. Compare their scheme + authority so
+    // one allowlisted extension cannot admit every other opaque origin.
+    return parsed.host ? `${parsed.protocol}//${parsed.host}` : null;
+  } catch {
+    return null;
+  }
+}
+
 export function managementRequestOrigin(req: Request, config: OcxConfig): string | null {
   const host = req.headers.get("Host");
   const parsedHost = parseHttpHost(host);

src/types.ts

@@ -756,7 +756,7 @@ export interface OcxConfig {
   combos?: Record<string, OcxComboConfig>;
   /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
   tokenGuardian?: OcxTokenGuardianConfig;
-  /** Additional origins allowed for CORS (e.g. ["https://clisu-oracle.tail19a2d7.ts.net"]). Loopback origins are always allowed. */
+  /** Additional exact origins allowed for CORS (e.g. HTTPS or chrome-extension://<id>). Loopback origins are always allowed. */
   corsAllowOrigins?: string[];
 }
 

tests/server-auth.test.ts

@@ -632,6 +632,68 @@ describe("server local API auth", () => {
     }
   });
 
+  test("extension allowlist gates preflight and data-plane requests by authority", async () => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    const extensionOrigin = "chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofh";
+    saveConfig({
+      ...config("127.0.0.1"),
+      corsAllowOrigins: [extensionOrigin],
+    });
+    stubModelDiscoveryFor("https://api.example.test");
+
+    const server = startServer(0);
+    const modelsUrl = new URL("/v1/models", server.url);
+    try {
+      const preflight = await fetch(modelsUrl, {
+        method: "OPTIONS",
+        headers: {
+          origin: extensionOrigin,
+          "access-control-request-method": "GET",
+        },
+      });
+      expect(preflight.status).toBe(204);
+      expect(preflight.headers.get("access-control-allow-origin")).toBe(extensionOrigin);
+
+      const accepted = await fetch(modelsUrl, { headers: { origin: extensionOrigin } });
+      expect(accepted.status).toBe(200);
+      expect(accepted.headers.get("access-control-allow-origin")).toBe(extensionOrigin);
+
+      const rejected = await fetch(modelsUrl, {
+        headers: { origin: "chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" },
+      });
+      expect(rejected.status).toBe(403);
+
+      // The management plane shares isExtraAllowedOrigin: the configured extension gets
+      // its preflight echoed, any other extension is refused before reaching /api/*.
+      const managementUrl = new URL("/api/settings", server.url);
+      const managementPreflight = await fetch(managementUrl, {
+        method: "OPTIONS",
+        headers: {
+          origin: extensionOrigin,
+          "access-control-request-method": "GET",
+        },
+      });
+      expect(managementPreflight.status).toBe(204);
+      expect(managementPreflight.headers.get("access-control-allow-origin")).toBe(extensionOrigin);
+
+      const managementRejected = await fetch(managementUrl, {
+        method: "OPTIONS",
+        headers: {
+          origin: "chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "access-control-request-method": "GET",
+        },
+      });
+      expect(managementRejected.status).toBe(403);
+      expect(managementRejected.headers.get("access-control-allow-origin")).not.toBe(
+        "chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      );
+    } finally {
+      await server.stop(true);
+    }
+  });
+
   test("loopback management API rejects host-header same-origin rebinding", async () => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });

tests/server-loopback-host-gate.test.ts

@@ -96,3 +96,38 @@ describe("isAllowedRequestOrigin over a forwarded port", () => {
     ).toBe(false);
   });
 });
+
+describe("isAllowedRequestOrigin with extension origins", () => {
+  test("admits only the configured browser extension authority", () => {
+    const config = {
+      ...loopbackConfig,
+      corsAllowOrigins: ["chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofh"],
+    } as OcxConfig;
+
+    expect(
+      isAllowedRequestOrigin(
+        request("localhost:10100", "chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofh"),
+        config,
+      ),
+    ).toBe(true);
+    expect(
+      isAllowedRequestOrigin(
+        request("localhost:10100", "chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
+        config,
+      ),
+    ).toBe(false);
+    expect(
+      isAllowedRequestOrigin(
+        request("localhost:10100", "moz-extension://modkelfkcfjpgbfmnbnllalkiogfofh"),
+        config,
+      ),
+    ).toBe(false);
+
+    expect(
+      isAllowedRequestOrigin(
+        request("localhost:10100", "chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofh"),
+        { ...loopbackConfig, corsAllowOrigins: ["*"] } as OcxConfig,
+      ),
+    ).toBe(false);
+  });
+});