Grabadora Asset Core Puerta de Decisión
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

Decision Gate MCP impone una estricta autenticación y autorización de cierre en caso de 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 enchufable puede imponer el alcance de inquilinos/espacios de nombres antes de la ejecución de la herramienta. Las herramientas de ciclo de vida tipadas (typed_providers_import/register/list/get/activate/deprecate) ahora requieren campos de alcance de inquilinos/espacios de nombres explícitos y siempre enrutan el contexto de alcance a través de verificaciones de authz + espacio de nombres + medición de uso. typed_providers_import además requiere un mapeo explícito de credential_bindings para esquemas OpenAPI asegurados (locator + value_render), y el registro/importación de artefactos tipados rechaza perfiles de tiempo de ejecución que no son typed-runtime-v4. Se aplica un endurecimiento de importación de proyección primero en este límite: las respuestas complejas de objeto/array JSON sin x-decision-gate.projections son rechazadas, y los campos de solicitud heredados eliminados (como response_projection_mode) son rechazados como parámetros inválidos. La resolución de credenciales de tiempo de ejecución tipadas se basa en localizadores (secret:// y env:// restringido) con el backend de secreto local cifrado OSS como el resolutor por defecto. Los valores de credenciales se almacenan en bruto; se aplica un formato de cable determinista a partir de los metadatos de value_render de autenticación tipada en tiempo de ejecución. Las llamadas con alcance de proveedor ahora también pasan provider_id a la costura de autorización de inquilinos cuando está disponible (herramientas de ciclo de vida tipadas y evidence_query), lo que permite decisiones de RBAC a nivel de proveedor en autorizadores empresariales sin bifurcaciones OSS. Las decisiones de autorizació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 y etiquetado de métricas deterministas. F:crates/decision-gate-mcp/src/auth.rs L293-L372 F:crates/decision-gate-mcp/src/tools/router.rs L1436-L1454 F:crates/decision-gate-mcp/src/tools/router.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 desde server.auth.principals. La retroalimentación de evidencia todavía 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 permitan explícitamente). F:crates/decision-gate-config/src/config.rs L452-L545 F:crates/decision-gate-mcp/src/tools/router.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

Divulgación de Importación de OpenAPI Tipada

typed_providers_import y el registro de artefactos tipados devuelven fallos deterministas InvalidParams por violaciones de política/entrada:

  • unsupported OpenAPI security constructs include explicit taxonomy metadata (unsupported_code, texto de remediación) en mensajes de rechazo;
  • los campos credential_bindings faltantes y los mapeos de esquema asegurado vacíos son rechazados antes de la importación;
  • los perfiles de runtime que no son typed-runtime-v4 son rechazados antes de la registración.

F:crates/decision-gate-mcp/src/tools/router.rs L3798-L3830 F:crates/decision-gate-mcp/src/tools/router.rs L5112-L5160 F:crates/decision-gate-mcp/src/tools/router.rs L5259-L5263

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:

  • Inflight request limits (reject with 503 and -32072, kind inflight_limit, código de razón dg.server.inflight_limit_exhausted).
  • Rate-window limiting (reject with 429 and -32071, kind rate_limited, reason code dg.server.rate_limit_window_exhausted, including retry-after sugerencias).
  • Rate-limiter capacity saturation (reject with 503 and -32074, kind rate_limiter_capacity, reason code dg.server.rate_limiter_capacity_exhausted).
  • Límites de tamaño de carga útil (rechazar con 413 y -32070).

Los controles de ejecución saliente de proveedor tipado son independientes de los controles de ingreso de MCP y se aplican mediante políticas de tiempo de ejecución tipadas (outbound_max_inflight, reintentos limitados/retraso).

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 L1688-L1760 F:crates/decision-gate-mcp/src/server.rs L2150-L2250 F:crates/decision-gate-providers/src/typed.rs L448-L463 F:crates/decision-gate-providers/src/typed.rs L958-L980

Referencia Cruzada Archivo por Archivo

ÁreaArchivoNotas
Superficie de configuración de autenticacióncrates/decision-gate-config/src/config.rsModos de autenticación, listas permitidas de tokens/sujetos, lista permitida 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/router.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.