Security Boundaries & Exposure Review

When this skill applies

• 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

• 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

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.

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

Hard constraints

Constraint: Public routes must validate untrusted input at the boundary

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
}

Constraint: Sensitive data must not cross route boundaries by accident

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

ctx.body = order

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

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

await processPartnerPayload(ctx.request.body)

Preferred pattern

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?

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.

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