Explica los límites de responsabilidad de la fuente de verdad de la configuración, las interfaces administrativas, las instantáneas locales por región, los bloqueos de emergencia y la coherencia de caché.
8. Modelo de datos
Se recomienda que el plano de control use el siguiente modelo relacional. Todas las claves primarias usan UUID, todos los tiempos usan UTC y la capa de presentación convierte las zonas horarias.
| Tabla | Campos clave | Restricciones clave |
|---|---|---|
merchants | id, external_ref, name, status, created_at | external_ref es globalmente único |
api_keys | id, merchant_id, public_key_id, environment, status, not_before, expires_at, created_at | public_key_id es globalmente único; clave foránea de comerciante no nula |
api_key_secret_versions | id, api_key_id, secret_digest, pepper_version, version, status, valid_from, valid_until | version única por Key; no conservar Secret en texto claro; clave foránea de versión Pepper no nula |
api_key_signing_keys | id, api_key_id, algorithm, public_key, status, valid_from, valid_until | Solo se permiten algoritmos asimétricos aprobados; no se reciben claves privadas |
api_key_client_certificates | id, api_key_id, certificate_fingerprint, issuer_ref, status, valid_from, valid_until | Vinculación única entre huella y Key; la cadena de certificados debe provenir de un emisor aprobado |
api_key_ip_bindings | id, api_key_id, ip_network, status, created_at | ip_network normalizada es única bajo la misma Key; se prohíbe solapamiento; aplica las restricciones de prefijo de la sección 5.3 |
scopes | id, scope_name, platform, resource, action, status | scope_name es globalmente único |
api_key_scopes | api_key_id, scope_id, granted_at, granted_by | Par Key y Scope único |
routes | id, route_name, environment, platform, method, path_rule, required_scope_id, service_capability_id, request_class, policy_version, status | Un CHECK de base de datos garantiza que una ruta publicada tenga required scope, entorno y declaración de capacidad de servicio |
merchant_region_policies | merchant_id, environment, primary_region, allowed_regions, failover_mode, version | Solo existe una política efectiva por comerciante y entorno |
service_capabilities | id, service_name, environment, read_consistency, max_replication_lag_ms, signal_max_age_seconds, supports_global_idempotency, automatic_read_failover, automatic_write_failover | Solo existe una declaración efectiva de capacidad por servicio y entorno; ampliar capacidades requiere aprobación |
service_endpoints | id, service_name, environment, region, endpoint_ref, health_policy, status | La combinación de servicio, entorno, región y referencia de endpoint es única |
control_plane_epochs | epoch, writer_region, lease_id, activated_at, fenced_previous_writer_at | Solo agregar; se debe registrar evidencia de vallado del primario anterior antes de asumir el control |
config_outbox | id, aggregate_type, aggregate_id, config_epoch, config_sequence, event_type, payload, published_at | ID de evento único; misma transacción que la escritura de configuración; versión comparada por epoch y sequence |
admin_audit_logs | id, actor_id, action, resource_type, resource_id, before_digest, after_digest, reason, created_at | Solo agregar; no se permite actualizar ni eliminar |
Se recomienda usar el tipo PostgreSQL inet para IP. secret_digest, diferencias de auditoría y payload de Outbox deben usar cifrado a nivel de columna o de disco; ningún payload puede contener Secret en texto claro.
9. Interfaces administrativas
Las interfaces administrativas solo pueden accederse desde la red interna de administración y utilizan tokens de acceso de corta duración del sistema de identidad corporativo. Se recomienda proporcionar las siguientes interfaces de recursos fijos:
| Método y ruta | Propósito | Entradas clave |
|---|---|---|
POST /admin/v1/api-keys | Crear una Key | merchant_id, environment, scopes, ip_bindings, expires_at, reason |
GET /admin/v1/api-keys | Consultar metadatos de Key por comerciante, estado o entorno | Criterios de consulta; no devuelve Secret ni resumen |
POST /admin/v1/api-key-rotations | Crear una nueva versión de Secret | api_key_id, overlap_hours, reason |
POST /admin/v1/api-key-signing-keys | Registrar la clave pública de firma de solicitudes del comerciante | api_key_id, algorithm, public_key, valid_until, reason |
POST /admin/v1/api-key-client-certificates | Vincular certificado de cliente mTLS | api_key_id, certificate_fingerprint, issuer_ref, valid_until, reason |
POST /admin/v1/api-key-suspensions | Suspender una Key | api_key_id, reason |
POST /admin/v1/api-key-revocations | Revocar permanentemente una Key | api_key_id, reason |
PUT /admin/v1/api-key-ip-bindings | Reemplazar atómicamente el conjunto de vinculaciones IP de una Key | api_key_id, ip_bindings, expected_version, reason |
PUT /admin/v1/api-key-scopes | Reemplazar atómicamente el conjunto de Scope de una Key | api_key_id, scopes, expected_version, reason |
POST /admin/v1/routes/validations | Validar una configuración de ruta pendiente de publicación | Configuración completa de ruta y versión destino |
POST /admin/v1/route-publications | Publicar una versión de ruta validada | route_id, expected_version, reason |
Todas las interfaces de escritura deben admitir identificador de solicitud idempotente, versión de bloqueo optimista y motivo de operación. La respuesta de reemplazo atómico de IP o Scope debe devolver el resumen del conjunto anterior y el nuevo número de versión para auditoría de operaciones erróneas y reversión controlada. Se prohíbe que proxies inversos, APM o middleware de auditoría registren respuestas de creación de Secret.
Las operaciones de alto riesgo incluyen creación de Key de producción, elevación de Scope, ampliación de redes IP, permitir escritura interregional y cambio de política de recuperación de revocaciones; se recomienda requerir aprobación de dos personas.
10. Caché y coherencia de configuración
10.1 Centro de publicación y operaciones de configuración
El centro de publicación y operaciones de configuración tiene dos rutas independientes entre sí. Los cambios ordinarios pasan por el plano de control de escritura única, PostgreSQL y Outbox; la ruta de solo denegación de emergencia utiliza una red, roles de identidad y firma protegida por hardware distintos, y puede restringir el acceso incluso cuando el plano de control ordinario no está disponible. La escritura de auditoría inmutable pertenece a este límite; el centro de observabilidad solo lee y correlaciona estos registros.
El proceso de publicación ordinaria es el siguiente:
- El plano de control actualiza la configuración y escribe un evento Outbox en la misma transacción PostgreSQL.
- El publicador envía el evento al bus de mensajes, y el evento contiene la versión de configuración
(epoch, sequence). - Los consumidores de cada región aplican los eventos de forma idempotente, comparan primero
epochy luegosequence, y rechazan que una versión anterior sobrescriba una nueva. - El servicio regional de validación de API Key mantiene una instantánea Redis y una caché breve en proceso.
- Cada región ejecuta periódicamente una conciliación completa de versiones y reconstruye la instantánea desde la fuente de verdad al detectar un hueco.
10.2 Prioridad de revocación
La revocación, suspensión y eliminación de IP son eventos de seguridad y deben pasar por un canal de alta prioridad, propagando la notificación de invalidación a todas las regiones. El objetivo recomendado es que el 99.9% de los cambios de seguridad entren en vigor en 10 segundos.
Si el bus de mensajes falla, cada región utiliza sondeo de versiones de ciclo corto como compensación. Para una Key nueva cuyo estado no pueda confirmarse o una Key no almacenada en caché, el plano de datos debe rechazar; no debe omitir la autorización para obtener disponibilidad.
10.3 Canal de solo denegación de emergencia
Cuando el plano de control o PostgreSQL no están disponibles, el personal de seguridad aún debe poder bloquear de inmediato una Key filtrada. Cada región proporciona una entrada de bloqueo de emergencia break-glass independiente y respeta las siguientes restricciones:
- La entrada solo permite añadir elementos de denegación para Key ID pública, ID de comerciante o IP de origen; no puede añadir elementos de permiso, ampliar permisos ni eliminar registros centrales de revocación.
- La instrucción se firma con una clave interna de firma de seguridad protegida por hardware; el servicio regional de validación de API Key valida primero la firma y después une el elemento de denegación a la configuración central.
- En condiciones normales se requiere la aprobación de dos personas de seguridad autorizadas; en un incidente de seguridad de máxima prioridad ya declarado, el comandante del incidente puede ejecutar primero y un segundo aprobador debe revisar en 15 minutos.
- El arrendamiento inicial de un elemento local de denegación regional es de 24 horas. Si el plano de control sigue no disponible, el personal de seguridad puede renovarlo mediante el mismo proceso de firma y aprobación; el servicio de validación de API Key alerta a 2 horas y 1 hora del vencimiento, y no debe restaurar automáticamente el permiso al vencer el arrendamiento mientras el plano de control no esté disponible y el elemento de denegación aún no se haya archivado formalmente. Después de recuperar el plano de control, debe convertirse en un registro formal de suspensión o revocación y no puede eliminarse antes de completar el archivo.
- Cada región escribe operador, aprobador, motivo, resumen de firma, hora de recepción y hora de vigencia en su almacenamiento local de auditoría solo de anexado.
- La entrada break-glass y la Gateway Admin API ordinaria usan rutas de red, roles de identidad y claves de firma diferentes, y se ejercitan una vez por trimestre.
10.4 Estrategia de degradación
| Fallo | Comportamiento |
|---|---|
| Base de datos principal PostgreSQL del plano de control no disponible | Se detienen las escrituras administrativas ordinarias; el plano de datos sigue dando servicio con la última instantánea validada; el bloqueo de emergencia usa el canal de la sección 10.3 |
| Bus de mensajes no disponible | El plano de control confirma la configuración pero la marca como pendiente de publicación; las regiones compensan mediante sondeo de versión; el cambio no se declara efectivo antes de completar la publicación |
| Redis regional no disponible | El servicio de validación de API Key utiliza una instantánea en proceso acotada; se rechazan Key desconocidas y Key que superan la vigencia de instantánea; la limitación distribuida se degrada a cubo de tokens local por instancia y cada instancia solo puede usar su porción de cuota alquilada antes del fallo y aún no vencida; la cuota de instancias nuevas es cero, por lo que la suma de las porciones de todas las instancias no puede superar la cuota global de ese comerciante o Key |
| Servicio de validación de API Key no disponible | La autenticación del gateway falla en modo cerrado y devuelve 503; no se omite la validación de permisos |
| Una instancia de backend no disponible | La comprobación de salud la retira y selecciona una instancia saludable dentro del mismo grupo de servicio |
| Toda una región de backend no disponible | Determina la conmutación por fallo o devuelve 503 según los requisitos previos de lectura y escritura de la sección 7.3 |
El tiempo máximo recomendado de uso sin conexión de la última instantánea validada es 15 minutos. Si no puede obtenerse una versión nueva después de ese tiempo, se deben rechazar solicitudes de escritura de alto riesgo; que las solicitudes de lectura continúen debe confirmarse por cada plataforma según clasificación de riesgo.