vtex-io-security-boundaries

安全边界与暴露面审查

适用场景

当核心问题是 VTEX IO 路由、集成或服务边界是否安全时，使用此技能。

• 审查公开与私有路由的暴露情况
• 验证服务边界处的外部输入
• 处理令牌、账户上下文或敏感负载
• 避免跨账户、跨工作区或跨用户的数据泄露
• 加固暴露或使用敏感数据的集成

以下情况不要使用此技能：

• manifest.json 中的策略声明语法
• 服务运行时容量配置
• 日志记录和可观测性策略
• 前端浏览器安全问题
• 决定应使用哪个 VTEX 身份验证令牌调用端点

决策规则

• 使用此技能判断哪些数据和输入可以安全地跨越应用边界，而不是判断哪些策略或令牌可以授权调用。
• 将每个公开路由都视为明确的信任边界。
• 在 service.json 中，将路由从 public: false 改为 public: true 属于边界变更，应触发明确的安全审查。
• 对于必须从 VTEX IO 外部调用的路由（例如合作伙伴 Webhook 或供外部使用的集成端点），使用 public: true。将其视为暴露于互联网的边界。
• 对于仅供 VTEX 内部流程或其他 IO 应用使用的路由，使用 public: false，但不要因此认为它们默认安全。这些路由仍需验证，并明确适用范围。
• 只要账户域名可访问，service.json 中设置为 public: true 的路由就能从应用外部访问。不要依赖晦涩的路径或看似内部的 URL 作为安全措施。
• 尽早验证外部输入，在其到达业务逻辑或下游集成之前完成验证。
• 对于类似 Webhook 的路由，在调用下游客户端之前，同时验证结构和真实性，例如检查必填字段，并验证共享密钥或签名标头。
• 不要因为请求来自另一个 VTEX 服务，或来自看似内部的路由路径，就认定请求安全。
• 服务读取或写入范围受限的数据时，应明确账户、工作区和用户上下文。
• 如果数据或行为必须限制在特定工作区内，请显式检查 ctx.vtex.workspace，并拒绝来自其他工作区的调用。
• 仅向调用方公开其所需的数据。应有意构造响应，而不是原样返回下游负载。
• 不要在日志或路由响应中暴露机密、令牌或安全敏感标头。
• 不要在生产路由或服务中使用 console.log 或 console.error。应用日志应使用 ctx.vtex.logger 和结构化对象；只有当应用有意将日志转发到合作伙伴拥有的系统时，才使用专用的外部日志客户端。
• 避免暴露会返回内部配置、机密或完整下游负载的调试或诊断路由。如果确实必须使用此类路由，请将其设为非公开，并限制为最少的非敏感信息。
• 使用此技能判断哪些内容可以跨越边界；使用 vtex-io-auth-and-policies 判断如何授权和保护该边界。

相关技能

• vtex-io-auth-and-policies - 当核心决策是如何授权路由或资源访问时使用
• vtex-io-auth-tokens-and-context - 当核心决策是哪个运行时身份应调用 VTEX 端点时使用

硬性约束

约束：公共路由必须在边界处验证不可信输入

任何暴露在严格受控的内部边界之外的路由，在调用领域逻辑或下游客户端之前，都必须验证传入的数据。

重要性

公共边界处未经验证的输入，是导致滥用、错误写入和意外下游故障的最快途径。

检测

如果公共路由未经验证，便将请求体字段、参数或标头直接传入业务逻辑或客户端调用，请立即停止并先添加验证。

正确

export async function webhook(ctx: Context) {
  const body = ctx.request.body

  if (!body?.eventId || !body?.type) {
    ctx.status = 400
    ctx.body = { message: 'Invalid payload' }
    return
  }

  await ctx.clients.partnerApi.handleWebhook(body)
  ctx.status = 202
}

错误

export async function webhook(ctx: Context) {
  await ctx.clients.partnerApi.handleWebhook(ctx.request.body)
  ctx.status = 202
}

约束：敏感数据不得意外跨越路由边界

路由和集成不得泄露令牌、内部标头、原始下游负载，或属于其他账户、工作区或用户上下文的数据。

重要性

边界泄露一旦部署就很难检测，可能会暴露远超预期调用方范围的信息。

检测

如果路由返回原始下游响应、记录机密，或在未明确过滤的情况下混用上下文，请立即停止并收窄输出后再继续。

正确

ctx.body = {
  orderId: order.id,
  status: order.status,
}

错误

ctx.body = order

约束：服务相互调用时必须明确标示信任边界

一个服务调用另一个服务时，接收方边界仍必须被视为真实的安全边界，并进行明确验证、限定假设。

重要性

服务间内部流量仍可能携带格式错误或范围过宽的数据。认为“内部流量意味着可信”会导致安全态势脆弱，并造成跨上下文泄露。

检测

如果服务接收来自另一服务的数据，却未验证格式、范围或账户／工作区上下文，请立即停止并明确执行这些检查。

正确

if (ctx.vtex.account !== expectedAccount) {
  ctx.status = 403
  return
}

错误

await processPartnerPayload(ctx.request.body)

首选模式

安全审查应从边界开始：

1. 谁可以调用此路由或触发此集成？
2. 哪些数据会进入系统？
3. 哪些数据必须立即验证？
4. 哪些数据会离开系统？
5. 账户、工作区或用户上下文是否可能跨边界泄露？

使用最精简的请求和响应结构、明确的验证以及限定范围的上下文检查，确保边界安全。

常见失误

• 将公共路由当作可信的内部处理程序。
• 返回暴露超出必要范围数据的原始下游负载。
• 记录机密或安全敏感标头。
• 在处理程序中使用 console.log，而不使用 ctx.vtex.logger，导致日志结构性较差，并增加敏感数据泄露风险。
• 在未明确检查的情况下混用账户或工作区上下文。
• 假设服务间流量天然安全。

审查清单

• 信任边界是否清晰？
• 外部输入是否在到达领域逻辑或集成逻辑之前经过验证？
• 响应结构是否有意保持精简？
• 是否避免在日志和响应中包含敏感值？
• 账户、工作区或用户上下文是否可能跨越此边界泄露？

参考

• 服务 - 路由暴露与服务行为
• 策略 - 与授权相关的声明上下文