Estado: prototipo probado con vtex link en empathymx/vendorread (11-nov), en la rama claude/feat-vendor-read-api-208e4b (parte de v0.2.1, e3d0a5e). No está publicado ni desplegado.
Objetivo
Que Jorge pueda, desde la cuenta del vendor empathymx, leer las entidades de Master Data propias del conector en cualquier cuenta cliente que lo tenga instalado, sin pedir acceso al cliente. Además, borrar registros de empathyProduct para forzar que un producto vuelva a entrar en el feed (el caso del 304 de Master Data).
Fuera de alcance: datos que no sean del conector, escrituras que no sean ese borrado y cualquier entidad con datos personales.
Arquitectura
Rutas nuevas
| Route ID | Ruta | Dónde responde | Acceso |
|---|---|---|---|
vendorRead | GET /_v/empathy/vendor/entities/:entity | Todas las cuentas | Privada, access: authorized, política get con principal fijado a empathymx, más verifyVendorCaller |
vendorDeleteProducts | DELETE /_v/empathy/vendor/products?ids=¬ify= | Todas las cuentas | Igual, con la acción delete |
vendorProxyRead | GET /_v/empathy/vendor-proxy/:account/entities/:entity?workspace= | Solo en empathymx (404 en el resto) | adminMiddleware (usuario admin de empathymx) |
vendorProxyDelete | DELETE /_v/empathy/vendor-proxy/:account/products?ids=¬ify=&workspace= | Solo en empathymx | Igual |
Parámetros de lectura (los valida node/utils/vendorQuery.ts):
ids=a,b,c: hasta 100 ids de documento. Respondedataymissing.- Sin
ids, lectura por páginas con la búsqueda de Master Data (nunca scroll, ver Riesgos):page(desde 1),size(1–100, por defecto 100),eq.<campo>=<valor>sobre campos indexados de la lista blanca, ysince/until(fechas ISO) sobredateField(por defectolastInteractionInenempathyProductycreatedInen el resto). Se ordena pordateField. La búsqueda solo sirve los primeros 10.000 resultados de cada consulta: para más, se acota con fechas. fields=a,b: un subconjunto de los campos permitidos. Siempre incluyeid.- La respuesta trae
totaly, si hay otra página alcanzable,nextPage.
El llamante nunca manda un where libre: el servidor lo construye con nombres de campo de la lista blanca y valores de un alfabeto cerrado ([A-Za-z0-9_.-]). Así no se pueden inyectar cláusulas ni usar un where sobre un campo oculto para adivinar su valor.
Opción A frente a B (elegida: A)
| A: ruta del conector (elegida) | B: app aparte empathymx.connector-reader | |
|---|---|---|
| Despliegue | Va con la próxima versión del conector, sin nada más que instalar | Una app más que publicar, versionar e instalar en empathymx |
| Confianza en el destino | El principal ya es este conector (el mismo patrón de las white labels) | El conector tiene que confiar en un segundo principal y en otro ciclo de versiones |
| Superficie | La ruta proxy existe en todas las cuentas, pero responde 404 si la cuenta no es empathymx y exige un admin válido | Aislada: solo existe en empathymx |
| Coste | S | M |
Se elige A por coste y porque reutiliza un mecanismo ya verificado (verifyWhiteLabelCaller, 5-nov). El inconveniente de A, que la ruta proxy está en todas las cuentas, queda cubierto: sin la cuenta empathymx responde 404 antes de hacer nada.
Lo verificado (y lo que no)
| Pregunta | Respuesta | Fuente |
|---|---|---|
| ¿Cómo se autentica una llamada app→app? | Ruta privada con política de recurso. El principal es un VRN vrn:{service}:{region}:{account}:{workspace}:{path}; para apps, service=apps y path=app/{vendor}.{app}@{version} | developers.vtex.com, Controlling access to app resources y VTEX Resource Name (VRN) |
| ¿Se puede fijar la cuenta que llama? | El VRN tiene el segmento account. El builder acepta el principal vrn:apps:*:empathymx:*:app/…, y la llamada de empathymx a empathymx pasa (prueba e2e del 11-nov). Falta probar que rechaza al conector de otra cuenta: de eso se encarga también verifyVendorCaller | Doc VRN; e2e en empathymx/vendorread |
| ¿Qué cabeceras pone el router? | En una llamada app→app consume el Authorization y pone x-vtex-caller (vendor.app@versión), x-vtex-caller-role, x-vtex-account y x-vtex-workspace. Pone x-vtex-origin-account/-workspace solo cuando la llamada cruza de cuenta: estaban en aconnector (5-nov) y no en la llamada de empathymx a empathymx (11-nov). Por eso verifyVendorCaller, si falta el origen, toma la cuenta propia (así solo se pueden leer los datos de empathymx). No viene en la doc | Observado; log temporal en vendorread |
| ¿Se pueden falsificar desde fuera? | No (verificado el 11-nov). Por myvtex.com, las rutas privadas ni existen (404, con o sin token y cabeceras falsas). Por app.io.vtex.com sin token, el router responde 401 (Credential required). Con el token de admin de la propia cuenta más x-vtex-caller y x-vtex-origin-account falsos, el router responde 403 (Role User:… cannot perform action GET on resource vrn:…). Las cabeceras falsas nunca llegan a la app | e2e, ver "Resultados" |
¿Sirve un principal de usuario (vrn:vtex.vtex-id:…:user/*@empathy.co) entre cuentas? | No se usa. Los tokens de usuario de VTEX ID pertenecen a una cuenta, y no está documentado que una política de la cuenta B acepte un usuario autenticado en A. Además, la doc dice que la política evalúa solo al dueño del token que llega; por eso el proxy llama con el token de la app, no con el del usuario | Doc Controlling access… (sección del dueño del token) |
¿Basta el token de la app en el cliente para leer empathyProduct? | Sí. Es lo que ya hace el conector (getProduct, el feed, las limpiezas), con la política ADMIN_DS del manifest | Código actual |
| Volumen | Gandhi tiene millones de empathyProduct. La API pagina con la búsqueda (100 por página, hasta 10.000 por consulta), así que una población grande se recorre por tramos de since/until o por ids en tandas de 100. No usa scroll: cada scroll ocupa durante minutos uno de los 10 que permite MD por cuenta, que son los mismos que necesita el feedUpdate (ver Riesgos) | Incidente del 11-nov en Gandhi |
Resultados de la prueba de punta a punta (11-nov, empathymx/vendorread, vtex link)
| # | Prueba | Resultado |
|---|---|---|
| 1 | Proxy con sesión de admin → empathyProduct (scroll, 3 docs) | ✅ 200, solo los campos pedidos, con cursor |
| 1b | Proxy → empathyConnectorAuditLog | ✅ 200, sin user ni actionData |
| 1c | Pedir el campo user | ✅ 400 field "user" is not readable |
| 1d | Entidad fuera de la lista (CL) | ✅ 404 |
| 2 | Proxy sin sesión | ✅ 401 |
| 3–4b | Ruta del destino por myvtex.com: sin token, con cabeceras falsas y con el token de usuario | ✅ 404: el host público no expone rutas privadas |
| 5 | Destino por app.io.vtex.com sin token y con cabeceras falsas | ✅ 401 del router |
| 5b–5c | Destino con el token de admin de empathymx (Bearer o VtexIdclientAutCookie) más cabeceras falsas | ✅ 403 del router (la política solo admite la app) |
| 6 | DELETE en el destino con token de usuario y cabeceras falsas | ✅ 404 |
| 7 | SSRF por el proxy (:account = evil.com) | ✅ 400 |
| 8 | Lectura por ids con uno inexistente | ✅ 200 y missing: ["999999999-1"] (corregido en d1716c8: Master Data responde 200 vacío, no 404) |
| 9–10 | Segunda página con cursor; filtro eq.whitelabel=1 + since | ✅ 200 |
| 11 | DELETE por el proxy de un id inexistente, sin notify | ✅ 200 not-found (corregido en d1716c8: Master Data da éxito al borrar un id inexistente, así que se comprueba antes) |
Entre cuentas: empathymx → superxtrapanama/vendorread (11-nov)
| # | Prueba | Resultado |
|---|---|---|
| X1, X3, X4 | Lectura de empathyProduct, empathyIndex y auditoría de Xtra | La llamada pasa el router, el principal fijado a empathymx y verifyVendorCaller, y llega al handler. Master Data responde 403 "Cannot read private fields" |
| — | Causa | La credencial que llega al destino es la del conector en Xtra (account: superxtrapanama, sub: empathymx.empathy-feed-connector-mr), pero de tipo link, con userLogin: latam@empathy.co. Con una app linkeada, Master Data aplica los permisos de ese usuario, que no puede leer en Xtra. Comprobado: getproduct (ruta existente) da el mismo 403 en el workspace linkeado y responde bien en master con la app instalada. Instaladas, las rutas nuevas usan el token de la app, como getproduct |
| X2 | Scroll con filtro en 1,4 M docs | 504 a los 30 s. Se quita el sort (094473b), y conviene usar since/until en entidades grandes |
| X5 | Destino en master (sin la versión nueva) | 403 del router: la ruta no existe en la versión instalada |
Pendiente para después del deploy: lectura y borrado real entre cuentas con la app instalada (primero una lectura en Gandhi).
No probado: el 403 cuando llama el conector instalado en otra cuenta (solo había empathymx; está cubierto por tests unitarios y por el principal fijado) y un borrado real con notify=true.
Modelo de amenazas
| Actor y ataque | Qué lo para |
|---|---|
Cualquiera en internet llama a /_v/empathy/vendor/... | Ruta privada: el router exige un token del principal |
| Una appkey o un usuario de la cuenta cliente | No son el principal (que es una app): 403 del router |
| El conector instalado en otra cuenta cliente (p. ej. un cliente lee a otro) | El principal está fijado a empathymx y verifyVendorCaller exige x-vtex-origin-account === 'empathymx': 403 |
| Otra app de cualquier vendor | El principal es solo este conector, y verifyVendorCaller comprueba x-vtex-caller: 401 o 403 |
Cabeceras x-vtex-* falsificadas | Sin token del principal no se llega a la app: 401 o 403 del router (verificado) |
Usuario de empathymx sin rol admin, o la ruta proxy en otra cuenta | adminMiddleware (audiencia admin) → 401; fuera de empathymx → 404 |
SSRF por el proxy (:account = evil.com/...) | account y workspace deben cumplir ^[a-z0-9]{1,64}$; el host es fijo (app.io.vtex.com) |
| Exfiltrar datos personales | La lista blanca no los incluye (ver abajo) y tampoco se puede filtrar por ellos |
Inyección en el where | No hay where libre; los valores van con un alfabeto cerrado |
| Abuso de volumen | rateLimitPerReplica: lectura 120/min y 5 concurrentes; borrado 10/min y 1 concurrente; hasta 100 docs por página y 10.000 por consulta, 100 ids por lectura y 50 por borrado |
| Borrado masivo por error | Solo empathyProduct y solo por id (sin borrado por filtro), hasta 50 por llamada, y queda en el log |
Un admin de empathymx lee datos de clientes | Es la intención. Queda trazado: el proxy registra usuario, cuenta destino, entidad y parámetros, y el destino registra la cuenta que llamó, la entidad y cuántos registros devolvió (vtex logs / Splunk de VTEX) |
Riesgo residual
- Cualquier admin de
empathymxpuede leer. Si se quiere solo a Jorge, se puede añadir una lista de correos en un setting oculto deempathymx(S). - Si el token de la app del conector en
empathymxse filtrara, daría lectura y borrado deempathyProducten todas las cuentas. Ese token solo existe dentro del runtime de VTEX IO y no se expone. La ruta públicaindexerAuthsí devuelve el token de la app de cada cliente (ver "Cerrar las rutas públicas").
Cómo cumple la regla master-data-security-data-exposure
La regla prohíbe rutas que consulten Master Data y devuelvan los datos tal cual, sobre todo los personales, y recuerda que public:false no es seguridad. Este diseño es una excepción acotada que Jorge tiene que aprobar de forma explícita. Lo justifica esto:
- No hay datos personales. Las entidades son del propio conector (catálogo, estados de trabajos y auditoría técnica). En la auditoría se quitan
user(correo del admin) yactionData(cuerpos de petición, entre ellos los settings conclientIdde Empathy). - La seguridad no es solo
public:false. La autenticación la hace la plataforma:access: authorizedcon una política de recurso cuyo principal es una app concreta fijada a una cuenta. Encima va un segundo control con la identidad que pone el router. No se reinventa la autenticación. - Lo mínimo. Lista blanca de campos y filtros, paginación con límite y sin
wherelibre. - Trazabilidad. Log estructurado en el proxy (quién) y en el destino (qué y cuánto).
- No existe la alternativa que propone la regla ("que el navegador consulte la API de VTEX con las credenciales del usuario"). Jorge no tiene usuario en las cuentas de los clientes, y eso es justamente lo que se quiere evitar.
- Reduce la exposición actual: permite cerrar
getproduct, que hoy es pública y sin autenticación.
Lista blanca
| Entidad | Campos legibles | Filtros eq. | dateField |
|---|---|---|---|
empathyProduct | id, createdIn, lastInteractionIn y los campos del feed (FEED_FIELDS: productID, name, skuId, isActive, isVisible, precios, offers, whitelabel, purchased, …) | productID, skuId, whitelabel, isActive, isVisible | lastInteractionIn, createdIn |
empathyIndex | id, fechas, status, mode, totalItems, progress, listedSkus, errorCount, error | status | createdIn, lastInteractionIn |
empathyConnectorAuditLog | id, fechas, action, status, errorMessage | action, status | createdIn, lastInteractionIn |
empathyProductCleanup | id, fechas, kind, status, stage, workspace, contadores, hasMore, error | status, kind | createdIn, lastInteractionIn |
Excluidos a propósito: user y actionData de la auditoría; batches, itemsWithErrors, markFailures y attemptId (cargas codificadas grandes o tokens internos).
Borrado para forzar reindexación
DELETE …/products?ids=7751437-1,7751881-1¬ify=true
- Solo
empathyProduct, solo ids<skuId>-<whitelabel>, hasta 50 por llamada. - Por qué funciona: si el conector reescribe un documento con los mismos valores, Master Data responde 304 y no mueve
lastInteractionIn, así que el documento no vuelve a entrar en ningún parcial. Un documento borrado se crea de nuevo en el siguiente evento de producto, conlastInteractionInnuevo, y entra en el siguiente parcial. - Con
notify=true, el conector dispara al momento el mismo evento queskuUpdate(update-empathy-product), conAn= la cuenta para la white label1y el id de la white label en el resto. También renotifica los ids que no existían (recrearlos es el objetivo). - Cuidado: sin
notify, el documento queda borrado hasta el próximo cambio del SKU, y un feed completo enviado mientras tanto lo quitaría del índice. Usar siemprenotify=truesalvo que se quiera eso. - Respuesta:
results[]condeleted,not-foundofailedpor id; 207 si alguno falló.
Ejemplo: Gandhi (MD frente al índice)
Regla: un SKU está desalineado si no existe en el índice gandhinew-catalog-es o si lastInteractionIn (MD) es más nuevo que indexMetrics.readTime (índice) por más de 30 minutos.
_10TOKEN=$(vtex local token) # con sesión de admin en empathymx_10BASE="https://empathymx.myvtex.com/_v/empathy/vendor-proxy/gandhi"_10_10# 1. MD: los 24 SKUs del diagnóstico del 11-nov_10curl -s -H "Cookie: VtexIdclientAutCookie=$TOKEN" \_10 "$BASE/entities/empathyProduct?ids=1-1,7751437-1,7751881-1&fields=skuId,isActive,price,lastInteractionIn" > md.json_10_10# 2. Índice: Kibana Latam Main → gandhinew-catalog-es/_search_10# {"query":{"ids":{"values":["1-1","7751437-1","7751881-1"]}},"_source":["indexMetrics.readTime","isActive","price"]}_10# Guardar la respuesta como es.json
_17// compare.js — node compare.js md.json es.json_17const [md, es] = process.argv.slice(2).map(f => require(require('path').resolve(f)))_17const THRESHOLD_MS = 30 * 60 * 1000_17const index = new Map(es.hits.hits.map(h => [h._id, h._source]))_17_17const rows = md.data.map(doc => {_17 const hit = index.get(doc.id)_17 const mdTime = Date.parse(doc.lastInteractionIn)_17 const readTime = hit && Date.parse(hit.indexMetrics?.readTime)_17 const misaligned = !hit || mdTime - readTime > THRESHOLD_MS_17_17 return { id: doc.id, lastInteractionIn: doc.lastInteractionIn, readTime: hit?.indexMetrics?.readTime ?? null, misaligned }_17})_17_17console.table(rows)_17console.log('desalineados:', rows.filter(r => r.misaligned).map(r => r.id).join(','))_17console.log('sin documento en MD:', md.missing.join(','))
Para corregir los desalineados (con OK previo, porque es una escritura en producción):
_10curl -s -X DELETE -H "Cookie: VtexIdclientAutCookie=$TOKEN" \_10 "$BASE/products?ids=<ids desalineados, hasta 50>¬ify=true"
Para una población grande (por ejemplo, todo lo tocado en un día), conviene paginar con since/until y page en lugar de usar ids:
_10curl -s -H "Cookie: VtexIdclientAutCookie=$TOKEN" \_10 "$BASE/entities/empathyProduct?eq.whitelabel=1&since=2026-11-10T00:00:00Z&until=2026-11-10T06:00:00Z&size=100&fields=lastInteractionIn"_10# Repetir con &page=<nextPage> hasta que no venga nextPage. Si total pasa de 10.000, acortar el tramo.
Cerrar las rutas públicas existentes
| Ruta | Quién la usa | Propuesta | Coste |
|---|---|---|---|
getproduct (GET, pública, sin auth) | Diagnóstico (Jorge) | La sustituye vendor/entities/empathyProduct?ids=. Quitar la ruta o ponerle adminMiddleware | S |
skuupdate (POST, pública, sin auth) | El broadcaster de catálogo de VTEX (webhook) y las notificaciones manuales | Suscribirse al evento IO vtex.broadcaster (broadcaster.notification) en service.json en lugar del webhook HTTP. Mientras convivan, exigir un secreto aleatorio (setting oculto generado al instalar) en la query de la URL registrada. Las notificaciones manuales pasan por la ruta del vendor | M |
feedupdate (POST, pública, sin auth) | index-vtex-connector al terminar un índice delegado; el panel de admin | Exigir fullIndexId de un empathyIndex en in-progress/generating-files más el secreto del punto siguiente (el mismo patrón que indexerAuth), o un usuario admin. Una llamada sin eso → 403 | M |
indexer-auth (GET, pública) devuelve el token de la app a quien conozca un id de empathyIndex reciente | index-vtex-connector (cada contenedor pide un token por callback) | El conector genera un secreto aleatorio por trabajo, guarda su hash en el empathyIndex y lo manda en POST /indexation-requests (por TLS). indexer-auth exige id + secreto. Requiere un cambio coordinado en index-vtex-connector. A largo plazo, que el indexador use una appkey propia por cliente con un rol mínimo (lectura de catálogo y empathyProduct) en lugar del token de la app | M (+ cambio en el indexador) |
logcleanup (POST, pública, sin auth) | Cron interno | adminMiddleware o pasarla a evento | S |
fullupdate/status, fullupdate/status/:id (GET, públicas) | Panel de admin | adminMiddleware | S |
Las white labels no se ven afectadas: ya usan whitelabelnotify/whitelabelproduct, que son privadas con política y verifyWhiteLabelCaller.
Tareas
| # | Tarea | Tamaño | Estado |
|---|---|---|---|
| 1 | Rutas vendor/entities, vendor/products (DELETE) y proxy, con middleware, lista blanca y tests | M | ✅ 52c1b9b, 90dbf98, d1716c8; 68 suites y 585 tests en verde |
| 2 | vtex link en empathymx (workspace de dev) y prueba e2e, incluidas las negativas | S | ✅ 11-nov, ver "Resultados" |
| 3 | Confirmar si el principal fijado a empathymx funciona; si no, volver a * | S | ✅ Admite a empathymx; falta ver que rechaza a otra cuenta (tarea 4) |
| 4 | Probar entre dos cuentas reales (p. ej. empathymx → empathymxwl1), incluido 403 desde otra cuenta | S | Pendiente |
| 5 | Opcional: lista de usuarios permitidos para el proxy (setting oculto en empathymx) | S | — |
| 6 | Cerrar getproduct, logcleanup y los status | S | — |
| 7 | skuupdate con evento del broadcaster y secreto transitorio | M | — |
| 8 | feedupdate + indexer-auth con secreto por trabajo (coordinar con index-vtex-connector) | M | — |
| 9 | Script de reconciliación Gandhi a escala (MD por scroll frente a ids en ES) | M | — |
| 10 | Publicar como beta, desplegar e instalar en clientes (requiere OK) | S | — |
Riesgos
- No está probado que el principal fijado rechace a otra cuenta (tarea 4). Mitigación:
verifyVendorCallertambién comprueba la cuenta. - Las cabeceras del router no están documentadas: si VTEX las cambia, el acceso se cierra (falla de forma segura: 401).
- Agotar los scrolls de MD de la cuenta cliente (ocurrió el 11-nov en Gandhi con la 0.2.2): cada lectura por páginas abría un scroll, y unas 150 seguidas llenaron el cupo de 10 por cuenta. Los parciales del cron fallaron con "Maximum simultaneous scrolls rate exceeded (10)". Corregido en la rama
fix/vendor-read-no-scroll: la API pagina con la búsqueda, que no usa scroll. Lección: una ruta que lee en el contexto del cliente no debe usar recursos de cupo compartido con el conector. - Borrado sin
notify: deja el producto fuera hasta el siguiente cambio, y un feed completo lo quitaría del índice. Mitigación: documentado; se podría hacernotify=truepor defecto. - Clientes con versiones viejas: la ruta solo existe donde esté instalada la versión nueva (
@0.xse propaga sola tras eldeploy).