Arquitectura y Robots Center

NORA es una plataforma RPA SaaS. Su arquitectura separa claramente dónde se decide qué ejecutar (la nube) de dónde se ejecuta de verdad (tu máquina). Esta página describe cada componente, cómo se conectan y el modelo de seguridad de tokens que protege tus credenciales.

Componentes

Componente	Dónde vive	Responsabilidad
Plataforma NORA / Robots Center	Nube (backend)	Orquesta: cola de jobs, procesos, máquinas, assets, colas (queues), releases firmados, auditoría. Es el plano de control.
Agente	En cada máquina (Windows o macOS)	Proceso de larga vida que se autentica contra el Robots Center, reclama jobs, descarga el robot, lo ejecuta como subproceso y reporta estado.
Máquina	Windows o macOS	El equipo donde corre el agente. Registrada en el Robots Center con una clave de máquina (`nora_mk_...`).
Robot / Paquete	Código Python subido a NORA	La automatización. Se empaqueta en un release firmado criptográficamente y se asocia a un proceso. El agente lo ejecuta.

Plano de control vs. plano de ejecución (datos)

La separación es deliberada y es la base del modelo de seguridad:

Plano de control (agente ↔ Robots Center): el agente usa su token de máquina (nora-agent, 24 h) para tareas operativas: reclamar el siguiente job, enviar heartbeat, reportar estado/logs/progreso, descargar releases. Este token nunca se entrega al robot.
Plano de ejecución / datos (robot ↔ Robots Center): el robot lee assets (secretos/credenciales) y opera colas. Para esto recibe un token de ejecución por job (nora-exec), corto y acotado, distinto del token de máquina.

El agente arranca el robot como un subproceso con un entorno mínimo (allowlist de variables del SO, no os.environ completo). Inyecta NORA_API_URL, NORA_JOB_ID y NORA_EXEC_TOKEN; excluye siempre la clave de máquina (NORA_MACHINE_KEY).

Flujo de orquestación

flowchart TD
    U["Usuario / API pública<br/>(X-API-Key: nora_ak_...)"] -->|dispara proceso| RC["Robots Center<br/>(nube / backend)"]
    RC -->|encola job| Q[("Cola de jobs")]
    A["Agente<br/>(en la máquina)"] -->|GET /agent/jobs/next<br/>token nora-agent| RC
    RC -->|job + exec_token + manifiesto| A
    A -->|descarga release firmado| RC
    A -->|ejecuta como subproceso<br/>inyecta NORA_EXEC_TOKEN| R["Robot<br/>(Python)"]
    R -->|lee assets / opera colas<br/>token nora-exec| RC
    A -->|status / logs / progreso<br/>token nora-agent| RC
    RC -->|estado en tiempo real| U

El usuario dispara un proceso desde la consola o con la API pública (POST /api/v1/jobs/trigger, cabecera X-API-Key: nora_ak_...). El Robots Center crea un job en cola. El agente, que sondea continuamente, lo reclama, descarga el release, verifica su firma y ejecuta el robot.

Modelo de seguridad de tokens

NORA usa tres audiencias de token JWT, separadas y validadas por endpoint:

Token	Audiencia (`aud`)	Vida	Para qué	Se entrega al robot
Máquina	`nora-agent`	24 h	Plano de control: poll de jobs, heartbeat, estado	No
Ejecución	`nora-exec`	Timeout del job + 5 min de gracia	Plano de datos: leer assets, operar colas	Sí
Desarrollo	`nora-dev`	Corta (por defecto 30 min)	CLI `nora dev` local; solo entornos no productivos	Sí (local)

Token de máquina (`nora-agent`)

El agente se autentica con su clave de máquina (nora_mk_...) en POST /agent/auth y recibe un JWT de máquina de 24 h. Este token solo sirve para el plano de control. Si la máquina se desactiva, el acceso se revoca de inmediato aunque el token siga dentro de su TTL.

Token de ejecución por job (`nora-exec`)

Cuando el agente reclama un job (GET /agent/jobs/next), el backend acuña un token de ejecución ligado a esa terna (máquina, job, proceso). Sus claims incluyen tenant_id, machine_id, job_id, process_id, envs y, si el proceso declara un manifiesto de assets (Process.required_assets), la lista assets permitida.

Propiedades de contención:

Caduca con el job. Al reportarse el job como completed/failed/cancelled, el token deja de ser usable: leer assets o colas después devuelve 401.
Acotado al manifiesto. Si el proceso declara assets, el token solo desbloquea esos; pedir otro asset devuelve 403. Igual para colas.
Aislamiento de entorno. Un token no puede leer assets de un entorno distinto al de sus claims. Los jobs gestionados leen production.

Aunque el nora-exec se filtrara, solo abre los recursos declarados y muere con el job: el robot no puede vaciar la bóveda de secretos del tenant.

Token de desarrollo (`nora-dev`)

Para desarrollo local con el CLI nora dev, el backend acuña un token corto restringido a entornos no productivos. Si sus claims incluyeran production, el backend lo rechaza. Así un desarrollador nunca lee secretos de producción desde su equipo.

Ciclo de vida de un job (poll / ejecución)

sequenceDiagram
    participant A as Agente
    participant RC as Robots Center
    participant R as Robot

    loop Plano de control (token nora-agent)
        A->>RC: POST /agent/heartbeat
        A->>RC: GET /agent/jobs/next
    end
    RC-->>A: job + exec_token (+ manifiesto)
    A->>RC: GET /agent/releases/{id}/download
    RC-->>A: ZIP firmado
    Note over A: Verifica la firma del release
    A->>R: ejecuta subproceso (inyecta NORA_EXEC_TOKEN)
    R->>RC: GET /agent/assets/{name} (token nora-exec)
    RC-->>R: valor descifrado (audita el acceso)
    R-->>A: termina
    A->>RC: PATCH /agent/jobs/{id}/status = completed
    Note over RC: el exec_token queda inservible

El agente verifica la firma criptográfica de cada release antes de ejecutarlo y rechaza releases sin firma válida (evita ejecución de código manipulado). Cada lectura de asset en runtime queda registrada en la auditoría con su contexto (job, proceso, máquina, tipo de token).

Glosario

Robots Center — el backend en la nube que orquesta todo. Es el plano de control. Ver conceptos.
Agente — proceso instalado en cada máquina que reclama y ejecuta jobs.
Máquina — equipo Windows/macOS registrado donde corre el agente.
Robot / Paquete — automatización en Python empaquetada como release firmado.
Proceso — configuración que asocia un release a una máquina y define su manifiesto de assets y timeout.
Job — una ejecución concreta de un proceso. Ver jobs.
Asset — credencial/secreto cifrado del tenant; los robots los leen con su token de ejecución.
Cola (queue) — estructura de items de trabajo que los robots consumen y producen.
Token de máquina / ejecución / desarrollo — ver autenticación.