Back to Details

vtex-io-security-boundaries

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Security Boundaries & Exposure Review

安全边界与暴露审查

When this skill applies

本技能适用场景

Use this skill when the main question is whether a VTEX IO route, integration, or service boundary is safe.
  • Reviewing public versus private route exposure
  • Validating external input at service boundaries
  • Handling tokens, account context, or sensitive payloads
  • Avoiding cross-account, cross-workspace, or cross-user leakage
  • Hardening integrations that expose or consume sensitive data
Do not use this skill for:
  • policy declaration syntax in 
    manifest.json
  • service runtime sizing
  • logging and observability strategy
  • frontend browser security concerns
  • deciding which VTEX auth token should call an endpoint
当核心问题为判断VTEX IO路由、集成或服务边界是否安全时使用本技能。
  • 审查公开与私有路由的暴露情况
  • 在服务边界校验外部输入
  • 处理令牌、账户上下文或敏感载荷
  • 避免跨账户、跨工作区或跨用户的泄露
  • 加固暴露或消费敏感数据的集成
本技能不适用于以下场景：
  • manifest.json
    中的策略声明语法
  • 服务运行时规格配置
  • 日志与可观测性策略
  • 前端浏览器安全问题
  • 决定调用端点应使用的VTEX鉴权令牌类型

Decision rules

决策规则

  • Use this skill to decide what data and input may safely cross the app boundary, not which policies or tokens authorize the call.
  • Treat every public route as an explicit trust boundary.
  • In 
    service.json
    , changing a route from 
    public: false
    to 
    public: true
    is a boundary change and should trigger explicit security review.
  • Use 
    public: true
    for routes that must be callable from outside VTEX IO, such as partner webhooks or externally consumed integration endpoints. Treat them as internet-exposed boundaries.
  • Use 
    public: false
    for routes that are meant only for VTEX internal flows or other IO apps, but do not treat them as implicitly safe. They still require validation and scoped assumptions.
  • A route with 
    public: true
    in 
    service.json
    is reachable from outside the app as long as the account domain is accessible. Do not rely on obscure paths or internal-looking URLs as a security measure.
  • Validate external input as early as possible, before it reaches domain logic or downstream integrations.
  • For webhook-style routes, validate both structure and authenticity, for example through required fields plus a shared secret or signature header, before calling downstream clients.
  • Do not assume a request is safe because it originated from another VTEX service or internal-looking route path.
  • Keep account, workspace, and user context explicit when a service reads or writes scoped data.
  • When data or behavior must be restricted to a specific workspace, check 
    ctx.vtex.workspace
    explicitly and reject calls from other workspaces.
  • Never expose more data than the caller needs. Shape responses intentionally instead of returning raw downstream payloads.
  • Keep secrets, tokens, and security-sensitive headers out of logs and route responses.
  • Do not use 
    console.log
    or 
    console.error
    in production routes or services. Use 
    ctx.vtex.logger
    for application logging with structured objects, and only use a dedicated external logging client when the app intentionally forwards logs to a partner-owned system.
  • Avoid exposing debug or diagnostic routes that return internal configuration, secrets, or full downstream payloads. If such routes are strictly necessary, keep them non-public and limited to minimal, non-sensitive information.
  • Use this skill to decide what may cross the boundary, and use 
    vtex-io-auth-and-policies
    to decide how that boundary is authorized and protected.
  • 本技能用于判断哪些数据和输入可以安全跨越应用边界，而非判断哪些策略或令牌可以授权调用。
  • 将所有公开路由视为明确的信任边界。
  • 在
    service.json
    中将路由从
    public: false
    改为
    public: true
    属于边界变更，需要触发明确的安全审查。
  • 仅对需要从VTEX IO外部调用的路由设置
    public: true
    ，例如合作伙伴Webhook或外部消费的集成端点，将此类路由视为互联网暴露边界。
  • 仅面向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
    判断边界如何进行授权和防护。

Related skills

相关技能

  • vtex-io-auth-and-policies
     - Use when the main decision is how route or resource access will be authorized
  • vtex-io-auth-tokens-and-context
     - Use when the main decision is which runtime identity should call VTEX endpoints
  • vtex-io-auth-and-policies
     - 当核心决策为路由或资源访问的授权方式时使用
  • vtex-io-auth-tokens-and-context
     - 当核心决策为调用VTEX端点应使用的运行时身份时使用

Hard constraints

硬性约束

Constraint: Public routes must validate untrusted input at the boundary

约束：公开路由必须在边界校验不可信输入

Any route exposed beyond a tightly controlled internal boundary MUST validate incoming data before calling domain logic or downstream clients.
Why this matters
Unvalidated input at public boundaries creates the fastest path to abuse, bad writes, and accidental downstream failures.
Detection
If a public route forwards body fields, params, or headers directly into business logic or client calls without validation, STOP and add validation first.
Correct
typescript
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
}
Wrong
typescript
export async function webhook(ctx: Context) {
  await ctx.clients.partnerApi.handleWebhook(ctx.request.body)
  ctx.status = 202
}
任何暴露在严格管控的内部边界之外的路由，必须在调用领域逻辑或下游客户端前校验传入数据。
重要性
公开边界的未校验输入是导致滥用、错误写入和意外下游故障的最直接原因。
检测方式
如果公开路由未做校验就直接将请求体字段、参数或请求头转发到业务逻辑或客户端调用中，请立即停止并先添加校验逻辑。
正确示例
typescript
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
}
错误示例
typescript
export async function webhook(ctx: Context) {
  await ctx.clients.partnerApi.handleWebhook(ctx.request.body)
  ctx.status = 202
}

Constraint: Sensitive data must not cross route boundaries by accident

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

Routes and integrations MUST not leak tokens, internal headers, raw downstream payloads, or data that belongs to another account, workspace, or user context.
Why this matters
Boundary leaks are hard to detect once deployed and can expose information far beyond the intended caller scope.
Detection
If a route returns raw downstream responses, logs secrets, or mixes contexts without explicit filtering, STOP and narrow the output before proceeding.
Correct
typescript
ctx.body = {
  orderId: order.id,
  status: order.status,
}
Wrong
typescript
ctx.body = order
路由和集成不得泄露令牌、内部请求头、原始下游载荷，或属于其他账户、工作区、用户上下文的数据。
重要性
边界泄露一旦部署上线就很难检测，可能导致信息暴露范围远超预期的调用方权限。
检测方式
如果路由直接返回原始下游响应、记录密钥日志，或未做明确过滤就混合不同上下文，请立即停止并先收窄输出范围。
正确示例
typescript
ctx.body = {
  orderId: order.id,
  status: order.status,
}
错误示例
typescript
ctx.body = order

Constraint: Trust boundaries must stay explicit when services call each other

约束：服务间调用时必须保持信任边界明确

When one service calls another, the receiving boundary MUST still be treated as a real security boundary with explicit validation and scoped assumptions.
Why this matters
Internal service-to-service traffic can still carry malformed or overbroad data. Assuming “internal means trusted” leads to fragile security posture and cross-context leakage.
Detection
If a service accepts data from another service without validating format, scope, or account/workspace context, STOP and make those checks explicit.
Correct
typescript
if (ctx.vtex.account !== expectedAccount) {
  ctx.status = 403
  return
}
Wrong
typescript
await processPartnerPayload(ctx.request.body)
当一个服务调用另一个服务时，接收方边界仍必须视为真实安全边界，进行明确校验并做出范围明确的信任假设。
重要性
内部服务间流量仍可能携带格式错误或范围超限的数据。假设「内部流量就是可信的」会导致安全架构脆弱，出现跨上下文泄露问题。
检测方式
如果服务未校验格式、范围或账户/工作区上下文就接受来自其他服务的数据，请立即停止并添加明确的校验逻辑。
正确示例
typescript
if (ctx.vtex.account !== expectedAccount) {
  ctx.status = 403
  return
}
错误示例
typescript
await processPartnerPayload(ctx.request.body)

Preferred pattern

推荐模式

Security review should start at the boundary:
  1. Who can call this route or trigger this integration?
  2. What data enters the system?
  3. What must be validated immediately?
  4. What data leaves the system?
  5. Could account, workspace, or user context leak across the boundary?
Use minimal request and response shapes, explicit validation, and scoped context checks to keep boundaries safe.
安全审查应从边界开始：
  1. 谁可以调用这个路由或触发这个集成？
  2. 有哪些数据进入系统？
  3. 哪些内容必须立即校验？
  4. 有哪些数据流出系统？
  5. 账户、工作区或用户上下文会不会跨越边界泄露？
使用最小化的请求和响应结构、明确的校验、范围受限的上下文检查来保障边界安全。

Common failure modes

常见故障模式

  • Treating public routes like trusted internal handlers.
  • Returning raw downstream payloads that expose more data than necessary.
  • Logging secrets or security-sensitive headers.
  • Using 
    console.log
    in handlers instead of 
    ctx.vtex.logger
    , making logs less structured and increasing the risk of leaking sensitive data.
  • Mixing account or workspace context without explicit checks.
  • Assuming service-to-service traffic is inherently safe.
  • 将公开路由视为可信内部处理器
  • 直接返回原始下游载荷，暴露超出必要的数据
  • 打印包含密钥或安全敏感请求头的日志
  • 在处理器中使用
    console.log
    而非
    ctx.vtex.logger
    ，导致日志结构化程度低，增加敏感数据泄露风险
  • 未做明确校验就混合账户或工作区上下文
  • 默认认为服务间流量本质安全

Review checklist

审查检查表

  • Is the trust boundary clear?
  • Are external inputs validated before reaching domain or integration logic?
  • Is the response shape intentionally minimal?
  • Are sensitive values kept out of logs and responses?
  • Could account, workspace, or user context leak across this boundary?
  • 信任边界是否清晰？
  • 外部输入在进入领域或集成逻辑前是否完成校验？
  • 响应结构是否有意识地做了最小化处理？
  • 敏感值是否未出现在日志和响应中？
  • 账户、工作区或用户上下文会不会跨越该边界泄露？

Reference

参考资料

  • Service - Route exposure and service behavior
  • Policies - Authorization-related declaration context
  • 服务 - 路由暴露与服务行为
  • 策略 - 授权相关的声明上下文