VTEX IO 应用安全边界审查：判断路由…

在审查或设计 VTEX IO 应用的安全敏感边界时，判断哪些数据和输入可以安全跨越应用边界，并防止跨账户、跨工作区、跨用户或跨集成的数据泄露。

适用场景

解决思路

1. 把每个 public 路由都视为显式的信任边界。
2. 在 `service.json` 中，将路由从 `public: false` 改为 `public: true` 属于边界变更，应触发显式的安全审查。
3. 对必须从 VTEX IO 外部调用的路由（如合作伙伴 webhook 或外部消费的集成端点）使用 `public: true`，并将其视为暴露在互联网上的边界。
4. 对仅供 VTEX 内部流程或其他 IO 应用使用的路由使用 `public: false`，但不要将其视为隐式安全，它们仍需验证和受限假设。
5. `service.json` 中 `public: true` 的路由只要账户域名可访问就能从外部访问，不要依赖晦涩路径或看似内部的 URL 作为安全措施。
6. 尽早验证外部输入，确保其在到达领域逻辑或下游集成之前已被校验。
7. 对 webhook 风格的路由，在调用下游客户端之前同时验证结构和真实性，例如通过必填字段加上共享密钥或签名头。
8. 不要因为请求来自另一个 VTEX 服务或看似内部的路径就假定其安全。
9. 当服务读取或写入有作用域的数据时，保持账户、工作区和用户上下文显式。
10. 当数据或行为必须限制在特定工作区时，显式检查 `ctx.vtex.workspace` 并拒绝来自其他工作区的调用。
11. 绝不暴露超出调用方所需的数据，要有意塑造响应，而不是返回原始的下游 payload。
12. 将密钥、令牌和安全敏感头排除在日志和路由响应之外。
13. 不要在生产路由或服务中使用 `console.log` 或 `console.error`，应使用 `ctx.vtex.logger` 以结构化对象记录应用日志，仅在应用有意将日志转发到合作伙伴拥有的系统时才使用专门的外部日志客户端。
14. 避免暴露返回内部配置、密钥或完整下游 payload 的调试或诊断路由；如果此类路由确实必要，保持其非公开并限制为最小、非敏感信息。
15. 用本技能决定什么可以跨越边界，用 `vtex-io-auth-and-policies` 决定该边界如何被授权和保护。
16. 对任何暴露在严格控制内部边界之外的路由，在调用领域逻辑或下游客户端之前必须验证传入数据。
17. 如果 public 路由将 body 字段、参数或头直接转发到业务逻辑或客户端调用而未验证，立即停止并先添加验证。
18. 路由和集成不得泄露令牌、内部头、原始下游 payload 或属于其他账户、工作区或用户上下文的数据。
19. 如果路由返回原始下游响应、记录密钥或在没有显式过滤的情况下混合上下文，立即停止并在继续之前收窄输出。
20. 当一个服务调用另一个服务时，接收边界仍必须被视为真实的安全边界，并进行显式验证和受限假设。
21. 如果服务接受来自另一个服务的数据而未验证格式、作用域或账户/工作区上下文，立即停止并使这些检查显式化。
22. 安全审查应从边界开始：谁能调用此路由或触发此集成？什么数据进入系统？什么必须立即验证？什么数据离开系统？账户、工作区或用户上下文是否会跨越边界泄露？
23. 使用最小的请求和响应结构、显式验证以及有作用域的上下文检查来保持边界安全。

适用边界 · 注意事项

• 不适用于 `manifest.json` 中的策略声明语法。
• 不适用于服务运行时规格、日志与可观测性策略、前端浏览器安全问题，或决定哪个 VTEX 认证令牌应调用端点。
• 不用于决定路由或资源访问如何被授权（应使用 `vtex-io-auth-and-policies`），也不用于决定哪个运行时身份应调用 VTEX 端点（应使用 `vtex-io-auth-tokens-and-context`）。