Mapa crítico · Credenciales, dependencias y rotación entre plataformas

Para qué sirve esta página

Mapa único y vivo de todas las credenciales, tokens, claves API, deploy keys SSH, GitHub Apps y Service Tokens que conectan las plataformas del proyecto, junto con el grafo de dependencias entre ellas y los procedimientos de rotación/auditoría.

Complementa al [[entity—ops—catalogo-servicios-externos]] (que cubre qué pagamos y a quién) respondiendo a una pregunta distinta: qué credenciales tenemos en circulación, dónde viven, qué depende de cada una, cómo regenerarlas, cómo auditarlas.

Grado: 🔴 Crítico. La pérdida o expiración descontrolada de cualquier item de este mapa rompe partes del pipeline. La última crisis (migración GitHub User→Org · sesiones 74-76, 19/20-05-2026) reveló que sin un mapa unificado tardamos horas en detectar qué dejó de funcionar.

Mantenimiento: lifecycle: refresh-30d — el Bibliotecario marca esta página como pendiente de verificación cada 30 días. Owner: Edu.

✅ Inventario RE-VERIFICADO el 24-07-2026 (s235) contra las fuentes vivas: GitHub API (deploy keys, secrets, apps, toggle Org) + SSH a OPS (100.96.245.233) y STAGE (100.96.254.204). Cambios estructurales desde la versión de mayo, ya incorporados abajo: Tailscale → NetBird (s85) · crons migrados de STAGE a OPS (s174-s201, deploy keys viejas 152056708/152056710 revocadas → 1 key crearack-ops por repo) · firewalls solo-NetBird (s222) · rotaciones CF Access (s222-s223, playbook §9) y MCP_TOKENS (s216) · el deploy del workspace es un cron de OPS (el workflow “CF Pages Deploy” está disabled_manually). El secret huérfano CLAUDE_METHOD_DEPLOY_KEY detectado en la verificación quedó RESUELTO el mismo día (decisión de Edu, opción a: secret borrado + workflow eliminado — ver §1.2).

Cuándo consultar este doc

• Auditoría rutinaria (mensual) — recorrer las secciones y validar que cada credencial sigue activa, dentro de su expiración y con scope correcto.
• Tras incidente de plataforma (transferencia de cuentas, cambios de Org, rotación masiva, leak sospechoso) — usar la matriz de dependencias para detectar qué se ha podido romper en cascada.
• Onboarding de nuevo dev — explicarle dónde vive cada credencial y por qué.
• Antes de regenerar una credencial — ver en la matriz qué se va a ver afectado y avisar a Dani/Txell si aplica.
• Cuando el Help Widget, Pulse, widget CI Pipeline, MCP handlers o cualquier integración externa empiece a dar 401/403/404 desde un día concreto — es casi siempre un token caducado o desactivado por cambio de cuenta upstream.

Cómo usarlo

1. Buscar qué credencial usa una funcionalidad → tabla “Matriz de dependencias plataforma → credencial” abajo.
2. Ver scope y dónde está almacenada una credencial → tabla “Inventario” en su categoría (PATs, Deploy Keys, OAuth, API Keys, Service Tokens, GitHub Apps).
3. Regenerarla → sección “Procedimientos de rotación” con el paso a paso de cada tipo.
4. Validar el sistema entero post-cambio → script de auditoría al final de la página.

Mapa visual de plataformas raíz

Las 11 plataformas raíz de las que dependen las 3 plataformas del proyecto (CreaRack Pro, Workspace, claude-method):

flowchart LR
    GH[GitHub Org<br/>CreaRackSL]
    CF[Cloudflare<br/>Workers + Pages + DNS + Access]
    HET[Hetzner<br/>PROD + STAGE + OPS + Object Storage]
    DOK[Dokploy<br/>en PROD + STAGE]
    AI_G[Google AI Studio<br/>Gemma 4]
    AI_A[Anthropic API<br/>Claude Haiku]
    RES[Resend<br/>email transaccional]
    ZOH[Zoho<br/>Calendar + Mail]
    HOL[Holded<br/>facturación]
    NB[NetBird<br/>VPN mesh solo-NetBird]
    UR[UptimeRobot<br/>monitoring externo]

    GH -->|deploy| CF
    GH -->|deploy keys SSH| HET
    GH -->|App| DOK
    CF -->|D1 + R2 + Vectorize + AI binding| CF
    CF -->|CF Access JWT| HET
    HET -->|crons OPS| GH
    HET -->|VictoriaMetrics scrape| HET
    DOK -->|deploy| HET
    CreaRackPro[CreaRack Pro<br/>SaaS Django] --> HET
    CreaRackPro --> AI_G
    CreaRackPro --> AI_A
    CreaRackPro --> RES
    Workspace[Workspace<br/>Astro + Pages Functions] --> CF
    Workspace --> GH
    Workspace --> AI_G
    Workspace --> AI_A
    Workspace --> ZOH
    Workspace --> HOL
    Workspace --> RES
    UR -.->|check| CreaRackPro

1 · Inventario de credenciales por categoría

1.1 GitHub Personal Access Tokens (PATs)

Tokens fine-grained emitidos por Esquembri (cuenta personal Owner del Org CreaRackSL) con resource owner = CreaRackSL Org.

Regla operativa: cualquier PAT nuevo del proyecto debe crearse con resource owner = Org CreaRackSL, NUNCA bajo cuenta personal de un dev. El motivo está documentado en el footgun gh_cli_token_owner_removal (s75): si un PAT está atado al usuario y ese usuario deja el Org, el PAT pierde scope silenciosamente.

1.2 Deploy keys SSH (read-only) · ✅ VERIFICADO 24-07-2026

Estado real post-migración a OPS (las 2 keys de la era STAGE — staging-bib-reindex 152056708 y Bibliotecario Reindex (Oraculo Fase 2) 152056710 — fueron revocadas en s201):

✅ Resuelto 24-07-2026 (decisión de Edu, opción a): el secret CLAUDE_METHOD_DEPLOY_KEY (huérfano — su pubkey 152056710 fue revocada en s201) se borró del workspace, y el workflow bib-reindex-claude-method.yml (sin runs desde 16-06, dispatch manual roto) se eliminó del repo. El reindex de claude-method lo cubre el cron bib-reindex-ws de OPS. Reversible: el .yml sigue en el historial de git y una deploy key nueva se emite en 1 min si algún día se quiere el fallback en Actions.

Toggle Org obligatorio (verificado true 24-07): la Org CreaRackSL tiene deploy_keys_enabled_for_repositories: true. Si vuelve a false (default al crear Org Free), TODAS las deploy keys quedan en enabled: false silenciosamente. Toggle a nivel Org → https://github.com/organizations/CreaRackSL/settings/security_analysis (o via API gh api -X PATCH orgs/CreaRackSL -F deploy_keys_enabled_for_repositories=true).

Footgun documentado en s76: tras transferir un repo desde User a Org, las deploy keys que tenía el User quedan asociadas con added_by: <user-bridge> y aunque el toggle Org esté activo, GitHub puede devolver enabled: false hasta re-añadirlas. Procedimiento de recuperación abajo.

1.2bis Crons por servidor · ✅ VERIFICADO por SSH 24-07-2026

Inventario canónico completo: AUTOMATISMOS.md del workspace. Foto verificada:

OPS (crearack-ops · 100.96.245.233) — TODOS los crons de mantenimiento:

STAGE (crearack-staging · 100.96.254.204) — limpio tras la F3 (s201), solo DR:

(+ /opt/workspace-mirror = mirror DR estático :8090.)

Workflows de GitHub Actions: siguen activos Ingest (post-merge), Catalog, Curator*, Lint*, Utility*, Drift-Check*, Weekly-Report, Reindex-TS/Supercontext*, D1 Cleanup, atlas-check, CI, Rotate-MCP-Tokens (*varios con schedule comentado — la ejecución real es el cron OPS; queda workflow_dispatch). CF Pages Deploy y Escriba drift cron están disabled_manually (migrados a OPS) y bib-reindex-claude-method.yml fue eliminado (24-07, opción a).

1.3 OAuth tokens (Zoho per-user)

3 tokens OAuth almacenados en D1 tabla zoho_oauth del workspace (multi-user desde migración s68 0027). Cada miembro del staff autoriza su propia cuenta Zoho.

App OAuth Zoho (Server-based) registrada en api-console.zoho.com cuenta esfericlabs.com. client_id + client_secret viven en CF Pages env vars ZOHO_CLIENT_ID + ZOHO_CLIENT_SECRET. Detalle en [[runbook—zoho-integration-end-to-end]].

Procedimiento re-autorización (cuando un refresh_token deja de funcionar tras revoke manual desde Zoho UI o tras cambio de scopes): cada usuario va a https://workspace.crearack.com/settings/integrations/zoho y pulsa “Autorizar mi cuenta”. El admin puede actuar por delegación con ?as=Edu|Dani|Txell (requiere ADMIN_EMAILS env var del workspace que incluya al actor). IMPORTANTE: en flujos admin, hacer logout en mail.zoho.eu entre cada ?as= para no contaminar el token con cuenta cruzada (footgun s68 feedback_zoho_logout_between_admin_oauth).

1.4 API keys de proveedores externos

Claves de proveedores third-party. No son PATs ni OAuth; son tokens estáticos con scope total sobre la cuenta. Política: NUNCA commitearlas, NUNCA en plain text en docs, SIEMPRE en secrets de plataforma.

Secrets por repo verificados 24-07-2026 — Pro: ANTHROPIC_API_KEY · CF_ACCESS_CLIENT_ID/SECRET (secret 14-07 ✓ rotación s222) · MCP_TOKEN (10-07 ✓ rotación s216) · WORKSPACE_REPO_TOKEN. Workspace (9 tras borrar el huérfano CLAUDE_METHOD_DEPLOY_KEY): los anteriores + ATLAS_CHECK_PAT · CLOUDFLARE_ACCOUNT_ID/API_TOKEN/D1_TOKEN · GOOGLE_AI_API_KEY. claude-method: vacío ✓.

1.5 Cloudflare Access Service Tokens

⚠️ Rotado en s222-s223 (14-07-2026): el secret vigente y el inventario de las 6 copias a sincronizar en cada rotación viven en el playbook canónico [[crearack-tech—guides—secret-rotation-playbook]] §9. La policy de /api/mcp es Service Auth (un token en policy Bypass NO autentica — footgun s223).

Tokens emitidos desde el panel CF Zero Trust → Service Auth → Service Tokens. Cada uno autoriza llamadas headless a un endpoint protegido por CF Access sin pasar por OAuth de Google/GitHub.

Toggle bypass-everyone: el endpoint /.well-known/cloudflare-access-protected-resource/* y /.well-known/version.json tienen política “Bypass Everyone” (público) para que el banner detector versión y OAuth discovery funcionen sin auth. Cualquier otro endpoint del workspace está detrás de CF Access standard.

Arquitectura policies a nivel cuenta (s78 · 21-05-2026): la UI actual de CF Zero Trust trata las policies como objetos a nivel cuenta reutilizables. La policy Service Tokens (crons) (acción Service Auth) se asocia simultáneamente a varias apps. Eliminada en s78 la app específica DR Backup Service (workspace.crearack.com/api/maintenance/*) tras causar bucle de redirect 302 para usuarios staff: la app más específica tumbaba el SSO de CreaRackSL Workspace. Path /api/maintenance/* ahora cubierto por la app principal (policy “Team only” para users + “Service Tokens (crons)” para tokens). Footguns relacionados: [[footguns_cf_access_app_path_specificity]] · [[footguns_cf_access_service_token_requires_service_auth_action]] · [[footguns_cf_access_account_policies_need_app_link]] (memorias locales staff).

1.6 GitHub Apps instaladas en Org · ✅ VERIFICADO 24-07-2026

Webhooks salientes clásicos en repos: 0 (esperado — las Apps los reemplazan).

1.5.bis Cloudflare Access · policy de usuarios (login del staff)

Además de los Service Tokens (1.5), la app CreaRackSL Workspace tiene una policy de usuarios humanos que define quién puede entrar a workspace.crearack.com con su login Google/GitHub. Es lo que valida el acceso de Edu, Dani y Txell al workspace.

Caso Dani (verificar en panel): existió un desajuste histórico por el cual el login de Dani usaba el email legacy dfuentes@edomo.net mientras la policy exigía dfuentes@esfericlabs.com. Acción de verificación (no hay forma de comprobarlo desde docs): en CF Zero Trust → Access → Policies → policy “Email staff” de la app “CreaRackSL Workspace”, confirmar que (a) la lista incluye dfuentes@esfericlabs.com y NO dfuentes@edomo.net, y (b) el email con el que Dani autentica realmente vía Google/GitHub OAuth coincide con el de la policy. Si Dani entra y recibe 403, casi siempre es este desajuste email-policy. (Nota: Dani verificado operativo al 100% el 15-07, task #199 — el riesgo residual es solo si se recrea la policy.)

Regla: cualquier alta/baja de miembro del staff toca esta policy. Mantener los 3 emails @esfericlabs.com alineados con la allowlist Resend (1.7 / email-routing) y con los onboardings.

1.7 Otros secretos críticos del workspace

2 · Matriz de dependencias plataforma → credencial

Permite responder rápido: “si rompo X, ¿qué deja de funcionar?”.

3 · Procedimientos de rotación / regeneración

3.1 Regenerar GH_PAT workspace (caso s76)

Cuándo: cuando alguna funcionalidad del workspace que llama a GitHub API empieza a dar 401/403/404. Caso típico: cambio de membresía Org, token expirado, scope insuficiente.

Pasos:

1. Ir a https://github.com/settings/personal-access-tokens/new (cuenta Esquembri, Owner del Org).
2. Configurar:
   • Token name: GH_PAT workspace (CF Pages)
   • Resource owner: CreaRackSL (Org, no User personal — crítico)
   • Expiration: 1 año
   • Repository access: Only select repositories → marcar los 3: CreaRack-Pro, CreaRackSL-workspace, claude-method
   • Repository permissions:
     • Metadata: Read
     • Contents: Read and write
     • Actions: Read
     • Issues: Read and write
     • Pull requests: Read
3. Si la Org requiere aprobación: aprobar en https://github.com/organizations/CreaRackSL/settings/personal-access-tokens-requests (auto-aprueba si eres Owner).
4. Subir a CF Pages env vars: pnpm wrangler pages secret put GH_PAT --project-name=crearacksl-workspace. Pegar el token cuando pida valor.
5. Disparar redeploy: push cualquier commit a main del workspace — el cron cf-pages-deploy de OPS lo despliega en ≤10 min. (El workflow “CF Pages Deploy” de Actions está disabled_manually — NO usarlo.)
6. Validar widget CI Pipeline del dashboard salud — debe mostrar 5/5 con color verde y “última: success”.

3.2 Regenerar WORKSPACE_REPO_TOKEN

Mismo procedimiento que 3.1 con scopes mínimos: solo Contents:Read + Metadata:Read sobre el repo CreaRackSL-workspace. Subir a gh secret set WORKSPACE_REPO_TOKEN --repo CreaRackSL/CreaRack-Pro y validar con gh workflow run audit-docs-drift.yml --repo CreaRackSL/CreaRack-Pro.

3.3 Re-añadir deploy key (caso s76)

Cuándo: cuando un cron de OPS falla con Repository not found o un workflow falla con ERROR: Repository not found / fatal: Could not read from remote repository. Causa típica: transferencia Org → deploy keys quedan enabled: false.

Pre-requisito: verificar que la Org tiene el toggle global activo:

gh api orgs/CreaRackSL | python -c "import sys,json; print('deploy_keys_enabled_for_repositories =', json.load(sys.stdin).get('deploy_keys_enabled_for_repositories'))"

Si devuelve False: gh api -X PATCH orgs/CreaRackSL -F deploy_keys_enabled_for_repositories=true.

Pasos para re-añadir la key (sin tocar la privkey que ya está en OPS /root/.ssh/github_*):

# 1. Listar keys actuales para obtener id y pubkey
gh api repos/CreaRackSL/<repo>/keys

# 2. Borrar la entry rota
gh api -X DELETE repos/CreaRackSL/<repo>/keys/<id>

# 3. Re-añadir con misma pubkey
gh api -X POST repos/CreaRackSL/<repo>/keys \
  -f title="crearack-ops (read-only)" \
  -f key="ssh-ed25519 AAAA... <comment>" \
  -F read_only=true

Validación (vía NetBird): ssh root@100.96.245.233 "cd /opt/<repo> && git pull" debe devolver “Already up to date” sin warnings (host aliases: github-crearack · github-workspace · github-claude-method).

3.4 Re-autorizar Zoho (per-user)

Ver runbook dedicado: [[runbook—zoho-integration-end-to-end]] sección “Autorizar mi cuenta Zoho”.

3.5 Rotar API key Anthropic / Google AI / Resend / Holded

Patrón común:

1. Crear nueva key en panel del proveedor (sin borrar la vieja todavía).
2. Subir a TODOS los almacenes donde se usa (mirar tabla 1.4 — varios servicios viven en 3+ sitios distintos: CF Pages env vars + GitHub Actions secrets + Dokploy env vars PROD + STAGE).
3. Disparar redeploys de cada plataforma (CF Pages: push a main → cron OPS · Dokploy: redeploy del servicio en panel).
4. Validar end-to-end con un caso real (mandar email test, generar 1 respuesta IA, listar 1 invoice, etc.).
5. Borrar la key vieja del panel del proveedor.

Footgun común: olvidar subir la key nueva a Dokploy STAGE o a uno de los entornos secundarios → funciona en uno y rompe en otro silenciosamente. Por eso el inventario por plataforma debe estar siempre completo.

3.6 Rotar Service Tokens CF Access

Fuente canónica: [[crearack-tech—guides—secret-rotation-playbook]] §9 — inventario de las 6 copias del secret a sincronizar (GH secrets ×2 repos · OPS · /opt/dr-backups/.cf-access STAGE · Dokploy PROD+STAGE · env vars User ×3) + registro de rotaciones. CF Zero Trust → Service Auth → Service Tokens → /rotate (mantiene el client-id). El token nuevo aparece UNA VEZ. Validar con curl explícito al endpoint protegido + redeploy del CreaRack-Pro. Recordar: la policy debe ser Service Auth, nunca Bypass (footgun s223).

4 · Auditoría rutinaria · script de verificación

Ejecutar mensualmente o tras incidente de plataforma. Cada comando debe devolver verde / lo esperado. (Última ejecución completa: 24-07-2026 ✅.)

# A) GitHub secrets de los 3 repos
gh secret list --repo CreaRackSL/CreaRackSL-workspace   # esperado: 9 (ver §1.4)
gh secret list --repo CreaRackSL/CreaRack-Pro           # esperado: 5 (ANTHROPIC, CF_ACCESS ×2, MCP_TOKEN, WORKSPACE_REPO_TOKEN)
gh secret list --repo CreaRackSL/claude-method          # esperado: vacío

# B) Deploy keys vivas (esperado: 1 por repo, "crearack-ops (read-only)", enabled)
gh api repos/CreaRackSL/CreaRack-Pro/keys | python -c "import sys,json; [print(k['title'], '·', 'enabled' if k['enabled'] else 'DISABLED') for k in json.load(sys.stdin)]"
gh api repos/CreaRackSL/CreaRackSL-workspace/keys | python -c "import sys,json; [print(k['title'], '·', 'enabled' if k['enabled'] else 'DISABLED') for k in json.load(sys.stdin)]"
gh api repos/CreaRackSL/claude-method/keys | python -c "import sys,json; [print(k['title'], '·', 'enabled' if k['enabled'] else 'DISABLED') for k in json.load(sys.stdin)]"

# C) Org toggle deploy keys (esperado: True)
gh api orgs/CreaRackSL | python -c "import sys,json; d=json.load(sys.stdin); print('deploy_keys_enabled =', d['deploy_keys_enabled_for_repositories'])"

# D) Apps instaladas en Org (esperado: cloudflare-workers-and-pages + dokploy ×2)
gh api orgs/CreaRackSL/installations | python -c "import sys,json; [print(i['app_slug'], '·', i['repository_selection']) for i in json.load(sys.stdin)['installations']]"

# E) Crons scheduled todos verdes (workspace · los migrados a OPS no aparecen aquí, ver F)
gh run list --repo CreaRackSL/CreaRackSL-workspace --limit 30 --json conclusion,event,workflowName,createdAt | python -c "
import sys, json
runs = json.load(sys.stdin)
scheduled = [r for r in runs if r['event'] == 'schedule']
by_wf = {}
for r in scheduled: by_wf.setdefault(r['workflowName'], r)
for wf, r in by_wf.items():
    flag = 'OK' if r['conclusion'] == 'success' else 'FAIL'
    print(f\"  [{flag}] {wf}: {r['conclusion']} at {r['createdAt']}\")
"

# F) OPS · crons y runners funcionando (vía NetBird; esperado: 7 crons de §1.2bis + logs frescos)
ssh root@100.96.245.233 "ls /etc/cron.d/ && tail -2 /opt/cron-heartbeat/cron-driver.log"

# G) STAGE · DR backups frescos (vía NetBird)
ssh root@100.96.254.204 "ls -lt /opt/dr-backups/ | head -5"

# H) PROD containers up (vía NetBird)
ssh root@100.96.156.31 "docker ps --format '{{.Names}}: {{.Status}}'"

# I) Smoke test endpoints públicos
curl -s -o /dev/null -w "PROD = %{http_code}\n" https://crearack.com/health
curl -s -o /dev/null -w "Workspace = %{http_code}\n" https://workspace.crearack.com    # esperado 302 (CF Access)
curl -s -o /dev/null -w "Esferic Labs = %{http_code}\n" https://esfericlabs.com         # esperado 200 (landing en vivo desde 10-07-2026)

Resultado esperado: todos los [OK] en E, crons presentes y heartbeat fresco en F, backups de hoy en G, contenedores Up X · healthy en H, HTTP esperados en I. Cualquier desviación = abrir incidente y volver a este doc para identificar la credencial afectada.

5 · Histórico · footguns conocidos y migraciones

6 · Quién debe leer este documento

• Edu — owner principal. Lo mantiene actualizado, lo consulta antes de cualquier rotación y al cierre del refresh-30d del Bibliotecario.
• Dani — lo lee para entender qué credenciales puede tocar sin riesgo (la mayoría requieren acción Edu, pero algunas — Zoho per-user, redeploys — son auto-servicio).
• Txell — solo las secciones relacionadas con billing (1.4 columna “Owner billing”) y el cross-link con [[entity—ops—catalogo-servicios-externos]]. Si una credencial caduca y bloquea facturación (Holded, Resend), Txell sabrá a qué panel ir.
• Cualquier sustituto temporal de los 3 (Regla 24 igualdad de accesos del staff) — este doc es punto de entrada al sistema de credenciales del proyecto. Junto al onboarding wiki, debe permitir tomar el relevo sin acceso previo a la memoria del equipo.

7 · Mantenimiento de este documento

• Lifecycle: refresh-30d. El Bibliotecario marca como pendiente de verificación cada 30 días. Edu valida sección por sección.
• Cuándo actualizar:
  • Cualquier rotación de credencial (anotar en sección 5 si el incidente fue significativo).
  • Nueva integración con proveedor externo (añadir a tablas 1.4, 2 y procedimientos 3).
  • Cambio de plan Org GitHub o Cloudflare que afecte permisos/toggles.
  • Tras cualquier auditoría exhaustiva ejecutar comandos sección 4 y confirmar estado.
• Cross-links a mantener vivos: [[entity—ops—catalogo-servicios-externos]] · [[runbook—zoho-integration-end-to-end]] · [[crearack-tech—admin—email-routing-architecture]] · [[crearack-tech—guides—secret-rotation-playbook]].

Véase también

• [[entity—ops—catalogo-servicios-externos]]
• [[runbook—zoho-integration-end-to-end]]
• [[crearack-tech—admin—email-routing-architecture]]
• [[crearack-tech—guides—secret-rotation-playbook]]
• [[decision—20260516—auditoria-simplificacion-servicios-auxiliares]]