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

Puerta de Decisión Authn/Authz + Arquitectura de Divulgación

Audience: Engineers implementing or reviewing MCP authentication, Audiencia: Ingenieros que implementan o revisan el comportamiento de autenticación, autorización y divulgación de errores de MCP.

Tabla de Contenidos

  1. Resumen Ejecutivo
  2. Contexto de Solicitud e Identidad
  3. Modos de Autenticación
  4. Autorización de Herramientas (Lista de Permisos)
  5. Autorización de Inquilino (Conectable)
  6. Medición de Uso y Cuotas (Conectable)
  7. Eventos de Auditoría de Autenticación
  8. Postura de Divulgación (JSON-RPC + HTTP)
  9. Limitación de tasa y respuestas de sobrecarga
  10. Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

La puerta de decisión MCP aplica una autenticación y autorización estrictas y de cierre por fallo para las llamadas a herramientas. La autenticación es consciente del transporte (stdio, HTTP, SSE) y se configura a través de server.auth. La autorización se aplica por cada llamada a la herramienta mediante DefaultToolAuthz, con listas de permitidos opcionales para herramientas. Una capa de autorización de inquilinos separada y conectable puede hacer cumplir el alcance de inquilinos/espacios de nombres antes de la ejecución de la herramienta. Las decisiones de autenticación emiten eventos de auditoría estructurados, y los fallos de solicitud se mapean a códigos de error JSON-RPC estables y códigos de estado HTTP para una divulgación determinista y etiquetado de métricas. F:crates/decision-gate-mcp/src/auth.rs L293-L372 F:crates/decision-gate-mcp/src/tools.rs L1436-L1454 F:crates/decision-gate-mcp/src/tools.rs L2857-L2878 F:crates/decision-gate-mcp/src/server.rs L1984-L2017

Contexto de Solicitud e Identidad

Contexto de la Solicitud

Las solicitudes entrantes se normalizan en un RequestContext que registra el transporte, la IP del par, el encabezado de autenticación, el sujeto del cliente y un identificador de solicitud opcional más metadatos de correlación. Para los transportes HTTP/SSE, el contexto se construye a partir del encabezado Authorization y el encabezado x-decision-gate-client-subject para la identidad del proxy mTLS. Los identificadores de correlación proporcionados por el cliente llegan a través de x-correlation-id y se tratan como entrada no segura: se validan estrictamente y se rechazan si son inválidos. El servidor siempre emite su propio x-server-correlation-id y lo devuelve en las respuestas, proporcionando un identificador estable y auditable incluso cuando los ID de cliente faltan o son rechazados. F:crates/decision-gate-mcp/src/auth.rs L82-L173 F:crates/decision-gate-mcp/src/server.rs L993-L1072 F:crates/decision-gate-mcp/src/server.rs L1648-L1734

Identidad Principal

AuthContext captura el método de autenticación más un sujeto explícito o una huella digital de token portador. Si una solicitud solo local no tiene sujeto, el sujeto se establece en stdio o loopback según el transporte. Para los tokens portadores, se calcula una huella digital sha256 y se utiliza como una etiqueta de identidad estable. F:crates/decision-gate-mcp/src/auth.rs L181-L216 F:crates/decision-gate-mcp/src/auth.rs L503-L517

Modos de Autenticación

El modo de autenticación se configura a través de server.auth.mode con listas de permitidos de apoyo:

  • local_only: se permite stdio; HTTP/SSE solo se permiten para IPs de loopback.
  • bearer_token: el token portador debe coincidir con server.auth.bearer_tokens.
  • mtls: subject must be present in x-decision-gate-client-subject and match mtls: el sujeto debe estar presente en x-decision-gate-client-subject y coincidir con server.auth.mtls_subjects cuando esté configurado.

Superficie de configuración:

Detalles de implementación:

  • Local-only rechaza HTTP/SSE no loopback.
  • Bearer tokens are parsed with size and scheme validation; invalid/missing Los tokens de portador se analizan con validación de tamaño y esquema; los encabezados inválidos/faltantes fallan en la autenticación.
  • mTLS requires a subject; unauthorized subjects are rejected. mTLS requiere un sujeto; los sujetos no autorizados son rechazados. F:crates/decision-gate-mcp/src/auth.rs L479-L552

Autorización de Herramientas (Lista Permitida)

La autorización de herramientas se aplica por solicitud mediante DefaultToolAuthz. Si server.auth.allowed_tools está configurado, cualquier herramienta que no esté en la lista de permitidos es rechazada con un error de no autorizado. Los nombres de herramientas inválidos en la lista de permitidos se tratan como una configuración de fallo cerrado (lista de permitidos vacía). F:crates/decision-gate-mcp/src/auth.rs L293-L372

Los resultados de autorización de herramientas son emitidos por el enrutador de herramientas:

Autorización de Inquilino (Conectable)

La autorización de inquilinos/nombres de espacio se aplica mediante un gancho TenantAuthorizer intercambiable. La implementación predeterminada permite todo el acceso, pero las implementaciones empresariales pueden proporcionar un autorizador que vincula a los principales con los ámbitos de inquilino y nombre de espacio. La autorización de inquilinos se ejecuta después de las verificaciones de lista blanca de herramientas y antes de la ejecución de la herramienta. Las denegaciones de inquilinos emiten eventos de auditoría dedicados (tenant_authz).

Referencias de implementación:

Medición de Uso y Cuotas (Conectable)

El control de uso y las verificaciones de cuotas son aplicados por un gancho UsageMeter intercambiable. La implementación predeterminada es una operación nula, pero las implementaciones empresariales pueden proporcionar un medidor que imponga cuotas y registre el uso de nivel de facturación. Las verificaciones de uso se ejecutan antes de la ejecución de la herramienta; las denegaciones emiten eventos usage_audit.

Referencias de implementación:

Eventos de Auditoría de Autenticación

Las decisiones de autenticación emiten eventos de auditoría JSON estructurados con detalles de transporte, sujeto, método y razón de fallo. El sumidero de auditoría predeterminado registra líneas JSON en stderr; las pruebas pueden utilizar un sumidero sin operación. F:crates/decision-gate-mcp/src/auth.rs L379-L445

Postura de Divulgación (JSON-RPC + HTTP)

Divulgación de Comentarios (scenario_next)

Las respuestas de scenario_next son solo un resumen por defecto. Los niveles de retroalimentación opcionales (trace, evidence) están regulados por la política server.feedback.scenario_next, con verificaciones de rol/sujeto resueltas a partir de server.auth.principals. La retroalimentación de evidencia aún se filtra a través de la política de divulgación de evidencia (los valores en bruto pueden ser redactados a menos que se permita explícitamente). F:crates/decision-gate-config/src/config.rs L452-L545 F:crates/decision-gate-mcp/src/tools.rs L2144-L2257

JSON-RPC Error Envelope

El servidor MCP responde utilizando códigos de error JSON-RPC y metadatos estructurados (kind, retryable, request_id, retry_after_ms opcional). Los tipos de error son etiquetas estables utilizadas para métricas y categorización de auditoría. F:crates/decision-gate-mcp/src/server.rs L1961-L2043

Mapeo de Errores (Errores de Herramienta)

Los errores de la herramienta se mapean a códigos de estado HTTP + códigos de error JSON-RPC:

ToolErrorHTTPJSON-RPC CodeMessage
No autenticado401-32001no autenticado
No autorizado403-32003no autorizado
Parámetros inválidos400-32602mensaje proporcionado
Violación de capacidad400-32602code: message
Herramienta desconocida400-32601herramienta desconocida
Respuesta demasiado grande200-32070mensaje proporcionado
Límite de tasa200-32071mensaje proporcionado
No encontrado200-32004mensaje proporcionado
Conflicto200-32009mensaje proporcionado
Evidencia200-32020mensaje proporcionado
Plano de control200-32030mensaje proporcionado
Ejecutar paquete200-32040mensaje proporcionado
Interno200-32050mensaje proporcionado
Serialización200-32060la serialización falló

Estos mapeos están implementados en jsonrpc_error. F:crates/decision-gate-mcp/src/server.rs L1984-L2015

Encabezado de Desafío de Autenticación (RFC 6750)

Las respuestas HTTP/SSE para solicitudes no autenticadas incluyen un encabezado WWW-Authenticate con un ámbito Bearer cuando la autenticación con token Bearer está habilitada. Esto se alinea con la RFC 6750 y mantiene los desafíos de autenticación explícitos sin filtrar detalles de validación del token. F:crates/decision-gate-mcp/src/auth.rs L46-L75 F:crates/decision-gate-mcp/src/server.rs L1706-L1718

Encabezados de Correlación

Las respuestas HTTP/SSE siempre incluyen un x-server-correlation-id emitido por el servidor. Si el cliente proporciona un x-correlation-id válido, se devuelve. Los IDs de correlación de cliente inválidos son rechazados antes del análisis de la solicitud y no se devuelven. El rechazo de correlación inválida utiliza HTTP 400 con el código de error JSON-RPC -32073 (invalid_correlation_id). F:crates/decision-gate-mcp/src/server.rs L993-L1072 F:crates/decision-gate-mcp/src/server.rs L1648-L1749

Fallos en el Análisis de Solicitudes

Las versiones de JSON-RPC no válidas, los métodos desconocidos y los cuerpos de solicitud mal formados son rechazados con códigos de error estándar de JSON-RPC y HTTP 400. F:crates/decision-gate-mcp/src/server.rs L1505-L1583

Limitación de tasa y respuestas de sobrecarga

El servidor impone:

  • Límites de solicitudes en vuelo (rechazar con 503 y -32072).
  • Limitación de tasa (rechazar con 429 y -32071, incluyendo sugerencias de reintento).
  • Límites de tamaño de carga útil (rechazar con 413 y -32070).

Estos fallos se informan con metadatos de error JSON-RPC estructurados y se marcan como reintentables cuando es apropiado. F:crates/decision-gate-mcp/src/server.rs L1505-L1568 F:crates/decision-gate-mcp/src/server.rs L2051-L2053

Referencia Cruzada Archivo por Archivo

ÁreaArchivoNotas
Superficie de configuración de autenticacióncrates/decision-gate-config/src/config.rsModos de autenticación, listas de permitidos de token/sujeto, lista de permitidos de herramientas.
Motor de políticas de autenticacióncrates/decision-gate-mcp/src/auth.rsDefaultToolAuthz, modos de autenticación, eventos de auditoría, análisis de tokens.
Integración de autenticación de herramientascrates/decision-gate-mcp/src/tools.rsAutorización por llamada + emisión de auditoría.
Interfaz de autorización de inquilinoscrates/decision-gate-mcp/src/tenant_authz.rsCostura de autorización de inquilinos/nombres de espacio intercambiable.
Interfaz de medición de usocrates/decision-gate-mcp/src/usage.rsCostura de medición de uso intercambiable + aplicación de cuotas.
Divulgación de JSON-RPCcrates/decision-gate-mcp/src/server.rsMapeo de errores y códigos de respuesta.