Saltar a contenido

ADR-008 · Sudo como Firma Electrónica Simple (FES)

Fecha: 2026-04-09 Source: /srv/projects/cis/cis-plan/DECISIONS.md (do not edit here — re-split desde la fuente)

Contexto: Durante la sesión del 2026-04-09, al configurar cis-auth (Authentik), el usuario explicó la arquitectura objetivo: cada operación privilegiada (sudo, ejecución MCP, modificación financial, firma de documentos) debe quedar legalmente trazable como firma electrónica simple según la Ley 19.799 de Firma Electrónica (Chile).

La firma electrónica simple requiere tres elementos: 1. Identidad verificable del firmante — provisto por cis-auth (Authentik) con auth multi-factor 2. Voluntad expresa de firmar — provisto por un segundo factor (OTP/SMS/liveness) en firmasydocumentos.cl 3. Integridad del documento/acción — provisto por hash SHA256 de estado pre/post + timestamp

Alternativas consideradas:

  1. Firma Electrónica Avanzada (FEA) — requiere certificado digital emitido por entidad acreditada (~$30-50 USD/año). Legalmente más fuerte (equivale a firma manuscrita notariada). Demasiado costoso y lento para uso interno diario.

  2. Sin firma, solo audit log — registro append-only de acciones. No tiene peso legal; no protege en disputas.

  3. Firma Electrónica Simple (FES) ← elegida. Costo cero, suficiente para actos privados entre partes que conocen el sistema, y escalable. Se usa para toda acción interna. Para documentos que requieran FEA (facturas electrónicas reales al SII, contratos con terceros), se complementa con certificado digital en el futuro.

Decisión: Todo sudo, ejecución MCP de alto riesgo, firma de documentos y aprobación financial dentro del ecosistema CIS pasa por un flow de firma electrónica simple orquestado por dos servicios:

identidad              →  verificación de acción  →  ejecución + audit
────────────              ───────────────────────     ────────────────
cis-auth (Authentik)     firmasydocumentos.cl        cis-core (MCP)
(auth.innovacionsantiago  (firmasydocumentos.cl)     cis-admin (audit)
 .cl)

Flow completo:

1. Usuario en cis-admin solicita acción
   → cis-admin valida permisos vía cis-auth JWT

2. cis-admin evalúa si la acción requiere FES
   → sí para: sudo, modificar DB, firmar doc, aprobar pago >X
   → no para: lectura, búsqueda, edición de drafts

3. Redirect a firmasydocumentos.cl con:
   {
     action_id: UUID,
     action_summary: "Reiniciar servicio cis-inbox",
     state_hash: SHA256(estado_previo),
     return_url: "https://admin.innovacionsantiago.cl/actions/{id}",
     jwt_identity: <cis-auth JWT>
   }

4. firmasydocumentos.cl verifica segundo factor:
   - Email OTP (default)
   - SMS OTP (opcional)
   - TOTP authenticator
   - WebAuthn / Passkey
   - Liveness test (futuro: face match)

5. Al verificar exitosamente, firmasydocumentos.cl genera:
   signed_receipt = JWT {
     iss: "firmasydocumentos.cl",
     sub: <persona_id>,
     aud: "cis-admin",
     action_id: UUID,
     action_summary: "...",
     state_hash: "...",
     otp_method: "email",
     verified_at: <timestamp>,
     legal_weight: "simple",
     jti: UUID,
   }
   firmado con private key RS256 de firmasydocumentos.cl

6. cis-admin valida signed_receipt (verifica signature, expiry, audience)

7. cis-admin ejecuta la acción vía cis-core MCP:
   POST https://core.innovacionsantiago.cl/ops/execute
   { action: ..., receipt: signed_receipt }

8. cis-core:
   a) Valida receipt
   b) Ejecuta sudo / cambio
   c) Escribe en tabla `acciones` con signature_receipt completo
   d) Devuelve confirmación con hash post-acción

9. cis-admin devuelve a usuario:
   - Success/Fail
   - Link permanente al receipt (verificable públicamente)

Esquema de datos (ver docs/architecture/DATA-MODEL.md sección 2.6):

CREATE TABLE acciones (
    id UUID PRIMARY KEY,
    persona_id UUID NOT NULL,
    org_id UUID NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    action_type TEXT NOT NULL,
    target TEXT,
    payload_hash TEXT,
    authentik_session_id TEXT NOT NULL,
    fyd_verification_id UUID,
    otp_method TEXT,
    ip_origin INET,
    legal_weight TEXT DEFAULT 'none',  -- 'none' | 'simple' | 'avanzada' | 'cualificada'
    signature_receipt TEXT  -- JWT completo devuelto por firmasydocumentos.cl
);

Consecuencias:

  • Legales: toda acción privilegiada genera evidencia legal utilizable en disputas (Ley 19.799 Art. 3 y 4).
  • UX: cada sudo toma +30s a +2min (dependiendo del factor). Trade-off aceptable para acciones privilegiadas. Acciones de lectura no pasan por FES.
  • Arquitectura: 3 servicios deben estar UP para que el sistema funcione (cis-auth, firmasydocumentos, cis-core). Si alguno cae, las acciones privilegiadas se suspenden. Riesgo aceptado — cis-auth y cis-core son locales al VPS.
  • firmasydocumentos.cl: es un servicio nuevo que hay que construir (Bloque 5 del BACKLOG). Hasta que exista, los sudos se ejecutan con aprobación simple vía core-server MCP (current state) y se migra gradualmente.
  • Clave privada de firma: firmasydocumentos.cl necesita una RSA key pair. Se genera al deploy y se guarda en vault project=firmasydocumentos. Rotación anual.
  • Verificación pública: los receipts son JWT firmados — cualquiera con la public key (publicada en https://firmasydocumentos.cl/.well-known/jwks.json) puede verificar.
  • Expansión futura: cuando hayamos comprado certificado digital avanzado, migrar a FEA es añadir un método "advanced" al stage de verificación en firmasydocumentos.cl.

Implementación:

  • Bloque 5 del BACKLOG: cis-sign o firmasydocumentos (mismo servicio, dos nombres — elegir firmasydocumentos porque ya está en CF).
  • Dependencia previa: cis-auth ✓ (hecho hoy), cis-admin (Bloque 3), cis-core (Bloque 1.5)
  • OIDC client firmasydocumentos ya registrado en cis-auth con client_id FHvOEJMnTLCptdD0MUY03mHkHfEVnV1Ge10chS4m.

Referencias legales:

  • Ley 19.799 sobre Documentos Electrónicos, Firma Electrónica y Servicios de Certificación (Chile)
  • Art. 3: "Los actos y contratos otorgados o celebrados por personas naturales o jurídicas, suscritos por medio de firma electrónica, serán válidos de la misma manera y producirán los mismos efectos que los celebrados por escrito y en soporte de papel"
  • Art. 4: define firma electrónica simple vs avanzada
  • Reglamento: Decreto Supremo 181 de 2002, Ministerio de Economía