Arxi Puerta de Decisión Asset Core
Docs
Documentos de Decision Gate

Evaluación de puertas determinista, reproducible con decisiones auditables.

Documentación de Asset Core

Espacio de Nombres de Puerta de Decisión + Arquitectura RBAC/ACL del Registro

Audience: Engineers implementing or reviewing namespace policy, Asset Core namespace authority integration, and schema registry access control. This document is the canonical, implementation-aligned description of how Audiencia: Ingenieros que implementan o revisan la política de espacios de nombres, integración de la autoridad de espacio de nombres de Asset Core y control de acceso al registro de esquemas. Este documento es la descripción canónica, alineada con la implementación, de cómo Decision Gate (DG) hace cumplir los límites de los espacios de nombres y el RBAC/ACL del registro.

Tabla de Contenidos

  1. Resumen Ejecutivo
  2. Alcance y No Objetivos
  3. Conceptos y Tipos Fundamentales
  4. Namespace Policy
    1. Guardia de Espacio de Nombres Predeterminado
    2. Modos de Autoridad de Namespace
    3. Reglas de Mapeo del Núcleo de Activos
    4. Postura de Fallo
  5. Registry RBAC/ACL
    1. Resolución Principal
    2. Política de ACL incorporada
    3. Política de ACL personalizada
    4. Requisito de Firma
  6. Flujos de Decisión de Autorización
  7. Auditoría y Observabilidad
  8. Almacenamiento y Persistencia
  9. Invariantes de Seguridad
  10. Pruebas y Validación
  11. Referencia Cruzada Archivo por Archivo
  12. Documentación relacionada

Resumen Ejecutivo

Decision Gate impone el aislamiento de espacios de nombres y la autorización del registro de esquemas como fronteras de seguridad de primera clase. Todas las verificaciones de espacios de nombres y registros son cerradas por defecto y se ejecutan antes de cualquier mutación del estado del registro o del escenario. El sistema es intencionadamente conservador:

El RBAC/ACL del registro está limitado por inquilino + espacio de nombres + sujeto y puede ser configurado como integrado o personalizado. La política integrada está definida explícitamente por los nombres de los roles con control de clase de política para el acceso de escritura.F:crates/decision-gate-mcp/src/registry_acl.rs L218-L255

Alcance y No Objetivos

En alcance:

  • Validación de espacio de nombres en herramientas MCP.
  • Restricciones del espacio de nombres predeterminado.
  • Integración de la autoridad del espacio de nombres de Asset Core.
  • Política de RBAC/ACL del registro de esquemas y requisitos de firma.
  • Auditar y ejecutar el contexto de seguridad para estas decisiones.

Fuera de alcance (manejado en otro lugar o excluido intencionadamente):

  • Asset Core write-path gating (explicitly out of scope in the integration Control de la ruta de escritura de Asset Core (explícitamente fuera del alcance en el contrato de integración).
  • Control de acceso basado en roles a nivel de escenario o listas blancas de herramientas (cubierto en la documentación de autenticación del servidor).
  • Aplicación de la confianza del proveedor de evidencia (documentado en la guía de seguridad).

Conceptos y Tipos Fundamentales

Identificadores de Espacio de Nombres y Inquilinos

Los espacios de nombres y los inquilinos se tratan como identificadores explícitos llevados por las solicitudes de herramientas. El identificador de espacio de nombres predeterminado reservado es 1 y debe pasar verificaciones adicionales antes de que se realice cualquier operación.F:crates/decision-gate-mcp/src/tools.rs L162-L168 F:crates/decision-gate-mcp/src/tools.rs L2821-L2841

Registros del Registro de Esquemas

Las entradas del registro de esquemas son valores inmutables DataShapeRecord. Cada registro está delimitado por inquilino + espacio de nombres + id de esquema + versión, y puede incluir metadatos de firma opcionales (id de clave, firma, algoritmo opcional). F:crates/decision-gate-core/src/core/data_shape.rs L49-L72

Política de Espacio de Nombres

Guardián del Espacio de Nombres Default

El espacio de nombres predeterminado es un identificador reservado codificado de forma rígida (1). Su comportamiento es intencionadamente limitado:

  • If namespace.allow_default is false, all requests targeting the default Si namespace.allow_default es falso, todas las solicitudes dirigidas al espacio de nombres predeterminado son rechazadas.
  • If namespace.allow_default is true, namespace.default_tenants must be Si namespace.allow_default es verdadero, namespace.default_tenants debe ser no vacío y el llamador debe proporcionar un tenant_id en la lista de permitidos.
  • La protección del espacio de nombres predeterminado se aplica antes de las verificaciones de autoridad externa.

Implementación:

Modos de Autoridad de Namespace

La autoridad del espacio de nombres determina cómo DG valida la existencia del espacio de nombres:

ModoComportamientoFuente
noneNo verifica autoridades externas (política de espacio de nombres local de DG únicamente)NamespaceAuthorityMode::NoneF:crates/decision-gate-config/src/config.rs L1056-L1115
assetcore_httpValida el espacio de nombres a través de la API HTTP del daemon de escritura de Asset CoreNamespaceAuthorityMode::AssetcoreHttpF:crates/decision-gate-config/src/config.rs L1056-L1115 F:crates/decision-gate-mcp/src/namespace_authority.rs L67-L159

Cuando assetcore_http está habilitado, DG valida los espacios de nombres emitiendo una solicitud GET a /{base_url}/v1/write/namespaces/{resolved_id}. HTTP 200 = permitido; 404 o 401/403 = denegado; otros estados y errores de transporte se tratan como no disponibles (fallo cerrado). F:crates/decision-gate-mcp/src/namespace_authority.rs L130-L158

Las solicitudes de autoridad de Asset Core pueden incluir un token de portador opcional y un encabezado x-correlation-id derivado del encabezado de correlación proporcionado por el cliente que es inseguro cuando está disponible (retrocediendo al id de solicitud JSON-RPC o al id de correlación emitido por el servidor). Los IDs de correlación del cliente se validan estrictamente y se rechazan cuando son inválidos; solo se reenvían valores sanitizados a la autoridad del espacio de nombres para prevenir la inyección de encabezados y el engaño de registros.F:crates/decision-gate-mcp/src/tools.rs L2821-L2852 F:crates/decision-gate-mcp/src/namespace_authority.rs L103-L126 F:crates/decision-gate-mcp/src/server.rs L1648-L1657

Restricción de integración: el modo dev-permissive está prohibido cuando namespace.authority.mode = assetcore_http para evitar debilitar la seguridad del namespace en implementaciones integradas.F:crates/decision-gate-config/src/config.rs L580-L603

Reglas del Espacio de Nombres de Asset Core

Los identificadores de espacio de nombres son numéricos en todas partes (>= 1). La validación de autoridad de Asset Core es directa y no aplica ningún mapeo o traducción. Cualquier fallo de análisis produce un error de validación de espacio de nombres (fallo cerrado).F:crates/decision-gate-config/src/config.rs L1118-L1165 F:crates/decision-gate-mcp/src/namespace_authority.rs L130-L158

La validación de configuración impone los ajustes requeridos de Asset Core (URL base, rangos de tiempo de espera) cuando la autoridad de Asset Core está habilitada.F:crates/decision-gate-config/src/config.rs L1118-L1165

Postura de Fallo

Los fallos de autoridad del espacio de nombres se mapean de la siguiente manera:

  • Entrada de espacio de nombres no válida -> InvalidParams (error del llamador)
  • Autoridad denegada o no disponible -> Unauthorized (fallo cerrado)

Esto asegura que los espacios de nombres faltantes y las interrupciones en la parte superior se traten como fallos de acceso en lugar de rutas permitidas.F:crates/decision-gate-mcp/src/tools.rs L3217-L3222

Registro RBAC/ACL

Resolución Principal

La ACL del registro se basa en un principal derivado del contexto de autenticación MCP:

  • AuthContext.principal_id() resolves to subject, token fingerprint, or a AuthContext.principal_id() se resuelve en sujeto, huella digital del token o una etiqueta de respaldo estable (local/token/mtls).
  • Principal profiles are configured in server.auth.principals, each with Los perfiles principales se configuran en server.auth.principals, cada uno con una clase de política opcional y vinculaciones de roles.
  • Role bindings can be globally scoped or restricted to a tenant and/or Las vinculaciones de roles pueden tener un alcance global o estar restringidas a un inquilino y/o un espacio de nombres.

Referencias de implementación:

Política de ACL Incorporada

La política incorporada es la predeterminada (schema_registry.acl.mode = builtin). El comportamiento es intencionadamente conservador y se basa en nombres de roles canónicos:

Leer (Lista/Obtener) permitido cuando el principal tiene cualquiera de:

  • TenantAdmin, NamespaceOwner, NamespaceAdmin, NamespaceWriter, TenantAdmin, NamespaceOwner, NamespaceAdmin, NamespaceWriter, NamespaceReader, SchemaManager

Escribir (Registrar) permitido cuando:

  • TenantAdmin, NamespaceOwner o NamespaceAdmin; O
  • SchemaManager y la clase de política no es prod

Si no se proporciona una clase de política, se trata como prod (cerrar en caso de fallo para las escrituras de SchemaManager).F:crates/decision-gate-mcp/src/registry_acl.rs L218-L283

Política de ACL Personalizada

La política personalizada (schema_registry.acl.mode = custom) evalúa las reglas en orden y devuelve la primera coincidencia. Una regla coincide cuando todas las dimensiones no vacías coinciden:

  • acción
  • inquilino
  • espacio de nombres
  • sujeto (id principal)
  • roles (coincidencia de rol limitado)
  • clase de política

Si no hay reglas que coincidan, se aplica el efecto predeterminado (allow o deny). F:crates/decision-gate-mcp/src/registry_acl.rs L287-L339 F:crates/decision-gate-config/src/config.rs L1723-L1812

Requisito de Firma

El ACL del registro puede requerir metadatos de firma de esquema:

Flujos de Decisión de Autorización

Flujo de Aplicación de Espacios de Nombres (Todas las Herramientas con Ámbito de Espacio de Nombres)

Request
  -> Tool auth (DefaultToolAuthz)
  -> ensure_namespace_allowed
     -> default namespace guard
     -> namespace authority check (optional)
  -> tool execution

El guardia del espacio de nombres predeterminado se ejecuta antes de las verificaciones de autoridad para prevenir cualquier retroceso o bypass implícito.F:crates/decision-gate-mcp/src/tools.rs L2821-L2841

Flujo de ACL del Registro (schemas_register/list/get)

Request
  -> Tool auth (DefaultToolAuthz)
  -> ensure_namespace_allowed
  -> ensure_registry_access
     -> resolve principal (auth context -> profile)
     -> evaluate registry ACL (builtin or custom)
     -> emit registry audit event
  -> validate signing metadata (optional)
  -> registry mutation or read

Referencias de implementación:

Auditoría y Observabilidad

DG emite registros de auditoría explícitos para decisiones de acceso al registro y cambios en la postura de seguridad:

  • RegistryAuditEvent captures tenant, namespace, action, allow/deny decision, reason, principal roles, schema identity, and correlation identifiers (unsafe RegistryAuditEvent captura inquilino, espacio de nombres, acción, decisión de permitir/denegar, razón, roles del principal, identidad del esquema y identificadores de correlación (cliente inseguro + emitido por el servidor) para la trazabilidad de auditoría. F:crates/decision-gate-mcp/src/audit.rs L112-L145
  • SecurityAuditEvent records dev-permissive activation (and invalid correlation rejections) along with namespace authority posture; correlation identifiers are included when the event is tied to a request. SecurityAuditEvent registra la activación permisiva para desarrolladores (y rechazos de correlación inválidos) junto con la postura de autoridad del espacio de nombres; los identificadores de correlación se incluyen cuando el evento está vinculado a una solicitud. F:crates/decision-gate-mcp/src/audit.rs L204-L223 F:crates/decision-gate-mcp/src/server.rs L1739-L1749
  • Runpack exports embed RunpackSecurityContext with dev-permissive and namespace authority metadata, making security posture verifiable offline. Runpack exporta RunpackSecurityContext con metadatos de autoridad de espacio de nombres y permisos de desarrollo, lo que hace que la postura de seguridad sea verificable sin conexión. F:crates/decision-gate-core/src/core/runpack.rs L94-L104 F:crates/decision-gate-mcp/src/server.rs L534-L543

Almacenamiento y Persistencia

Los registros del esquema de registro incluyen metadatos de firma de extremo a extremo:

  • DataShapeRecord incluye campos de firma opcionales.
  • SQLite registry persists signing metadata in dedicated columns and migrates El registro de SQLite persiste los metadatos de firma en columnas dedicadas y migra la versión del esquema de 3 a 4 para añadir las columnas de firma.

Referencias:

Invariantes de Seguridad

  1. Fail-closed namespace enforcement: Invalid, unknown, or unreachable namespace authority always denies access. Aplicación de espacio de nombres de fallo cerrado: La autoridad de espacio de nombres inválida, desconocida o inalcanzable siempre deniega el acceso. F:crates/decision-gate-mcp/src/namespace_authority.rs L130-L158 F:crates/decision-gate-mcp/src/tools.rs L3217-L3222
  2. No implicit default namespace: id 1 requires explicit allowlist and tenant match; otherwise denied. Sin espacio de nombres predeterminado implícito: el id 1 requiere una lista de permitidos explícita y coincidencia de inquilino; de lo contrario, se deniega el acceso. F:crates/decision-gate-config/src/config.rs L1025-L1052 F:crates/decision-gate-mcp/src/tools.rs L2821-L2841
  3. Asset Core integration is strict: Asset Core config is required when namespace.authority.mode = assetcore_http, and dev-permissive is disallowed when using Asset Core authority. La integración de Asset Core es estricta: La configuración de Asset Core es requerida cuando namespace.authority.mode = assetcore_http, y se desautoriza el modo dev-permissive al utilizar la autoridad de Asset Core. F:crates/decision-gate-config/src/config.rs L580-L603 F:crates/decision-gate-config/src/config.rs L1118-L1165
  4. Registry ACL is authoritative: Tool allowlists do not bypass registry ACL; registry access is enforced and audited for every registry action. La ACL del registro es autoritativa: Las listas de herramientas permitidas no eluden la ACL del registro; el acceso al registro se aplica y audita para cada acción del registro. F:crates/decision-gate-mcp/src/tools.rs L2881-L2910
  5. Local-only registry access is explicit: schema_registry.acl.allow_local_only defaults to false. When enabled, the built-in ACL can allow loopback/stdio subjects to bypass principal mapping; this does not apply to custom ACL rules. El acceso al registro solo local es explícito: schema_registry.acl.allow_local_only tiene como valor predeterminado false. Cuando está habilitado, el ACL integrado puede permitir que los sujetos de bucle invertido/stdio eviten el mapeo de principales; esto no se aplica a las reglas de ACL personalizadas. F:crates/decision-gate-config/src/config.rs L1768-L1785 F:crates/decision-gate-mcp/src/registry_acl.rs L218-L230
  6. Schema signing enforcement is explicit: When enabled, signing metadata is mandatory for registry writes. La aplicación de la firma del esquema es explícita: Cuando está habilitada, la firma de los metadatos es obligatoria para las escrituras en el registro. F:crates/decision-gate-mcp/src/tools.rs L3032-L3041

Pruebas y Validación

Las capas de registro y espacio de nombres deben ser validadas tanto a nivel de unidad como de sistema. La cobertura recomendada incluye:

  • Mapeo de autoridad de espacio de nombres (explícito vs numérico) y comportamiento de fallo cerrado.
  • Aplicación de la lista de permitidos del espacio de nombres por defecto.
  • Matriz de ACL del registro incorporado (lectura/escritura por rol y clase de política).
  • Precedencia de coincidencia de ACL personalizada + efectos predeterminados.
  • Aplicación requerida de firma y persistencia de metadatos de firma.

Los huecos en las pruebas del sistema se rastrean en system-tests/test_gaps.toml y deben ser mantenidos junto con los cambios en estas políticas.

Referencia Cruzada Archivo por Archivo

ÁreaArchivoNotas
Configuración y validación de espacio de nombrescrates/decision-gate-config/src/config.rsPolítica de espacio de nombres + configuración y validación de autoridad de Asset Core.
Aplicación de espacio de nombres y autoridad por defectocrates/decision-gate-mcp/src/tools.rsensure_namespace_allowed y mapeo de errores de espacio de nombres.
Integración de autoridad de espacio de nombrescrates/decision-gate-mcp/src/namespace_authority.rsValidación HTTP, reglas de mapeo, semántica de fallo cerrado.
Motor de ACL de registrocrates/decision-gate-mcp/src/registry_acl.rsMapeo de principales + evaluación de ACL incorporada/personalizada.
Aplicación de ACL de registrocrates/decision-gate-mcp/src/tools.rsensure_registry_access + emisión de auditoría + comprobaciones de firma.
Identificadores de principales de autenticacióncrates/decision-gate-mcp/src/auth.rsIDs de principales estables para mapeo de ACL.
Esquemas de eventos de auditoríacrates/decision-gate-mcp/src/audit.rsCargas útiles de auditoría de registro + seguridad.
Contexto de seguridad de Runpackcrates/decision-gate-core/src/core/runpack.rsMetadatos de seguridad incrustados en runpacks.
Persistencia del registro de esquemascrates/decision-gate-store-sqlite/src/store.rsColumnas de metadatos de firma y migraciones.