SOP: detectar y corregir conectores Orbitype cruzados

Los conectores Orbitype cruzados aparecen cuando dos proyectos Nuxt usan la misma API key, dos connectors diferentes terminan en la misma base o una credencial etiquetada para un proyecto apunta al contenido de otro. La respuesta segura es detener escrituras, comprobar el destino real con consultas de solo lectura, respaldar los datos, separar el connector y migrar únicamente los registros que tengan un dueño confirmado.

Este SOP parte de un incidente real anonimizado. Los clientes se presentan como Proyecto A y Proyecto B; se eliminaron dominios, IDs de base, fragmentos de credenciales, fechas, cantidades y contenido legal. Los comandos usan placeholders y nunca contienen secretos reales.

Respuesta corta

Proyecto A → key A → connector A → base A
Proyecto B → key B → connector B → base B

Antes de escribir:
huella de key + current_database() + current_schema() + slugs esperados

El nombre del repositorio, el proyecto de Vercel o el label visible en Orbitype no prueba el aislamiento. La evidencia útil es la identidad que devuelve la sesión SQL y la coherencia del contenido que existe allí. PostgreSQL documenta que current_database() devuelve la base actual y current_schema() el primer schema del search path.

Qué falló en el caso anonimizado

La causa no fue única:

1. El archivo de entorno del Proyecto B contenía una credencial asociada al Proyecto A.
2. El connector original del Proyecto B dejó de resolver a una base utilizable.
3. La base accesible contenía registros de ambos proyectos.
4. Los dos sitios live parecían normales en las rutas más visitadas porque marca, navegación y componentes vivían en cada frontend.
5. Una auditoría SEO encontró 404 y rutas incoherentes antes de que la portada de producción mostrara un fallo evidente.

Una corrección basada solo en el slug home terminó escribiendo sobre el contenido del otro proyecto. La lección es operacional: un error de render puede ser el primer síntoma, pero el incidente real es una pérdida de aislamiento entre datos.

Señales que deben detener las escrituras

Señal	Qué puede significar	Acción
Textos de otro proyecto en warnings o SSR	Payload ajeno o schema incompatible	Detener escrituras
Props esperadas como objetos llegan como strings	Secciones de otro frontend	Verificar base y slugs
404 en URLs que deberían existir	Inventario CMS incompleto o cruzado	Comparar sitemap y slugs
Dos entornos producen la misma huella de key	Credencial reutilizada	Rotar y auditar
Keys distintas devuelven la misma base	Connectors sin aislamiento	Separar destino
Error connector not found y campo vacío en UI	Connector roto o eliminado	Crear destino nuevo
Live se ve bien	Solo confirma las rutas visitadas	No autoriza escrituras

1. Contener antes de diagnosticar

Deshabilita temporalmente seeds, instaladores de schema, editores administrativos y scripts one-off. No ejecutes INSERT, UPDATE ni DELETE hasta conocer la base actual y el propietario de los registros.

Si ya ocurrió una escritura incorrecta:

1. detén nuevos despliegues y tareas automáticas;
2. preserva logs sin copiar secretos;
3. restaura desde un backup validado si la producción está afectada;
4. verifica las rutas principales y legales;
5. rota las credenciales expuestas después de estabilizar el servicio.

El hardening de un composable puede impedir un 500 si recibe un shape inesperado, pero no corrige el destino equivocado. Trátalo como contención de render, no como remediación de datos.

2. Identificar cada key sin publicarla

No pegues API keys en chats, tickets, capturas o documentos. En lugar de guardar el valor o su sufijo, calcula localmente una huella SHA-256 corta:

printf '%s' "$ORBITYPE_API_SQL_KEY" | shasum -a 256 | cut -c1-12

La huella permite detectar reutilización sin revelar parte del secreto. Registra internamente una matriz privada con:

Campo	Ejemplo seguro
Proyecto	Proyecto A
Repositorio	repo-a
Huella de key	12 caracteres de SHA-256
Identidad de base	guardada en el secret manager o runbook privado
Entorno	Development, Preview o Production
Estado	verificado, en migración o retirado

3. Ejecutar consultas de solo lectura

Usa variables de entorno locales y placeholders. No escribas el valor de la key dentro del comando:

curl --fail-with-body --silent --show-error "$ORBITYPE_API_SQL_URL" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $ORBITYPE_API_SQL_KEY" \
  --data '{"sql":"SELECT current_database() AS db, current_schema() AS schema"}'

Después revisa el inventario:

SELECT slug FROM pages ORDER BY slug LIMIT 100;

SELECT
  slug,
  left(title::text, 120) AS title_sample,
  json_array_length(sections) AS section_count
FROM pages
ORDER BY updated_at DESC
LIMIT 20;

No confíes solo en el título. Compara también nombres de componentes y forma de las props. Si el Proyecto A espera objetos i18n y recibe strings planos o secciones que no existen en su catálogo Vue, probablemente está leyendo datos ajenos.

Matriz de diagnóstico

Resultado	Diagnóstico probable
Misma huella y misma base	Key copiada entre proyectos
Huellas distintas y misma base	Connectors diferentes sobre un destino compartido
Key A abre slugs del Proyecto B	Connector mal cableado o label engañoso
Key B devuelve connector not found	Credencial revocada o connector roto
Bases distintas y contenido coherente	Aislamiento correcto; aún verifica que el destino sea propio

4. Por qué producción puede parecer sana

Cada deploy aporta su layout, navegación, estilos y catálogo de componentes. El CMS solo responde al slug solicitado. Por eso una home compatible puede renderizar bien mientras otras páginas faltan, devuelven 404 o contienen una forma de sección incompatible.

Además, local, Preview y Production pueden tener valores distintos. En Vercel, los cambios de variables solo se aplican a deployments nuevos, así que “live funciona” no demuestra que el archivo local apunte al mismo destino.

Incluye en observabilidad:

• crawl de rutas canónicas después de cada go-live;
• comparación entre sitemap, allowlist de rutas e inventario CMS;
• alerta ante slugs ajenos al producto;
• verificación de identidad antes de cualquier operación de escritura.

5. Respaldar y clasificar antes de migrar

Obtén un backup completo y verificable. Si tienes acceso PostgreSQL directo, usa la estrategia de backup aprobada por tu proveedor; PostgreSQL recomienda respaldos regulares y documenta pg_dump y pg_restore. Si solo existe una API SQL, exporta las tablas afectadas a almacenamiento cifrado fuera del repositorio.

Clasifica cada fila por propiedad:

• permitida: pertenece claramente al proyecto destino;
• excluida: pertenece claramente al otro proyecto;
• en revisión: no hay evidencia suficiente;
• legal o sensible: requiere validación humana explícita.

Prefiere una allowlist de slugs esperados sobre una lista de exclusión. Copiar “todo menos tres páginas” puede reintroducir legales, metadatos SEO o settings del otro cliente.

6. Crear un destino limpio y migrar

Si el connector no puede repararse:

1. crea un proyecto o connector Orbitype nuevo;
2. confirma que muestra una base válida;
3. genera una credencial nueva;
4. ejecuta current_database() y current_schema();
5. comprueba que pages no existe o está vacía;
6. instala el schema desde el código versionado;
7. importa únicamente registros aprobados;
8. verifica conteos, slugs, home y componentes.

Si un INSERT responde con error, consulta primero si la fila existe antes de reintentar. Una respuesta HTTP fallida no siempre demuestra que la transacción no se aplicó; el reintento ciego puede crear conflictos o duplicados.

7. Hacer el cutover sin perder el rollback

Actualiza Development, Preview y Production de forma controlada. Nuxt mantiene los secretos fuera del cliente cuando se declaran en configuración privada del servidor; revisa la guía oficial de runtime config.

En Vercel:

1. agrega la key nueva al entorno correcto;
2. crea un deployment nuevo;
3. ejecuta smoke tests sobre home, rutas de negocio, sitemap y legales;
4. confirma que la nueva base recibe las lecturas esperadas;
5. conserva temporalmente el destino anterior como rollback;
6. revoca la key antigua cuando todos los entornos estén verificados.

La guía de rotación de secretos de Vercel también recomienda mantener la credencial anterior activa hasta validar los deployments nuevos.

8. Añadir un gate previo a cualquier seed

El control más efectivo es bloquear escrituras por defecto:

async function assertSafeCmsTarget(options: {
  expectedDatabase: string
  allowNonEmpty: boolean
}) {
  const identity = await sql(
    "SELECT current_database() AS db, current_schema() AS schema",
  )

  if (identity[0].db !== options.expectedDatabase) {
    throw new Error("CMS target does not match the expected project")
  }

  const result = await sql("SELECT count(*)::int AS n FROM pages")
  if (result[0].n > 0 && !options.allowNonEmpty) {
    throw new Error("CMS target is not empty; seeding requires review")
  }
}

Para destinos no vacíos, exige una confirmación interactiva y muestra una muestra de slugs. La identidad esperada debe vivir en configuración segura, no hardcodeada en un repositorio público.

Checklist antes de escribir

• Huella de key comparada con los demás proyectos.
• current_database() y current_schema() verificados.
• Slugs y forma de las secciones coherentes con el repo.
• Backup completo fuera del repositorio.
• Registros legales revisados por una persona.
• Destino nuevo vacío o explícitamente aprobado.
• Plan de rollback definido.
• Vercel redeployado después de cambiar variables.
• Key antigua revocada solo después del smoke test.

Preguntas frecuentes

¿Cómo sé si dos proyectos Orbitype comparten una base?

Compara huellas unidireccionales de las keys y ejecuta current_database() con cada una. Keys distintas aún pueden terminar en la misma base; confirma además slugs, títulos y componentes.

¿Qué debo hacer antes de corregir contenido?

Detén escrituras, identifica el destino real, crea un backup y clasifica la propiedad de cada registro. No uses UPDATE sobre home como primera prueba.

¿Rotar la key arregla un connector roto?

No necesariamente. Si el connector no resuelve a una base válida, crea un destino nuevo, migra datos limpios, corta los entornos y rota las credenciales después.

¿Cómo evito que un seed afecte otro proyecto?

Ejecuta un gate bloqueante que valide identidad, tabla vacía e inventario de slugs. Ningún instalador o seed debería escribir solo porque encontró una key en el entorno.

Este mismo principio de secretos server-side y validación por capas se aplica a integraciones de formularios; consulta el SOP de Orbitype, Vercel y SendGrid para un ejemplo complementario.