pz-cli 5.0.0__py3-none-any.whl

pz_foundation/docs//345/205/254/345/274/200/345/205/215/350/264/271/346/216/245/345/217/243/351/230/262/346/273/245/347/224/250/344/270/216/344/272/272/346/234/272/346/240/241/351/252/214.md

@@ -0,0 +1,680 @@
+# 公开免费接口防滥用与人机校验
+
+## 背景
+
+很多产品都会提供匿名免费试用、公开诊断、公开生成、公开提交等入口。这类入口有两个共同特点：
+
+- 用户不一定登录，不能直接依赖 auth owner 做身份拦截。
+- 后端动作有真实成本，可能调用 LLM、搜索、邮件、短信、爬取、导出或第三方 API。
+
+因此，“让用户只能在现有网页上交互”不能理解为浏览器来源检查。`Origin`、`Referer`、CORS、User-Agent 都可以被脚本绕过或缺失，只能作为辅助信号。正式方案必须由源站验证一组服务端可判定的凭据：
+
+- 同源 unsafe request 约束。
+- SSR 页面签发的短时 action token。
+- 人机验证 provider 的服务端校验。
+- action 级限流、去重、成本预算与可观测审计。
+
+该能力属于 `pz_foundation` 的通用 HTTP / middleware / security 能力，不属于某个业务 app 私有实现。
+
+## 定位
+
+建议命名为 `Public Action Gate`。
+
+`Public Action Gate` 负责保护匿名或半匿名公开动作，例如：
+
+- 免费诊断提交。
+- 联系表单。
+- 邮件订阅。
+- 一次性 AI 生成 / 分析。
+- 未登录 checkout 前置动作。
+
+它不负责：
+
+- 登录态认证、用户 session、角色权限；这些仍由 auth owner 负责。
+- 订阅、付费、业务额度和套餐权益；这些由业务 owner 负责。
+- 判断业务请求是否“应该成功”；foundation 只输出通用 gate verdict。
+- 替代 Cloudflare WAF、Bot Management 或平台侧 rate limit；边缘层只能作为第一道防线，源站仍必须验证。
+
+## 正式目标
+
+1. 公开高成本接口默认不能被裸 API 调用直接消费。
+2. 业务页面仍是交互入口；页面首屏由业务 app SSR，foundation 只提供可复用 token、校验和中间件能力。
+3. 所有高成本公开动作都必须有稳定 `action_id`，进入可审计 manifest。
+4. 人机验证必须服务端校验，不能只在页面上渲染 widget。
+5. 限流和配额以 action 为粒度，不把所有公开 API 混成一类。
+6. secret 只进入 `configs/default.env` / 项目 env layer，不写入 JSONC、模板、页面或日志。
+
+## 现有分散点
+
+当前仓库里已经有一批相近能力，但职责分散在不同子包和中间件里：
+
+- `pz_foundation.middlewares.rate_limited.KeyLimiter`
+  - 已经提供 Redis + 进程内 fallback 的 key window 限制能力。
+  - 目前只是底层计数器，不知道 action、客户端身份、payload hash、human verification 或 fail-open / fail-closed policy。
+- `pz_foundation.middlewares.security_csrf.SecurityCSRFMiddleware`
+  - 已经提供 double-submit CSRF 校验。
+  - 目前只按 path prefix 工作，不理解 public action manifest。
+- `pz_api_access.middlewares.rate_limited`
+  - 已有 path / method / pre_auth / post_auth 规则、IP burst / daily limit、规则快照缓存。
+  - 目前 IP 解析、规则匹配、KeyLimiter 构造和响应语义都在 middleware 内部。
+- `pz_api_access.middlewares.risk_control`
+  - 已有 `ip`、`email`、`ip_email`、`token` 等风险 key 维度。
+  - 目前 body 解析、key 归一化、规则命中和 limiter 编排都在 middleware 内部。
+- `pz_api_access.deps.require_api_token`
+  - 已有 PAT 级本地限流和 Redis 限流。
+  - 这是外部 API token 访问控制，不应被 public action gate 接管，但可以复用统一 limiter / client identity 对象。
+- `pz_page_center.review_state`
+  - 有 review quota、Redis reserve、local fallback 和 override。
+  - 这是 Page Center 自己的治理额度，不属于通用公开动作防滥用，但其中的 reserve store 语义可以作为 foundation quota counter 的参考。
+- `pz_site_media.services.enforce`
+  - 有媒体存储业务 quota。
+  - 这是业务/套餐额度，不应迁入 foundation；foundation 只能提供请求保护 verdict，media 继续拥有存储额度真相。
+- `showinai/docs/公开工具设计.md`
+  - 已经声明 IP + payload + domain + email 维度限流。
+  - 这类匿名公开高成本动作应改为贡献 public action declaration，由 foundation 统一执行通用 gate。
+
+正式收敛方向：
+
+- foundation 拥有通用 HTTP request protection primitives。
+- `pz_api_access` 继续拥有外部 API token / PAT 生命周期和外部 API 权限。
+- `pz_auth` 继续拥有登录态认证、session control 和 route policy。
+- 业务子包继续拥有套餐、积分、存储、报告、provider 成本等业务额度。
+- 业务子包不再复制 IP 解析、Turnstile 校验、action token、通用 nonce 和通用 rate limit 编排。
+
+## 核心结论
+
+公开免费接口的最小防护链路为：
+
+```text
+GET public page
+  -> SSR 输出表单、csrf cookie、public_action_token、human verification site key
+
+POST public action API
+  -> route owner / canonical middleware
+  -> CORS / same-origin / CSRF check
+  -> PublicActionGate 校验 action token
+  -> PublicActionGate 服务端校验 human verification token
+  -> PublicActionGate 检查 action rate limit / budget / replay
+  -> business handler
+  -> business service
+```
+
+其中 `public_action_token` 和人机验证 token 是两类不同凭据：
+
+- `public_action_token` 证明请求来自 foundation 最近签发过的页面交互上下文。
+- 人机验证 token 证明本次提交通过了外部 provider 的挑战校验。
+
+两者都必须通过服务端验证。只做其中一个都不完整。
+
+## 面向对象统一模型
+
+Public Action Gate 不应实现成一个巨大 middleware，也不应继续把规则解析、IP 解析、token 签发、limiter、Turnstile adapter、日志和业务判断散落到 handler 里。
+
+按 `pz` 面向对象规范，建议拆成以下对象：
+
+```text
+PublicActionProtectionSpec            # 声明期：业务 app 贡献 action 保护声明
+PublicActionProtectionManifest        # 编译期：RuntimePlan 内不可变保护清单
+PublicActionGateSettingsSnapshot      # 编译期：foundation settings 投影
+
+PublicActionGateRuntime               # runtime owner / 组合根
+  -> PublicActionGateFacade           # 对业务页面和中间件暴露的窄公开面
+  -> ClientIdentityResolver           # 解析可信 IP、国家、session、用户、header facts
+  -> ActionTokenSigner                # 内存运行时 signer，负责签发/验签 action token
+  -> ActionNonceStore                 # 一次性 nonce consume / replay 防护
+  -> HumanVerificationProvider        # Turnstile 等 provider 协议
+  -> RateLimitEvaluator               # action 级限流编排
+      -> RateLimitKeyBuilder          # ip / session / payload / email / domain key 归一化
+      -> CounterStore                 # Redis / local fallback / future durable store
+  -> BudgetEvaluator                  # 通用项目级 provider budget，可选
+  -> PublicActionAuditSink            # 安全日志与指标
+```
+
+### 声明期对象
+
+`PublicActionProtectionSpec` 由业务 app 贡献，描述“哪个业务动作需要哪些 gate”，不直接保存运行状态：
+
+```text
+action_id
+owner_app
+route_name / route_namespace
+methods
+required_gates
+payload_hash_fields
+rate_limit_policy_ids
+human_verification_action
+fail_closed
+```
+
+要求：
+
+- `action_id` 稳定、全局唯一，例如 `showinai.public_geo_run`。
+- path projection 从 route manifest 解析，不长期以 settings path 字符串作为唯一真相。
+- payload hash 字段必须由业务 owner 显式声明；foundation 不猜字段。
+
+### 编译对象
+
+`PublicActionProtectionCompiler` 负责把业务贡献、route manifest 和 foundation settings 编译为 `PublicActionProtectionManifest`。
+
+要求：
+
+- 在 RuntimePlan 编译期完成冲突检查。
+- 检查 action 是否指向存在的 route。
+- 检查 high-cost action 是否声明了 `public_action_token`、`human_verification` 和至少一个限流策略。
+- 检查 secret 缺失时 product 环境 fail-fast；develop / test 可使用显式 disabled 或 test provider。
+- 输出不可变 manifest；Web 执行阶段只消费 manifest。
+
+### Runtime Owner
+
+`PublicActionGateRuntime` 是唯一 runtime owner。
+
+职责：
+
+- 从 `PublicActionProtectionManifest` 与 `PublicActionGateSettingsSnapshot` 构造对象图。
+- 在内存中持有 `ActionTokenSigner`、provider adapter、counter store、nonce store 和 audit sink。
+- 对外暴露 `PublicActionGateFacade`。
+- 统一生命周期，后续如果 provider client 或 store 需要关闭，由 runtime owner 对称释放。
+
+不允许：
+
+- handler 内临时创建 Turnstile client。
+- handler 内临时读取 env secret。
+- 业务 app 自己 new `KeyLimiter` 保护 public action。
+- action token signer 作为模块级全局函数散落在业务模块。
+
+### Runtime Signer
+
+把 token 生成函数放在服务端内存中是合理的，但正式对象应是 `ActionTokenSigner`，而不是匿名函数。
+
+语义：
+
+- 启动或 runtime activate 时，由 foundation 根据 settings/env secret 构造 signer。
+- 请求期通过 `PublicActionGateFacade.issue_action_token(...)` 使用 signer。
+- signer 持有密钥派生结果、算法版本、默认 TTL 和 clock 依赖。
+- signer 不读取 settings、不访问 request、不做业务判断。
+
+收益：
+
+- 请求热路径不重复解析 settings/env。
+- 业务 app 不接触签名 secret。
+- token 算法和版本可替换、可测试。
+- 符合 RuntimePlan “编译先于运行”的对象图。
+
+边界：
+
+- signer 只能在服务端内存中。
+- 浏览器端不能生成可信 action token。
+- signer 缓存不是安全边界；安全边界仍是服务端 secret、短 TTL、nonce 单次消费和 gate 校验。
+
+### Client Identity Resolver
+
+IP 限制必须统一先解决“可信客户端身份”问题。
+
+`ClientIdentityResolver` 负责输出结构化 `ClientIdentity`：
+
+```text
+client_ip
+client_ip_source
+country
+ray_id
+user_agent_hash
+origin
+referer
+anonymous_session_hash
+authenticated_user_id
+is_trusted_proxy_chain
+```
+
+规则：
+
+- 只在请求来自可信代理时消费 `CF-Connecting-IP`、`X-Forwarded-For`、`X-Real-IP`。
+- Cloudflare 部署下优先读取 `CF-Connecting-IP`，并记录 `CF-Ray` 用于审计。
+- 未确认可信代理时只使用 ASGI client host。
+- IP 原文默认不进入业务日志；审计日志可记录 hash 和来源。
+- 业务 app 不再自己解析 `x-forwarded-for`。
+
+### Rate Limit Evaluator
+
+`RateLimitEvaluator` 统一消费 action policy 和 `ClientIdentity`，输出 `RateLimitVerdict`。
+
+支持维度：
+
+- `ip`
+- `anonymous_session`
+- `authenticated_user`
+- `payload_hash`
+- `email_hash`
+- `domain_hash`
+- `ip_payload_hash`
+- `ip_email_hash`
+- `country`
+- `global_action`
+
+要求：
+
+- key 构造由 `RateLimitKeyBuilder` 负责，字段归一化和 hash 策略可测试。
+- 计数器由 `CounterStore` 负责，首版可复用现有 `KeyLimiter`。
+- Redis 不可用时如何处理由 action policy 决定：
+  - 高成本 public action 默认 fail-closed 或进入极低本地 fallback limit。
+  - 低成本 action 可以显式 fail-open。
+- verdict 必须包含 `allowed`、`retry_after_seconds`、`policy_id`、`dimension`、`store_status`。
+
+### Facade
+
+`PublicActionGateFacade` 是业务 app 唯一稳定消费面：
+
+```text
+issue_action_token(action_id, request_context) -> IssuedPublicActionToken
+verify_request(action_id, request) -> PublicActionGateVerdict
+build_template_context(action_id, request_context) -> PublicActionTemplateContext
+```
+
+业务页面使用 `build_template_context(...)` 输出 site key、action token 和字段名。
+
+业务 API handler 可以选择两种集成方式：
+
+- 通过 foundation middleware 在进入 handler 前 fail-fast。
+- 通过 dependency/facade 显式调用 `verify_request(...)` 并接收 verdict。
+
+同一 action 只能选一种正式执行路径，避免 middleware 和 handler 双重扣次数。
+
+## Action Token
+
+### 语义
+
+`public_action_token` 是 foundation 签发的短时、单用途、可绑定上下文的 action 凭据。
+
+建议字段：
+
+- `version`
+- `action_id`
+- `owner_app`
+- `method`
+- `path`
+- `issued_at`
+- `expires_at`
+- `nonce`
+- `anonymous_session_id` 或登录态 `user_id` 的不可逆摘要
+- `payload_policy_id`
+- `signature`
+
+要求：
+
+- token 由 foundation 使用 HMAC 或同等强度签名，不允许业务 app 自己拼接。
+- 默认有效期不超过 10 分钟；高成本动作建议 2-5 分钟。
+- nonce 必须一次性消费；重复提交返回 `action_token_replayed`。
+- token 不包含 email、关键词、domain、prompt、URL 等业务明文。
+- token 可以绑定 `method + path + action_id`，避免被挪用到其它接口。
+- token 可以绑定匿名 session cookie，但不能把 cookie 当成身份认证。
+
+### 签发入口
+
+业务页面在 SSR 时通过 foundation facade 请求签发：
+
+```text
+foundation.public_action_gate.issue_token(action_id, request_context)
+```
+
+模板只拿到：
+
+- public action token
+- csrf token / cookie
+- human verification site key
+- action id
+
+业务 app 不接触签名 secret。
+
+## 人机验证 Provider
+
+### Provider 抽象
+
+foundation 应定义 provider-neutral contract：
+
+```text
+HumanVerificationProvider.verify(
+  provider_token,
+  remote_ip,
+  expected_action,
+  expected_hostname,
+  idempotency_key,
+) -> HumanVerificationVerdict
+```
+
+首个正式实现建议为 `cloudflare_turnstile`。
+
+正式 verdict 至少包含：
+
+- `success`
+- `provider`
+- `hostname`
+- `action`
+- `challenge_ts`
+- `error_codes`
+- `score` 或 provider 扩展字段
+- `raw_metadata_ref`
+
+`raw_metadata_ref` 指向内部日志或原始响应引用，不进入公开响应。
+
+### Cloudflare Turnstile
+
+Cloudflare Turnstile 的正式集成要求：
+
+- 页面只渲染 site key；secret key 只能在服务端使用。
+- 提交接口接收 `cf-turnstile-response` 或 foundation 统一字段名。
+- 源站必须调用 Cloudflare Siteverify API 完成校验。
+- token 过期或重复使用时必须拒绝本次业务动作。
+- 校验时应传 `remoteip`；可传 `idempotency_key` 支持安全重试。
+- 必须校验返回的 `hostname` 与当前公开域名匹配。
+- 如果启用了 action 绑定，必须校验返回的 `action` 与 `action_id` 或 provider action 映射一致。
+
+Cloudflare 官方文档说明 Turnstile token 需要服务端验证，并且 token 是短时、单次使用的。当前官方 Siteverify 端点为：
+
+```text
+POST https://challenges.cloudflare.com/turnstile/v0/siteverify
+```
+
+参考：
+
+- https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
+
+### 失败策略
+
+高成本公开动作必须 fail-closed：
+
+- provider token 缺失：`human_verification_required`
+- provider token 无效：`human_verification_failed`
+- provider 超时：`human_verification_unavailable`
+- hostname / action 不匹配：`human_verification_mismatch`
+
+低成本动作可以由 action policy 显式声明降级，但默认不降级。
+
+## 限流与预算
+
+Public Action Gate 必须支持 action 级 rate limit。维度建议：
+
+- `action_id`
+- client IP 或可信代理解析出的真实 IP
+- anonymous session id
+- authenticated user id
+- payload hash
+- email hash
+- domain hash
+- country / region
+
+典型公开免费诊断动作：
+
+```text
+ip + action_id: 10 / day
+anonymous_session + action_id: 5 / day
+payload_hash + action_id: 3 / hour
+domain_hash + action_id: 20 / day
+global action concurrency: 3
+global provider budget: project-defined
+```
+
+要求：
+
+- payload hash 只基于业务 owner 明确声明的字段生成，不由 foundation 猜测。
+- hash 使用归一化后的值；不在日志里输出原始 email、domain、keyword。
+- Redis / cache 可用时使用共享计数器。
+- Redis 不可用时可以使用进程内 fallback 作为短期保护，但高成本 action 不得因为共享限流不可用而无限放行。
+- 超限响应必须包含稳定错误码和可选 `retry_after_seconds`。
+
+## Origin、CORS 与 CSRF
+
+同源检查不是完整安全方案，但仍必须作为基础门槛：
+
+- unsafe methods 默认要求 `Origin` 或可信 `Referer` 与当前 canonical host 匹配。
+- 受 Public Action Gate 保护的接口不得使用 `Access-Control-Allow-Origin: *` 搭配 credentials。
+- 跨域公开 API 必须显式声明为跨域产品能力，并使用独立 action policy。
+- CSRF double-submit cookie 继续由 foundation `security_csrf` 负责；Public Action Gate 不再复制第二套 CSRF。
+- 缺失 `Origin` 的浏览器兼容场景可以回退到 `Referer`，但命中高风险 action 时应要求 action token 与人机验证同时通过。
+
+## 与 Route Manifest 的关系
+
+业务 app 仍通过 `<pkg>.urls` 声明 URL。Public Action Gate 不成为第二套路由真相源。
+
+建议新增一个正式 manifest：
+
+```text
+PublicActionProtectionManifest
+  - action_id
+  - owner_app
+  - methods
+  - route namespace / route name
+  - path projection
+  - required gates
+  - rate limit policy ids
+  - payload hash policy
+```
+
+贡献方式：
+
+- 业务 app 在 route hints 或正式 extension 中声明 action protection。
+- foundation 在 RuntimePlan 编译阶段把这些声明编译为 manifest。
+- Web 执行阶段只消费 manifest，不运行时扫描业务路由。
+
+业务 app 不应在 handler 里临时写：
+
+- 自己调用 Turnstile Siteverify。
+- 自己解析 Cloudflare header。
+- 自己维护匿名 action nonce。
+- 自己维护通用 IP 限流。
+
+如果业务有额外额度或付费规则，应在业务 service 内基于 foundation verdict 之后继续判断。
+
+## Settings 口径
+
+通用配置 owner 为 `pz_foundation`。
+
+建议 settings namespace：
+
+```jsonc
+{
+  "public_action_gate": {
+    "enabled": true,
+    "token_ttl_seconds": 300,
+    "nonce_store": "cache",
+    "fail_closed_on_nonce_store_unavailable": true,
+    "trusted_proxy_headers": [
+      "cf-connecting-ip",
+      "x-forwarded-for"
+    ],
+    "human_verification": {
+      "provider": "cloudflare_turnstile",
+      "site_key": "",
+      "secret_key": "",
+      "siteverify_url": "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+      "timeout_seconds": 3.0,
+      "expected_hostnames": []
+    },
+    "actions": {}
+  }
+}
+```
+
+密钥作者面：
+
+```env
+pz_foundation__public_action_gate__human_verification__secret_key=
+```
+
+`site_key` 可以是非敏感配置；`secret_key` 只能进入 env layer。
+
+业务 action 的阈值可以通过 action id 覆盖：
+
+```jsonc
+{
+  "public_action_gate": {
+    "actions": {
+      "showinai.public_geo_run": {
+        "enabled": true,
+        "require_action_token": true,
+        "require_human_verification": true,
+        "rate_limits": [
+          {
+            "dimension": "ip",
+            "limit": 10,
+            "window_seconds": 86400
+          },
+          {
+            "dimension": "payload_hash",
+            "limit": 3,
+            "window_seconds": 3600
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+注意：path 仍来自 route manifest 或业务 action declaration，不应长期只靠 settings 里的 path 字符串定义保护范围。
+
+## 响应与错误码
+
+Public Action Gate 应输出稳定错误码，业务页面据此刷新 widget、提示重试或引导登录。
+
+推荐错误码：
+
+- `public_action_required`
+- `action_token_missing`
+- `action_token_invalid`
+- `action_token_expired`
+- `action_token_replayed`
+- `csrf_failed`
+- `origin_rejected`
+- `human_verification_required`
+- `human_verification_failed`
+- `human_verification_unavailable`
+- `human_verification_mismatch`
+- `rate_limited`
+- `public_action_budget_exhausted`
+
+HTTP 状态建议：
+
+- `400`：字段缺失或格式错误。
+- `403`：token、CSRF、origin、人机验证失败。
+- `409`：token replay 或 idempotency 冲突。
+- `429`：限流或预算耗尽。
+- `503`：verification provider 或 nonce store 不可用且 action policy 要求 fail-closed。
+
+## 日志与隐私
+
+日志必须包含足够审计信息，但不能泄漏用户输入和 secret。
+
+允许记录：
+
+- `action_id`
+- `owner_app`
+- `verdict`
+- `error_code`
+- `limit_policy_id`
+- IP hash / session hash / payload hash
+- provider 名称
+- provider error code
+- Cloudflare Ray ID 等请求追踪 id
+
+禁止记录：
+
+- Turnstile secret key
+- provider token
+- action token 原文
+- CSRF token
+- email 原文
+- 用户提交的 prompt / keyword 原文
+- session cookie 原文
+
+## Cloudflare 边缘层建议
+
+如果站点部署在 Cloudflare 后面，建议把边缘层当作第一道粗过滤：
+
+- 对公开高成本 API 配置 Cloudflare WAF / Rate Limiting 规则。
+- 对异常国家、ASN、路径、方法做边缘限速或挑战。
+- 使用 Turnstile widget 提供人机验证 token。
+- 只信任来自 Cloudflare 的 `CF-Connecting-IP`、`CF-IPCountry`、`CF-Ray` 等 header；非可信代理来源不得直接消费这些 header。
+
+但正式安全结论仍在源站：
+
+- Cloudflare 边缘规则可能被配置绕过、环境未启用或本地测试不存在。
+- 源站必须独立完成 action token、人机验证服务端校验、限流和业务额度判断。
+
+## showinai 落位示例
+
+`showinai` 的匿名 GEO 诊断应声明为一个 public action：
+
+```text
+action_id = "showinai.public_geo_run"
+owner_app = "showinai"
+method = "POST"
+route = "showinai:public-geo-runs"
+required gates = ["csrf", "public_action_token", "human_verification", "rate_limit"]
+payload_hash_fields = ["seed_keywords", "business_type", "audience_type", "market_language", "intent_templates"]
+```
+
+执行链路：
+
+1. `GET /geo-checker/` SSR 输出表单、Turnstile site key、CSRF cookie、`public_action_token`。
+2. 用户提交到 `POST /api/v1/showinai/public/geo-runs`。
+3. foundation 验证 gate。
+4. `showinai.api` 只接收已通过 gate 的请求。
+5. `showinai.service` 继续判断免费额度、缓存命中、provider 预算和业务输入校验。
+
+这样可以满足“交互只发生在现有网页上”的产品诉求，同时避免把 Cloudflare 校验、nonce、限流和安全日志散落到每个业务 app。
+
+## 实施阶段
+
+### Phase 1：文档与合同
+
+- 新增 `PublicActionProtectionManifest` 设计。
+- 定义 `HumanVerificationProvider` 协议。
+- 定义 action token 签发 / 消费 facade。
+- 定义错误码与日志字段。
+
+### Phase 2：foundation 实现
+
+- 在 `pz_foundation.settings` 增加 `public_action_gate` schema。
+- 在 `configs/default.jsonc` / `configs/default.env` 增加作者面。
+- 增加 `PublicActionGateRuntime` 作为唯一 runtime owner，在 activate 阶段构造 signer、provider、resolver、limiter、nonce store 和 audit sink。
+- 增加 `ClientIdentityResolver`，统一可信代理、Cloudflare header、ASGI client host、匿名 session 和 IP hash 语义。
+- 增加 `ActionTokenSigner`，替代“业务模块里放 token 生成函数”的做法。
+- 增加 `RateLimitEvaluator` / `RateLimitKeyBuilder` / `CounterStore`，首版底层可复用现有 `KeyLimiter`。
+- 增加 Turnstile provider adapter。
+- 增加 nonce store，优先复用 foundation cache capability。
+- 增加 middleware 或 route dependency，在 RuntimePlan 编译后消费 manifest。
+- 增加契约测试覆盖 token 过期、重放、Turnstile 失败、限流、Redis 不可用。
+
+### Phase 3：业务接入
+
+- `showinai` 的公开诊断 action 贡献 action declaration。
+- 页面 SSR 接入 token 签发和 Turnstile site key。
+- API handler 移除私有校验实现，只消费 foundation verdict。
+- 业务 service 保留自己的免费额度、缓存和 provider 成本控制。
+
+### Phase 4：现有实现收敛
+
+- `pz_api_access.middlewares.rate_limited`
+  - 保留 `pz_api_access` 作为外部 API 访问控制 owner。
+  - 迁移 IP 解析、limiter 构造、规则 verdict 到 foundation 的 `ClientIdentityResolver` 与 `RateLimitEvaluator`。
+  - `pz_api_access` 只负责把自己的 path/global rule 编译成访问控制 policy。
+- `pz_api_access.middlewares.risk_control`
+  - 保留 `ip`、`email`、`ip_email`、`token` 这些业务语义。
+  - 迁移 key hash、body field normalization、retry-after verdict 到 foundation key builder。
+- `pz_api_access.deps.require_api_token`
+  - PAT 生命周期和 scope 校验仍归 `pz_api_access`。
+  - per-token limit 改为消费 foundation `RateLimitEvaluator`，避免同时维护 `_LOCAL_PAT_RATE_LIMITS` 和 `KeyLimiter` 两套语义。
+- `pz_page_center.review_state`
+  - review quota / freeze 仍归 Page Center。
+  - 如果需要共享 reserve counter，后续只抽取 `CounterStore.reserve(...)` 能力，不把 Page Center 治理规则迁入 foundation。
+- `pz_site_media.services.enforce`
+  - 存储 quota 仍归 media。
+  - 只在公开上传前置动作需要匿名保护时接入 Public Action Gate；套餐额度不迁移。
+
+## 冻结结论
+
+- Public Action Gate 是 foundation 通用能力。
+- Cloudflare Turnstile 是首个 human verification provider，不是业务 app 私有逻辑。
+- 任何高成本公开免费接口都不能只靠 CORS、Referer 或页面 widget 防护。
+- 服务端必须同时验证 action token、人机验证 token、CSRF / origin 和 action 级限流。
+- 业务 app 只声明自己的 action 与业务预算，不复制通用安全链路。
+- 现有 IP 限制、risk control、PAT limit、review quota 和业务 quota 要按 owner 分层收敛，不能简单合并成一个全局杂物中间件。