Administración
Esta página está orientada al administrador. El admin gestiona las credenciales de máquina (API keys) y las credenciales de dispositivo (MQTT) del sistema. Su poder es de sistema, usuarios, catálogos, reportes y auditoría — no operativo.
Por diseño (separación de funciones / least privilege), el administrador no aprueba, anula
ni emite nada del flujo de custodia o de laboratorio, y no edita ingeniería. No tiene
custody:issue, custody:void, manual:approve ni manual:void. Esas acciones de "segundo par
de ojos" son humanas (operador, supervisor, ingeniero), nunca del administrador ni de una
credencial de máquina. El admin administra las llaves; no las usa para operar.
Quién hace qué
| Superficie | Autoridad requerida | Quién |
|---|---|---|
API keys (/admin/api-keys) | admin:users | Admin |
Credenciales MQTT (/admin/devices/[id]/credentials) | admin:system | Admin |
Ambas pantallas son solo del administrador. Toda acción que realice queda registrada en el visor de auditoría (quién, qué, cuándo).
API keys
Las API keys son credenciales de máquina: permiten que un sistema externo (una
integración, un script, un agente) hable con la API de TankOS sin un usuario humano detrás. Se
gestionan en /admin/api-keys (solo admin:users).
La pantalla muestra la lista de API keys (ApiKeyRow): cada fila se expande en su lugar
para mostrar los detalles y el botón de revocar inline (RevokeInlineConfirm). Cuando no hay
ninguna clave, se muestra un estado vacío (EmptyState) con el CTA centrado. Arriba, el CTA
"Nueva clave" abre el diálogo de creación (CreateApiKeyDialog), donde se define un nombre
y se eligen los scopes mediante checkboxes (ScopeCheckboxList).
Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md
(/admin/api-keys lista con inline revoke).
Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md
(/admin/api-keys CreateApiKeyDialog abierto).
Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md
(/admin/api-keys EmptyState sin claves).
Scopes con allowlist de separación de funciones (SoD)
Los scopes asignables a una API key tienen una allowlist que prohíbe las autoridades
sensibles de separación de funciones (SoD). Una API key nunca puede recibir
custody:issue, custody:void, manual:approve ni manual:void — no existe forma de marcarlas
en el diálogo, y aunque se intentara forzar por API, hay un CHECK en la base de datos
(packages/contracts/src/auth/api-keys.ts) que lo rechaza.
El motivo es el corazón del flujo custody: emitir, anular y aprobar son acciones de "segundo par de ojos" humanas, no automatizables vía una credencial de máquina. Si una integración pudiera emitir tickets, se rompería la separación de funciones que garantiza la trazabilidad custody-grade. Ver la SoD del flujo de custodia en Tickets de custodia.
Copy-once de la clave generada
Al crear la API key, su valor secreto se muestra una única vez en pantalla. No hay endpoint de read-back: TankOS no almacena la clave en claro y no puede volver a mostrártela. Cópiala en el momento y guárdala en tu gestor de secretos. Si la pierdes, no hay forma de recuperarla: revócala y crea una nueva.
Para retirar una clave que ya no se usa o que se filtró, se usa el revocar inline dentro de su
fila (RevokeInlineConfirm) — la clave deja de autenticar de inmediato.
Credenciales MQTT (rotación)
Cada dispositivo (radar, sensor) publica su telemetría por MQTT con un usuario y una
contraseña propios. El admin rota esas credenciales desde /admin/devices/[id]/credentials
(solo admin:system), mediante un stepper de rotación de 4 pasos (4 pips).
Durante la rotación:
- El usuario MQTT se preserva —
dev-{tag}-{site}no cambia. Solo se rota la contraseña. - Se emite una nueva contraseña (CTA), mostrada en texto claro una sola vez
(
CredentialRotationClient, modal copy-once). - Una vez que el dispositivo adopta la nueva contraseña, se revoca la vieja (CTA de revocar con interlock 409 que impide dejar el dispositivo sin credencial activa).
Patrón two-secret (rotación sin downtime)
Para que el dispositivo no pierda conexión durante la rotación, TankOS usa un patrón two-secret: la credencial vieja y la nueva coexisten mientras el dispositivo migra. El dispositivo sigue publicando con la vieja hasta que adopta la nueva; solo entonces se revoca la vieja. Así no hay ventana de telemetría perdida. Este mismo patrón, junto con el ciclo de vida completo del dispositivo y su calibración, se documenta en detalle en Dispositivos y radares (manual de Ingeniería).
Igual que con las API keys, la nueva contraseña MQTT se muestra una única vez y no hay endpoint de read-back. Cópiala en el momento y configúrala en el dispositivo de inmediato. Si se pierde antes de aplicarla, hay que volver a rotar (emitir otra) — no se puede recuperar.
Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md
(/admin/devices/[id]/credentials stepper de rotación copy-once).
Toda acción admin queda auditada
Cada creación, revocación y rotación que realiza el administrador se escribe en el audit_log
(quién, qué entidad, antes/después). El admin no edita ni borra ese registro: lo investiga
desde el visor de auditoría, que es inmutable y se conserva
durante 7 años.
Páginas relacionadas
- Tickets de custodia — la separación de funciones del flujo custody que la allowlist de scopes refuerza.
- Auditoría — toda acción de administración queda registrada.
- Dispositivos y radares — ciclo de vida del dispositivo, calibración y el patrón de rotación de credenciales MQTT en detalle.
La guía por rol del administrador se publicará (próximamente).