agent-webview 0.1.4__tar.gz → 0.1.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. {agent_webview-0.1.4 → agent_webview-0.1.6}/.github/workflows/ci.yml +4 -4
  2. {agent_webview-0.1.4 → agent_webview-0.1.6}/CHANGELOG.md +31 -0
  3. {agent_webview-0.1.4 → agent_webview-0.1.6}/CONTRIBUTING.md +9 -6
  4. {agent_webview-0.1.4 → agent_webview-0.1.6}/PKG-INFO +68 -6
  5. {agent_webview-0.1.4 → agent_webview-0.1.6}/README.md +65 -5
  6. {agent_webview-0.1.4 → agent_webview-0.1.6}/README_EN.md +64 -4
  7. agent_webview-0.1.6/SECURITY.md +48 -0
  8. {agent_webview-0.1.4 → agent_webview-0.1.6}/pyproject.toml +5 -0
  9. {agent_webview-0.1.4 → agent_webview-0.1.6}/scripts/release_check.py +50 -17
  10. {agent_webview-0.1.4 → agent_webview-0.1.6}/scripts/smoke_proxy_switch.py +5 -0
  11. agent_webview-0.1.6/scripts/smoke_storage_cache.py +133 -0
  12. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/__init__.py +1 -1
  13. agent_webview-0.1.6/src/agent_webview/cache_proxy.py +76 -0
  14. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/controller_api.py +2 -1
  15. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/cookies.py +4 -0
  16. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/models.py +44 -0
  17. agent_webview-0.1.6/src/agent_webview/native.py +168 -0
  18. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/proxy.py +3 -34
  19. agent_webview-0.1.6/src/agent_webview/resource_cache.py +125 -0
  20. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/runtime.py +11 -0
  21. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/sessions.py +10 -1
  22. agent_webview-0.1.6/src/agent_webview/storage.py +34 -0
  23. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/worker.py +46 -6
  24. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/worker_api.py +5 -0
  25. agent_webview-0.1.6/tests/test_cache_proxy.py +155 -0
  26. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_controller_api.py +2 -1
  27. agent_webview-0.1.6/tests/test_native.py +67 -0
  28. agent_webview-0.1.6/tests/test_resource_cache.py +109 -0
  29. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_runtime.py +19 -0
  30. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_sessions.py +22 -0
  31. agent_webview-0.1.6/tests/test_storage.py +63 -0
  32. {agent_webview-0.1.4 → agent_webview-0.1.6}/uv.lock +925 -3
  33. agent_webview-0.1.4/SECURITY.md +0 -26
  34. {agent_webview-0.1.4 → agent_webview-0.1.6}/.github/dependabot.yml +0 -0
  35. {agent_webview-0.1.4 → agent_webview-0.1.6}/.github/workflows/publish.yml +0 -0
  36. {agent_webview-0.1.4 → agent_webview-0.1.6}/.gitignore +0 -0
  37. {agent_webview-0.1.4 → agent_webview-0.1.6}/LICENSE +0 -0
  38. {agent_webview-0.1.4 → agent_webview-0.1.6}/docs/api-stability.md +0 -0
  39. {agent_webview-0.1.4 → agent_webview-0.1.6}/examples/debug_page.html +0 -0
  40. {agent_webview-0.1.4 → agent_webview-0.1.6}/scripts/smoke_service.py +0 -0
  41. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/__main__.py +0 -0
  42. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/auth.py +0 -0
  43. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/bridge.py +0 -0
  44. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/cli.py +0 -0
  45. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/errors.py +0 -0
  46. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/events.py +0 -0
  47. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/files.py +0 -0
  48. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/http_errors.py +0 -0
  49. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/js.py +0 -0
  50. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/logging.py +0 -0
  51. {agent_webview-0.1.4 → agent_webview-0.1.6}/src/agent_webview/proxy_relay.py +0 -0
  52. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_bridge.py +0 -0
  53. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_cli.py +0 -0
  54. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_cookies.py +0 -0
  55. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_events.py +0 -0
  56. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_files.py +0 -0
  57. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_js.py +0 -0
  58. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_models.py +0 -0
  59. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_proxy.py +0 -0
  60. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_proxy_relay.py +0 -0
  61. {agent_webview-0.1.4 → agent_webview-0.1.6}/tests/test_worker_api.py +0 -0
@@ -22,11 +22,11 @@ jobs:
22
22
  with:
23
23
  python-version: ${{ matrix.python }}
24
24
  enable-cache: true
25
- - run: uv sync --extra dev
26
- - run: uv run ruff check src tests scripts
27
- - run: uv run mypy
25
+ - run: uv sync --extra dev --extra cache
26
+ - run: uv run --extra dev --extra cache ruff check src tests scripts
27
+ - run: uv run --extra dev --extra cache mypy
28
28
  - run: >-
29
- uv run pytest
29
+ uv run --extra dev --extra cache pytest
30
30
  --cov=agent_webview
31
31
  --cov-report=term
32
32
  --cov-fail-under=70
@@ -4,6 +4,37 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.1.6] - 2026-11-14
8
+
9
+ ### Fixed
10
+
11
+ - 修复 macOS 14 中启用资源缓存后 HTTPS 页面停在隐藏窗口并超时的问题。窗口改用独立的 WKWebView 数据存储配置 HTTP/HTTPS 代理,避免 Network.framework CONNECT 通道拒绝已验证的临时缓存证书。
12
+ - 在 WKWebView 创建前安装数据存储,并让 Cookie 读取和无痕清理使用同一存储;不修改系统代理或钥匙串,保留上游证书校验和会话隔离。
13
+ - 同时修复普通代理会话对仅能通过上游解析的 HTTP 域名加载失败的问题;原生代理配置不可用时明确报错,不回退直连。
14
+
15
+ ### Tests
16
+
17
+ - 增加原生代理配置时序、Cookie 存储绑定和配置失败测试。
18
+ - 扩展真实窗口冒烟测试,覆盖无痕 Cookie/localStorage 隔离及开启缓存时的账密代理切换。
19
+
20
+ ### Security
21
+
22
+ - 核查新增 Tornado RedirectHandler 告警 CVE-2026-126347:缓存进程不加载 Tornado,隔离测试继续通过;记录精确版本例外,详见 SECURITY.md。
23
+
24
+ ## [0.1.5] - 2026-11-12
25
+
26
+ ### Added
27
+
28
+ - 登录快照保存当前 origin 的完整 localStorage,原生 document-start 恢复,兼容旧 Cookie 快照。
29
+ - 创建会话支持 `private_mode` 和 `resource_cache`,默认缓存 JS/CSS,可配置后缀、保留时间与容量。
30
+ - 可选 `cache` 依赖提供跨进程 HTTP/HTTPS 磁盘缓存,支持既有代理,临时 CA 仅在当前窗口受信任。
31
+ - 新增存储/缓存单元测试及真实 WebView 冒烟测试;缓存需要 Python 3.12+。
32
+
33
+ ### Security
34
+
35
+ - 发布检查覆盖 cache extra;记录 Tornado 6.5.10 三项不涉及缓存引擎运行路径的已核查告警,新增禁止加载 Tornado 的隔离测试,详见 SECURITY.md。
36
+ - 缓存代理关闭内置 onboarding 页面,HTTPS 上游保持证书验证。
37
+
7
38
  ## [0.1.4] - 2026-10-30
8
39
 
9
40
  ### Security
@@ -1,14 +1,17 @@
1
1
  # 参与开发
2
2
 
3
- 需要 Python 3.10 以上版本和 [uv](https://docs.astral.sh/uv/)。
3
+ 基础开发需要 Python 3.10 以上版本和 [uv](https://docs.astral.sh/uv/)。
4
+ 资源缓存测试需要 Python 3.12+ 及 `cache` extra。
4
5
 
5
6
  ```bash
6
- uv sync --extra dev
7
- uv run ruff check src tests
8
- uv run mypy
9
- uv run pytest
7
+ uv sync --extra dev --extra cache
8
+ uv run --extra dev --extra cache ruff check src tests
9
+ uv run --extra dev --extra cache mypy
10
+ uv run --extra dev --extra cache pytest
10
11
  uv run python scripts/smoke_service.py
11
- uv run python scripts/smoke_proxy_switch.py
12
+ uv run --extra cache python scripts/smoke_proxy_switch.py
13
+ uv run --extra cache python scripts/smoke_proxy_switch.py --cache
14
+ uv run --extra cache python scripts/smoke_storage_cache.py
12
15
  ```
13
16
 
14
17
  代码注释、日志、调试输出和用户可见错误使用简短中文。提交应保持通用,不加入
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agent-webview
3
- Version: 0.1.4
3
+ Version: 0.1.6
4
4
  Summary: A hidden pywebview browser controlled through an agent-friendly HTTP debugging API.
5
5
  Project-URL: Homepage, https://github.com/Yuv96/agent-webview
6
6
  Project-URL: Repository, https://github.com/Yuv96/agent-webview.git
@@ -37,6 +37,8 @@ Requires-Dist: pyobjc-framework-network>=10; sys_platform == 'darwin'
37
37
  Requires-Dist: pywebview<7,>=6.2.1
38
38
  Requires-Dist: structlog<26,>=25.1
39
39
  Requires-Dist: uvicorn<1,>=0.34
40
+ Provides-Extra: cache
41
+ Requires-Dist: mitmproxy<13,>=12.3.1; (python_version >= '3.12') and extra == 'cache'
40
42
  Provides-Extra: dev
41
43
  Requires-Dist: detect-secrets<2,>=1.5; extra == 'dev'
42
44
  Requires-Dist: httpx2<3,>=2; extra == 'dev'
@@ -83,7 +85,8 @@ Description-Content-Type: text/markdown
83
85
  | 页面操作 | 支持导航、DOM 查询、输入、点击和 JavaScript 执行 |
84
86
  | 可观测性 | 支持 DOM 事件、DOM 变更和页面网络活动的长轮询采集 |
85
87
  | 代理调试 | 支持全局或单窗口 HTTP/HTTPS 代理,并异步查询出口 IP 与归属地 |
86
- | Cookie 快照 | 可保存 Cookie,并在新会话中尽力恢复 |
88
+ | 登录快照 | 保存 Cookie 和当前 origin 的 localStorage,并在新会话恢复 |
89
+ | 资源缓存 | 可选跨进程本地缓存,默认仅 JS/CSS,支持后缀白名单 |
87
90
  | 跨平台 | 支持 Windows、macOS 和带 GTK/Qt 后端的 Linux |
88
91
 
89
92
  ## 🧱 工作方式
@@ -349,21 +352,80 @@ if proxy["state"] == "active":
349
352
  或所有响应体。需要协议级调试时,可以在创建会话时设置
350
353
  `remote_debugging_port`,并使用后端支持的 DevTools 协议。
351
354
 
352
- ## 🍪 Cookie 快照
355
+ ## 🍪 登录快照(Cookie + localStorage)
353
356
 
354
357
  Cookie 快照默认保存在当前用户数据目录,也可以通过 `--data-dir` 指定位置。创建
355
358
  新会话时传入 `snapshot_id` 即可尝试恢复;请求中显式提供的 `cookies` 会覆盖快照
356
- 内同名、同域、同路径的 Cookie。
359
+ 内同名、同域、同路径的 Cookie。原 `/cookie-snapshots` 路径保持兼容。
360
+
361
+ 新快照增加 `schema_version: 2` 和 `local_storage: {"https://example.com": {"key": "value"}}`。
362
+ 保存当前主文档 origin(协议、主机、端口)的全部 localStorage 字符串键值,包含空值、
363
+ Unicode、特殊键名和超过 500 个键的存储。恢复时先清空对应 origin,再写入快照内容;
364
+ 通过原生 document-start 脚本,在网站首段 JavaScript 运行前执行。只在该会话首次访问
365
+ 匹配 origin 时恢复,后续刷新或导航不覆盖网站新写入的数据,也不向其他 origin 注入凭证。
366
+ 旧的仅 Cookie 快照仍可加载。localStorage 恢复支持 macOS WKWebView、Windows WebView2。
357
367
 
358
368
  恢复存在浏览器后端限制:
359
369
 
360
370
  - pywebview 可以读取包含 HttpOnly 在内的 Cookie。
361
371
  - 通用跨后端恢复依赖 `document.cookie`,因此无法恢复 HttpOnly Cookie。
362
372
  - Domain、SameSite、Secure、过期时间和浏览器策略可能拒绝部分 Cookie。
363
- - 快照不包含 IndexedDB、Local Storage、Service Worker 或缓存。
373
+ - localStorage 仅包含保存时的当前主文档 origin,不包含其他 origin、跨域 iframe、sessionStorage、IndexedDB 或 Service Worker。
374
+ - 资源缓存独立保存在数据目录中,不打包进登录快照。
364
375
 
365
376
  Cookie 快照和运行信息文件都应按敏感数据处理,不应提交到版本控制系统。
366
377
 
378
+ ## 📦 启动资源缓存
379
+
380
+ 使用 Python 3.12+ 安装可选依赖(基础功能仍支持 Python 3.10+):
381
+
382
+ ```bash
383
+ pip install 'agent-webview[cache]'
384
+ # 源码开发环境
385
+ uv sync --extra dev --extra cache
386
+ ```
387
+
388
+ 创建会话时指定:
389
+
390
+ ```json
391
+ {
392
+ "url": "https://example.com/",
393
+ "private_mode": true,
394
+ "resource_cache": {
395
+ "enabled": true,
396
+ "extensions": [".js", ".css"],
397
+ "max_age_seconds": 604800,
398
+ "max_resource_bytes": 20971520,
399
+ "max_total_bytes": 536870912
400
+ }
401
+ }
402
+ ```
403
+
404
+ `private_mode` 默认 `true`,可设为 `false`;两种模式均可启用资源缓存。API 会话仍采用独立进程;共享资源保存在 `<data-dir>/resource-cache/resources.sqlite3`,
405
+ worker 或控制器重启后仍可复用。缓存默认关闭,关闭时既不读取也不写入共享缓存。
406
+
407
+ 命中有效缓存直接返回本地资源;未命中则联网并保存成功响应。完整 URL(含查询参数)、
408
+ 协议、端口及响应 Vary 指定的请求头参与匹配;Cookie、Authorization、Origin 和压缩协商
409
+ 始终隔离,不同凭证不会互用响应。未被 Vary 指定的 Referer 等请求头变化不影响命中。
410
+ 各资源按自己的域名区分,CDN 资源也可缓存。默认仅 URL 路径后缀 `.js`、`.css`;
411
+ 图片、HTML、无后缀 URL 默认不缓存,可显式加入 `.svg`、`.png`、`.html`、`.mjs` 等后缀。
412
+ 列表为完整白名单,`[".svg"]` 表示仅缓存 SVG;大小写会归一化,查询参数不参与后缀判断。
413
+
414
+ 缓存采用显式 cache-first 策略:在 `max_age_seconds` 内复用,不按服务器的 max-age
415
+ 重新验证。因此内容有变化应更换资源 URL/版本参数,缩短保存时间,或停止会话后删除缓存数据库。
416
+ 仅保存 GET 的完整 200 响应;跳过 Range、升级请求、`no-store`、`private`、`Vary: *`、
417
+ 带 `Set-Cookie` 的响应以及超大资源。默认单项上限 20 MiB、实体总量 512 MiB,超限淘汰最早条目。
418
+ 页面或 Service Worker 自行截获的请求不经过此缓存。
419
+
420
+ HTTP/HTTPS 缓存由 worker 内的本地代理完成,兼容既有全局/单窗口代理;HTTPS 上游仍进行
421
+ 证书校验,临时 CA 只由当前窗口信任,不写入系统钥匙串。支持 macOS 14+ WKWebView 和
422
+ Windows WebView2;其他后端启用时明确报错。浏览器对 localhost/回环地址可能绕过代理,
423
+ 本地站点不保证进入共享缓存。此模式使用代理网络栈,依赖 TLS 指纹或客户端证书的网站可能不兼容。
424
+
425
+ macOS 窗口通过独立 WKWebView 数据存储配置代理,兼容 macOS 14 的 HTTPS 缓存证书验证。Cookie 读取和无痕清理使用该窗口的同一存储;系统代理和钥匙串不变。原生配置接口不可用时会明确报错,不退回直连。
426
+
427
+ 验证命令:`uv run --extra cache python scripts/smoke_storage_cache.py`;缓存与代理切换组合验证:`uv run --extra cache python scripts/smoke_proxy_switch.py --cache`。
428
+
367
429
  ## ⚙️ 常用配置
368
430
 
369
431
  | 参数 | 默认值 | 说明 |
@@ -396,7 +458,7 @@ Cookie 快照和运行信息文件都应按敏感数据处理,不应提交到
396
458
 
397
459
  ## 📐 设计边界
398
460
 
399
- - 无痕隔离依靠“一会话一进程”和 `private_mode=True`。
461
+ - 默认无痕隔离依靠“一会话一进程”和 `private_mode=True`;可在创建请求中关闭无痕。
400
462
  - 所有 worker 接口只监听随机本机端口,并使用独立内部令牌。
401
463
  - 控制器重启不会恢复仍在运行的 worker 会话。
402
464
  - DOM `click()` 不等同于操作系统级鼠标事件。
@@ -29,7 +29,8 @@
29
29
  | 页面操作 | 支持导航、DOM 查询、输入、点击和 JavaScript 执行 |
30
30
  | 可观测性 | 支持 DOM 事件、DOM 变更和页面网络活动的长轮询采集 |
31
31
  | 代理调试 | 支持全局或单窗口 HTTP/HTTPS 代理,并异步查询出口 IP 与归属地 |
32
- | Cookie 快照 | 可保存 Cookie,并在新会话中尽力恢复 |
32
+ | 登录快照 | 保存 Cookie 和当前 origin 的 localStorage,并在新会话恢复 |
33
+ | 资源缓存 | 可选跨进程本地缓存,默认仅 JS/CSS,支持后缀白名单 |
33
34
  | 跨平台 | 支持 Windows、macOS 和带 GTK/Qt 后端的 Linux |
34
35
 
35
36
  ## 🧱 工作方式
@@ -295,21 +296,80 @@ if proxy["state"] == "active":
295
296
  或所有响应体。需要协议级调试时,可以在创建会话时设置
296
297
  `remote_debugging_port`,并使用后端支持的 DevTools 协议。
297
298
 
298
- ## 🍪 Cookie 快照
299
+ ## 🍪 登录快照(Cookie + localStorage)
299
300
 
300
301
  Cookie 快照默认保存在当前用户数据目录,也可以通过 `--data-dir` 指定位置。创建
301
302
  新会话时传入 `snapshot_id` 即可尝试恢复;请求中显式提供的 `cookies` 会覆盖快照
302
- 内同名、同域、同路径的 Cookie。
303
+ 内同名、同域、同路径的 Cookie。原 `/cookie-snapshots` 路径保持兼容。
304
+
305
+ 新快照增加 `schema_version: 2` 和 `local_storage: {"https://example.com": {"key": "value"}}`。
306
+ 保存当前主文档 origin(协议、主机、端口)的全部 localStorage 字符串键值,包含空值、
307
+ Unicode、特殊键名和超过 500 个键的存储。恢复时先清空对应 origin,再写入快照内容;
308
+ 通过原生 document-start 脚本,在网站首段 JavaScript 运行前执行。只在该会话首次访问
309
+ 匹配 origin 时恢复,后续刷新或导航不覆盖网站新写入的数据,也不向其他 origin 注入凭证。
310
+ 旧的仅 Cookie 快照仍可加载。localStorage 恢复支持 macOS WKWebView、Windows WebView2。
303
311
 
304
312
  恢复存在浏览器后端限制:
305
313
 
306
314
  - pywebview 可以读取包含 HttpOnly 在内的 Cookie。
307
315
  - 通用跨后端恢复依赖 `document.cookie`,因此无法恢复 HttpOnly Cookie。
308
316
  - Domain、SameSite、Secure、过期时间和浏览器策略可能拒绝部分 Cookie。
309
- - 快照不包含 IndexedDB、Local Storage、Service Worker 或缓存。
317
+ - localStorage 仅包含保存时的当前主文档 origin,不包含其他 origin、跨域 iframe、sessionStorage、IndexedDB 或 Service Worker。
318
+ - 资源缓存独立保存在数据目录中,不打包进登录快照。
310
319
 
311
320
  Cookie 快照和运行信息文件都应按敏感数据处理,不应提交到版本控制系统。
312
321
 
322
+ ## 📦 启动资源缓存
323
+
324
+ 使用 Python 3.12+ 安装可选依赖(基础功能仍支持 Python 3.10+):
325
+
326
+ ```bash
327
+ pip install 'agent-webview[cache]'
328
+ # 源码开发环境
329
+ uv sync --extra dev --extra cache
330
+ ```
331
+
332
+ 创建会话时指定:
333
+
334
+ ```json
335
+ {
336
+ "url": "https://example.com/",
337
+ "private_mode": true,
338
+ "resource_cache": {
339
+ "enabled": true,
340
+ "extensions": [".js", ".css"],
341
+ "max_age_seconds": 604800,
342
+ "max_resource_bytes": 20971520,
343
+ "max_total_bytes": 536870912
344
+ }
345
+ }
346
+ ```
347
+
348
+ `private_mode` 默认 `true`,可设为 `false`;两种模式均可启用资源缓存。API 会话仍采用独立进程;共享资源保存在 `<data-dir>/resource-cache/resources.sqlite3`,
349
+ worker 或控制器重启后仍可复用。缓存默认关闭,关闭时既不读取也不写入共享缓存。
350
+
351
+ 命中有效缓存直接返回本地资源;未命中则联网并保存成功响应。完整 URL(含查询参数)、
352
+ 协议、端口及响应 Vary 指定的请求头参与匹配;Cookie、Authorization、Origin 和压缩协商
353
+ 始终隔离,不同凭证不会互用响应。未被 Vary 指定的 Referer 等请求头变化不影响命中。
354
+ 各资源按自己的域名区分,CDN 资源也可缓存。默认仅 URL 路径后缀 `.js`、`.css`;
355
+ 图片、HTML、无后缀 URL 默认不缓存,可显式加入 `.svg`、`.png`、`.html`、`.mjs` 等后缀。
356
+ 列表为完整白名单,`[".svg"]` 表示仅缓存 SVG;大小写会归一化,查询参数不参与后缀判断。
357
+
358
+ 缓存采用显式 cache-first 策略:在 `max_age_seconds` 内复用,不按服务器的 max-age
359
+ 重新验证。因此内容有变化应更换资源 URL/版本参数,缩短保存时间,或停止会话后删除缓存数据库。
360
+ 仅保存 GET 的完整 200 响应;跳过 Range、升级请求、`no-store`、`private`、`Vary: *`、
361
+ 带 `Set-Cookie` 的响应以及超大资源。默认单项上限 20 MiB、实体总量 512 MiB,超限淘汰最早条目。
362
+ 页面或 Service Worker 自行截获的请求不经过此缓存。
363
+
364
+ HTTP/HTTPS 缓存由 worker 内的本地代理完成,兼容既有全局/单窗口代理;HTTPS 上游仍进行
365
+ 证书校验,临时 CA 只由当前窗口信任,不写入系统钥匙串。支持 macOS 14+ WKWebView 和
366
+ Windows WebView2;其他后端启用时明确报错。浏览器对 localhost/回环地址可能绕过代理,
367
+ 本地站点不保证进入共享缓存。此模式使用代理网络栈,依赖 TLS 指纹或客户端证书的网站可能不兼容。
368
+
369
+ macOS 窗口通过独立 WKWebView 数据存储配置代理,兼容 macOS 14 的 HTTPS 缓存证书验证。Cookie 读取和无痕清理使用该窗口的同一存储;系统代理和钥匙串不变。原生配置接口不可用时会明确报错,不退回直连。
370
+
371
+ 验证命令:`uv run --extra cache python scripts/smoke_storage_cache.py`;缓存与代理切换组合验证:`uv run --extra cache python scripts/smoke_proxy_switch.py --cache`。
372
+
313
373
  ## ⚙️ 常用配置
314
374
 
315
375
  | 参数 | 默认值 | 说明 |
@@ -342,7 +402,7 @@ Cookie 快照和运行信息文件都应按敏感数据处理,不应提交到
342
402
 
343
403
  ## 📐 设计边界
344
404
 
345
- - 无痕隔离依靠“一会话一进程”和 `private_mode=True`。
405
+ - 默认无痕隔离依靠“一会话一进程”和 `private_mode=True`;可在创建请求中关闭无痕。
346
406
  - 所有 worker 接口只监听随机本机端口,并使用独立内部令牌。
347
407
  - 控制器重启不会恢复仍在运行的 worker 会话。
348
408
  - DOM `click()` 不等同于操作系统级鼠标事件。
@@ -30,7 +30,8 @@ Manage hidden browser sessions, inspect the DOM, execute JavaScript, and observe
30
30
  | Page interaction | Navigate, query the DOM, enter text, click elements, and execute JavaScript |
31
31
  | Observability | Long-poll DOM events, DOM mutations, and page-level network activity |
32
32
  | Proxy debugging | Apply a global or per-window HTTP(S) proxy and resolve its exit IP and location asynchronously |
33
- | Cookie snapshots | Save cookies and make a best-effort restore in a new session |
33
+ | Login snapshots | Save cookies and current-origin localStorage for new sessions |
34
+ | Resource cache | Optional persistent JS/CSS cache with extension allowlists |
34
35
  | Cross-platform | Windows, macOS, and Linux with a GTK or Qt backend |
35
36
 
36
37
  ## 🧱 Architecture
@@ -320,12 +321,20 @@ into Service Workers, cache hits, extension traffic, or every response body.
320
321
  For protocol-level debugging, set `remote_debugging_port` when creating a
321
322
  session and use a DevTools protocol supported by the selected backend.
322
323
 
323
- ## 🍪 Cookie snapshots
324
+ ## 🍪 Login snapshots (cookies + localStorage)
324
325
 
325
326
  Cookie snapshots are stored in the per-user data directory by default; use
326
327
  `--data-dir` to choose another location. Pass a `snapshot_id` when creating a
327
328
  new session to attempt a restore. Explicit `cookies` in the request override
328
- snapshot cookies with the same name, domain, and path.
329
+ snapshot cookies with the same name, domain, and path. The `/cookie-snapshots` routes
330
+ remain compatible. New snapshots include `schema_version: 2` and `local_storage`, an
331
+ origin-to-string-map dictionary. All keys are preserved, including Unicode, empty
332
+ values, special names, and stores with more than 500 keys.
333
+
334
+ On WKWebView and WebView2, a native document-start script replaces localStorage
335
+ before website scripts run, once per matching origin in that session. Subsequent
336
+ navigation does not overwrite new values, and unrelated origins receive no data.
337
+ Older cookie-only snapshots still load.
329
338
 
330
339
  Restoration is subject to browser backend limitations:
331
340
 
@@ -334,11 +343,62 @@ Restoration is subject to browser backend limitations:
334
343
  restore HttpOnly cookies.
335
344
  - Domain, SameSite, Secure, expiry, and browser policies may reject individual
336
345
  cookies.
337
- - Snapshots do not contain IndexedDB, Local Storage, Service Workers, or cache.
346
+ - localStorage covers only the current top-level origin at snapshot time, excluding
347
+ other origins, cross-origin frames, sessionStorage, IndexedDB, and Service Workers.
348
+ - Resource cache is stored independently and is not part of a login snapshot.
338
349
 
339
350
  Treat cookie snapshots and runtime files as sensitive data and never commit
340
351
  them to version control.
341
352
 
353
+ ## 📦 Persistent resource cache
354
+
355
+ Install `pip install 'agent-webview[cache]'` with Python 3.12+ (base functionality
356
+ still supports 3.10+), or `uv sync --extra dev --extra cache` from source. Create a session:
357
+
358
+ ```json
359
+ {
360
+ "url": "https://example.com/",
361
+ "private_mode": true,
362
+ "resource_cache": {
363
+ "enabled": true,
364
+ "extensions": [".js", ".css"],
365
+ "max_age_seconds": 604800,
366
+ "max_resource_bytes": 20971520,
367
+ "max_total_bytes": 536870912
368
+ }
369
+ }
370
+ ```
371
+
372
+ Caching is disabled by default. Both private and non-private sessions support it;
373
+ `private_mode` defaults to `true`. API sessions still use separate processes. Shared resources survive workers and controller restarts in
374
+ `<data-dir>/resource-cache/resources.sqlite3`.
375
+
376
+ Cache hits bypass the network; misses are fetched and saved. Full URLs (including
377
+ query, scheme and port) and Vary-selected request headers form the key. Credentials,
378
+ Origin and content encoding negotiation are always separated; unrelated headers such
379
+ as Referer do not prevent reuse unless named in Vary. CDN resources use their own domains. Only path extensions
380
+ `.js` and `.css` are enabled by default. Supply a complete allowlist to include
381
+ `.mjs`, `.svg`, `.png` or `.html`; extension matching ignores query strings and case.
382
+
383
+ This opt-in cache-first policy reuses entries for `max_age_seconds` without server
384
+ max-age revalidation. Change versioned URLs, shorten the retention period, or stop
385
+ sessions and delete the database to refresh. Only complete GET/200 responses qualify.
386
+ Range requests, upgrades, `no-store`, `private`, `Vary: *`, `Set-Cookie`, and oversized
387
+ responses are excluded. Defaults are 20 MiB per resource and 512 MiB total entity
388
+ bytes; oldest entries are evicted when full. Requests intercepted by a page or
389
+ Service Worker do not reach this cache.
390
+
391
+ A worker-local proxy supports HTTP/HTTPS and existing upstream proxies. Upstream TLS
392
+ certificates are still verified; only the current window trusts the temporary CA,
393
+ without changes to system trust. Supported backends: macOS 14+ WKWebView and Windows
394
+ WebView2. Other backends fail explicitly. Browsers may bypass proxies for loopback
395
+ addresses, so localhost caching is not guaranteed. Sites depending on TLS fingerprints
396
+ or client certificates may be incompatible with this proxy mode.
397
+
398
+ macOS proxy windows use a dedicated WKWebView data store, including HTTPS resource caching on macOS 14. Cookie access and private-mode cleanup use the same store as the window. System proxy settings and the keychain remain unchanged. Unsupported native proxy configuration fails explicitly without a direct fallback. Run `uv run --extra cache python scripts/smoke_proxy_switch.py --cache` to verify authenticated proxy switching with caching enabled.
399
+
400
+ Run `uv run --extra cache python scripts/smoke_storage_cache.py` for native smoke checks.
401
+
342
402
  ## ⚙️ Configuration
343
403
 
344
404
  | Option | Default | Description |
@@ -0,0 +1,48 @@
1
+ # 安全策略
2
+
3
+ ## 支持范围
4
+
5
+ 当前仅维护最新的 `0.1.x` 版本。安全修复不会回溯到更早的开发快照。
6
+
7
+ ## 报告方式
8
+
9
+ 请通过 GitHub 仓库的 Private vulnerability reporting 或 Security Advisory 私下报告。
10
+ 不要在公开 Issue 中附带 Cookie、Token、运行信息文件、HAR、请求日志或可复现账号。
11
+
12
+ 报告应包含受影响版本、平台、最小复现步骤和影响范围。确认问题后会尽快给出处理
13
+ 状态;公开披露时间由报告者和维护者协商。
14
+
15
+ ## 本地安全边界
16
+
17
+ 本工具允许执行任意页面 JavaScript 并读取浏览器 Cookie,只适合在可信本机使用。
18
+ 不要直接暴露到不可信网络,也不要共享运行信息文件或 Cookie 快照。
19
+
20
+ 代理会话会把出口 IP 发送给内置的第三方归属地查询服务。全局代理地址会记录在权限
21
+ 受限的运行信息文件中;不要共享该文件。
22
+
23
+ 单窗口代理账密通过受令牌保护的 API 传入,创建时保存在权限受限的 worker 配置中;
24
+ 后续切换账密只保留在进程内存,不进入状态响应或代理事件。窗口使用随机本机端口
25
+ 转发到上游,端口不面向外部网络;本机其他进程仍属于可信边界。HTTP Basic 仅编码
26
+ 认证数据;需要保护到上游的传输时应使用 `https://` 代理,组件会验证其 TLS 证书。
27
+
28
+ ## 可选缓存依赖的已核查告警
29
+
30
+ 核查日期:2026-11-14。`cache` extra 的 mitmproxy 12.3.1 将 Tornado 限定为
31
+ `>=6.5.0,<=6.5.10`,目前不能直接安装已经修复的 Tornado 6.6+。
32
+ 基础安装 `pip install agent-webview` 不引入该依赖。
33
+
34
+ 锁定的 Tornado 6.5.10 有以下已知告警:
35
+
36
+ - [CVE-2026-116577](https://github.com/tornadoweb/tornado/security/advisories/GHSA-pcg2-g6cj-q92c):Tornado HTTP 头解析的 CPU 消耗。
37
+ - [CVE-2026-115927](https://github.com/tornadoweb/tornado/security/advisories/GHSA-r4j5-9xpp-3985):Tornado 分块请求体解析的 CPU/内存消耗。
38
+ - [CVE-2026-116578](https://github.com/tornadoweb/tornado/security/advisories/GHSA-pw9p-v7r6-gx4p):Tornado RedirectHandler 的开放重定向。
39
+ - [CVE-2026-126347](https://github.com/advisories/GHSA-5cjw-f85j-cv6r):RedirectHandler 对三个及以上斜线开头路径的开放重定向,是上述修复的遗漏分支;修复版本为 6.6.1。本组件不加载该处理器,沿用下述隔离验证。
40
+
41
+ 本组件使用 `mitmproxy.tools.dump.DumpMaster`,通过 mitmproxy 自身的代理协议栈处理
42
+ HTTP/HTTPS,不加载 Tornado,也不启动 mitmweb 或 Tornado HTTP 服务;内置 onboarding
43
+ 页面亦明确关闭。`tests/test_cache_proxy.py` 在隔离子进程中禁止导入 Tornado,再验证
44
+ 实际缓存请求,防止升级依赖时无意改变这一边界。因此这些告警不涉及本组件当前运行路径。
45
+ 发布检查仅对上述精确包名、版本、告警编号记录例外,其他发现仍阻止发布。
46
+
47
+ 这不表示 Tornado 6.5.10 本身已修复。不要在同一依赖环境中用该版本启动 Tornado 服务
48
+ 或 mitmweb;需要这些功能的程序应使用独立环境。上游解除版本限制后应升级并移除此例外。
@@ -50,6 +50,7 @@ Documentation = "https://github.com/Yuv96/agent-webview#readme"
50
50
  Security = "https://github.com/Yuv96/agent-webview/security/policy"
51
51
 
52
52
  [project.optional-dependencies]
53
+ cache = ["mitmproxy>=12.3.1,<13; python_version >= '3.12'"]
53
54
  dev = [
54
55
  "detect-secrets>=1.5,<2",
55
56
  "httpx2>=2,<3",
@@ -94,3 +95,7 @@ files = ["src/agent_webview"]
94
95
  ignore_missing_imports = true
95
96
  check_untyped_defs = true
96
97
  warn_unused_ignores = true
98
+
99
+ [[tool.mypy.overrides]]
100
+ module = ["mitmproxy.*"]
101
+ follow_imports = "skip"
@@ -42,9 +42,9 @@ REQUIRED_WHEEL_FILES = {
42
42
  }
43
43
 
44
44
 
45
- def run(command: list[str], *, cwd: Path = ROOT) -> None:
45
+ def run(command: list[str], *, cwd: Path = ROOT, env: dict[str, str] | None = None) -> None:
46
46
  print(f"执行:{' '.join(command)}", flush=True)
47
- subprocess.run(command, cwd=cwd, check=True)
47
+ subprocess.run(command, cwd=cwd, check=True, env=env)
48
48
 
49
49
 
50
50
  def project_version() -> str:
@@ -94,6 +94,8 @@ def check_secrets() -> None:
94
94
  "run",
95
95
  "--extra",
96
96
  "dev",
97
+ "--extra",
98
+ "cache",
97
99
  "detect-secrets",
98
100
  "scan",
99
101
  *files,
@@ -111,6 +113,39 @@ def check_secrets() -> None:
111
113
  raise RuntimeError(f"敏感信息扫描未通过:{summary}")
112
114
 
113
115
 
116
+ def audit_requirements(requirements: Path) -> None:
117
+ # 仅允许已核查的精确包/版本/告警;依据及适用边界见 SECURITY.md。
118
+ exceptions = {
119
+ ("tornado", "6.5.10", "CVE-2026-116577"),
120
+ ("tornado", "6.5.10", "CVE-2026-115927"),
121
+ ("tornado", "6.5.10", "CVE-2026-116578"),
122
+ ("tornado", "6.5.10", "CVE-2026-126347"),
123
+ }
124
+ command = ["uv", "run", "--extra", "dev", "--extra", "cache", "pip-audit",
125
+ "--requirement", str(requirements), "--format", "json"]
126
+ print("执行:依赖审计(含 cache extra)", flush=True)
127
+ result = subprocess.run(command, cwd=ROOT, capture_output=True, text=True)
128
+ if result.returncode not in {0, 1}:
129
+ raise RuntimeError("依赖审计执行失败")
130
+ try:
131
+ report = json.loads(result.stdout)
132
+ except ValueError as error:
133
+ raise RuntimeError("依赖审计未返回有效报告") from error
134
+ rejected = []
135
+ accepted = []
136
+ for dependency in report["dependencies"]:
137
+ for vulnerability in dependency.get("vulns", []):
138
+ finding = (dependency["name"], dependency["version"], vulnerability["id"])
139
+ (accepted if finding in exceptions else rejected).append(finding)
140
+ if rejected:
141
+ raise RuntimeError(f"依赖存在未豁免的已知漏洞:{rejected}")
142
+ if result.returncode == 1 and not accepted:
143
+ raise RuntimeError("依赖审计失败且没有可解释的已核查告警")
144
+ for name, version, advisory in accepted:
145
+ print(f"已核查的不适用告警:{name} {version} {advisory};依据见 SECURITY.md")
146
+ print("依赖审计通过(无未核查告警)")
147
+
148
+
114
149
  def archive_names(path: Path) -> list[str]:
115
150
  if path.suffix == ".whl":
116
151
  with zipfile.ZipFile(path) as archive:
@@ -173,6 +208,8 @@ def check_artifacts(artifacts: list[Path], root_text: str) -> None:
173
208
 
174
209
 
175
210
  def clean_install_smoke(wheel: Path, temporary: Path, version: str) -> None:
211
+ clean_environment = os.environ.copy()
212
+ clean_environment.pop("PYTHONPATH", None)
176
213
  environment = temporary / "venv"
177
214
  run(["uv", "venv", str(environment), "--python", ">=3.10"])
178
215
  python = (
@@ -191,11 +228,13 @@ def clean_install_smoke(wheel: Path, temporary: Path, version: str) -> None:
191
228
  ),
192
229
  ],
193
230
  cwd=temporary,
231
+ env=clean_environment,
194
232
  )
195
- run([str(python), "-m", "agent_webview", "--help"], cwd=temporary)
233
+ run([str(python), "-m", "agent_webview", "--help"], cwd=temporary, env=clean_environment)
196
234
  run(
197
235
  [str(python), "-m", "agent_webview", "--print-runtime-file"],
198
236
  cwd=temporary,
237
+ env=clean_environment,
199
238
  )
200
239
 
201
240
 
@@ -217,14 +256,16 @@ def main() -> None:
217
256
  version = project_version()
218
257
  check_tag(version)
219
258
  check_secrets()
220
- run(["uv", "run", "--extra", "dev", "ruff", "check", "src", "tests", "scripts"])
221
- run(["uv", "run", "--extra", "dev", "mypy"])
259
+ run(["uv", "run", "--extra", "dev", "--extra", "cache", "ruff", "check", "src", "tests", "scripts"])
260
+ run(["uv", "run", "--extra", "dev", "--extra", "cache", "mypy"])
222
261
  run(
223
262
  [
224
263
  "uv",
225
264
  "run",
226
265
  "--extra",
227
266
  "dev",
267
+ "--extra",
268
+ "cache",
228
269
  "pytest",
229
270
  "--cov=agent_webview",
230
271
  "--cov-report=term",
@@ -243,6 +284,8 @@ def main() -> None:
243
284
  "--quiet",
244
285
  "--locked",
245
286
  "--no-dev",
287
+ "--extra",
288
+ "cache",
246
289
  "--no-emit-project",
247
290
  "--no-hashes",
248
291
  "--format",
@@ -251,24 +294,14 @@ def main() -> None:
251
294
  str(requirements),
252
295
  ]
253
296
  )
254
- run(
255
- [
256
- "uv",
257
- "run",
258
- "--extra",
259
- "dev",
260
- "pip-audit",
261
- "--requirement",
262
- str(requirements),
263
- ]
264
- )
297
+ audit_requirements(requirements)
265
298
  run(["uv", "build", "--out-dir", str(distribution)])
266
299
  artifacts = sorted(
267
300
  path
268
301
  for path in distribution.iterdir()
269
302
  if path.suffix == ".whl" or path.name.endswith(".tar.gz")
270
303
  )
271
- run(["uv", "run", "--extra", "dev", "twine", "check", *map(str, artifacts)])
304
+ run(["uv", "run", "--extra", "dev", "--extra", "cache", "twine", "check", *map(str, artifacts)])
272
305
  check_artifacts(artifacts, str(ROOT))
273
306
  wheel = next(path for path in artifacts if path.suffix == ".whl")
274
307
  clean_install_smoke(wheel, temporary, version)
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env python3
2
2
  from __future__ import annotations
3
3
 
4
+ import argparse
4
5
  import base64
5
6
  import json
6
7
  import os
@@ -76,6 +77,9 @@ def test_proxy(label: str):
76
77
 
77
78
 
78
79
  def main():
80
+ parser = argparse.ArgumentParser(description="验证原生窗口代理切换")
81
+ parser.add_argument("--cache", action="store_true", help="同时启用资源缓存")
82
+ args = parser.parse_args()
79
83
  with (
80
84
  tempfile.TemporaryDirectory(prefix="webview-proxy-smoke-") as name,
81
85
  test_proxy("first") as (first, first_requests),
@@ -120,6 +124,7 @@ def main():
120
124
  json={
121
125
  "url": "http://proxy-switch.invalid/",
122
126
  "visible": False,
127
+ "resource_cache": {"enabled": args.cache},
123
128
  "proxy": first,
124
129
  "proxy_username": "test",
125
130
  "proxy_password": "first", # pragma: allowlist secret