Autenticación de Decision Gate, Política y Arquitectura de Divulgación

Audiencia: Ingenieros que implementan o revisan el comportamiento de autenticación, autorización y divulgación de errores de MCP.

Tabla de Contenidos

Resumen Ejecutivo
Contexto de Solicitud e Identidad
Modos de Autenticación
Visibilidad de la herramienta y política de llamadas
Autorización de Espacio de Nombres (Enchufable)
Medición de Uso y Cuotas (Conectable)
Eventos de Auditoría de Autenticación
Postura de Divulgación (JSON-RPC y HTTP)
Limitación de tasa y respuestas de sobrecarga
Anclajes de Implementación Archivo por Archivo

Resumen Ejecutivo

Decision Gate MCP impone una autenticación estricta y de cierre en caso de fallo, y una política de autorización de propiedad separada. La autenticación es consciente del transporte (stdio, HTTP, SSE), configurada a través de server.auth, y es propiedad de RequestAuthenticator. RequestAuthenticator recibe solo la identidad de la solicitud; no recibe una acción de herramienta y no puede convertirse en un segundo propietario de la política de herramientas. ToolVisibilityResolver es el único propietario de la política de descubrimiento e invocación de herramientas estáticas, configurada por server.tools. Una capa de autorización de espacio de nombres separada y enchufable impone el alcance del espacio de nombres antes de la ejecución de la herramienta. Cada llamada semántica admitida pasa su espacio de nombres exacto a la costura de autorización. El perfil inicial no tiene autoridad de llamada de herramienta con alcance de proveedor ni autoridad de consulta de evidencia independiente. La evidencia del llamador entra solo a través de los transportes de prechequeo/evaluación del escenario; las afirmaciones de origen y garantía son construidas por el servidor, no aceptadas de los campos del llamador. El tiempo nombrado, el entorno inmutable y la adquisición de documentos enraizados utilizan autoridades locales registradas por el operador y la relación de enlace propiedad del escenario en lugar de RBAC con alcance de proveedor. 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 y etiquetado de métricas deterministas. Internamente, MCP ahora retiene la identidad simbólica/numerada exacta respaldada por un catálogo más códigos públicos seguros para auditoría y telemetría, manteniendo la proyección externa de JSON-RPC en primer lugar. Los artefactos de autoridad DG generados bajo Docs/generated/decision-gate/ congelan esas semánticas de error y telemetría OSS en forma legible por máquina para que las herramientas de verificación privada consuman contratos de propiedad DG en lugar de inferirlos ad hoc a partir de detalles de implementación. F:crates/decision-gate-mcp/src/auth.rs L293-L372 F:crates/decision-gate-mcp/src/tools/policy.rs L266-L281 F:crates/decision-gate-mcp/src/tools/policy.rs L36-L72 F:crates/decision-gate-mcp/src/server.rs L1984-L2017

Alcance y No Objetivos

El alcance es la identidad de ingreso de MCP, autenticación, autorización, ganchos de autorización de espacio de nombres, divulgación, auditoría y manejo de sobrecarga. Este documento no define la colocación del espacio de nombres, la propiedad del evaluador, el cercado o la replicación; el alcance de autorización es distinto de esas futuras responsabilidades del plano de control.

Responsabilidades de Capa

El ingreso normaliza la identidad de transporte no confiable y los metadatos de solicitud.
La autenticación establece el contexto principal.
ToolVisibilityResolver y la autorización de espacio de nombres deciden si una solicitud puede ejecutarse.
La divulgación y la auditoría proyectan el resultado sin debilitar la decisión.

Contexto de Solicitud e Identidad

Contexto de la Solicitud

Las solicitudes entrantes se normalizan en un RequestContext que registra el transporte, IP del par, encabezado de autenticación y metadatos opcionales de identidad de solicitud autorizada/llamador. Para transportes HTTP/SSE, el único portador de credenciales de aplicación es el encabezado Authorization. Los sujetos de certificado afirmados por el llamador no son un canal de identidad admitido. La procedencia proporcionada por el llamador llega a través de x-caller-request-id y se trata como entrada insegura: se valida estrictamente y se rechaza si es inválida. El servidor siempre emite su propio UUIDv7 canónico x-request-id y lo devuelve en las respuestas, proporcionando un identificador estable y auditable incluso cuando falta la procedencia del llamador. MCP además rastrea el id de JSON-RPC por mensaje como un campo de contexto de solicitud interno, pero ese identificador de protocolo se mantiene separado tanto de la procedencia del llamador como del ID de solicitud del servidor autorizado. No se devuelve como un encabezado HTTP/SSE y no reemplaza los canales de identidad de solicitud de auditoría o telemetría. 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 es un portador de principal sellado y etiquetado. Sus variantes vinculan un sujeto local derivado del transporte o un resumen de token portador canónico directamente al método de autenticación correspondiente; los llamadores no pueden construir campos de opción desajustados o un contexto “autenticado” anónimo/mal formado. La admisión local asigna el sujeto exacto stdio o loopback del transporte. La admisión de portador almacena el ContentDigest sha256 tipado, y la identidad de ACL/uso se proyecta solo desde esa variante sellada. No hay un principal de respaldo fabricado para un estado inválido. 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:

local_only: se permite stdio; HTTP/SSE solo se permiten para IPs de loopback.
bearer_token: el material del verificador de token de portador debe resolverse desde cada referencia secreta configurada en server.auth.bearer_tokens antes de la publicación.

Superficie de configuración:

server.auth.mode, bearer_tokens y principals. F:crates/decision-gate-config/src/config.rs L789-L937

Detalles de implementación:

Local-only rechaza HTTP/SSE no loopback.
Las referencias de secreto de portador se resuelven atómicamente al inicio; la materia prima es limitada, validada, hasheada en resúmenes de verificación y descartada. Las credenciales de solicitud se analizan con validación de tamaño y esquema y se comparan contra cada resumen de verificación sin un oráculo de coincidencia de salida anticipada.
TLS del servidor protege el transporte. No acuña la identidad de la aplicación. F:crates/decision-gate-mcp/src/auth.rs L479-L552

Visibilidad de la herramienta y política de llamadas

ToolVisibilityResolver es el único propietario de la política de herramientas estáticas. Los conjuntos server.tools.allowlist y server.tools.denylist rigen tanto tools/list como la invocación directa. Una herramienta que no es invocable se proyecta como UnknownTool, impidiendo el descubrimiento a través de diferentes divulgaciones de llamada/lista. Los nombres de herramientas desconocidas y los conjuntos de políticas sobredimensionados fallan en la admisión de configuración. La superficie eliminada server.auth.allowed_tools no tiene un alias de analizador ni un puente en tiempo de ejecución; su presencia es un error de campo desconocido. F:crates/decision-gate-mcp/src/tools/visibility.rs F:crates/decision-gate-config/src/config.rs

Los resultados de autenticación son emitidos por el enrutador de herramientas antes de la política de herramientas:

AuthAuditEvent::allowed en caso de éxito
AuthAuditEvent::denied en caso de fallo F:crates/decision-gate-mcp/src/tools/policy.rs F:crates/decision-gate-mcp/src/auth.rs

Descripción del flujo/secuencia principal

El servidor normaliza el contexto de la solicitud y rechaza la entrada de identidad malformada.
La autenticación establece un principal o rechaza la solicitud.
La política de herramientas, la autorización de espacio de nombres y las verificaciones de cuota aplicables se ejecutan antes del efecto secundario de la herramienta.
El resultado es auditado y proyectado a través de la política de divulgación JSON-RPC/HTTP.

Autorización de Espacio de Nombres (Intercambiable)

La autorización de espacio de nombres se impone mediante un gancho NamespaceAuthorizer enchufable. La implementación independiente permite solo la autenticación local que lleva un recibo de gobernanza de autenticación duradero y requiere contexto de espacio de nombres para cada herramienta que lleva espacio de nombres. Las implementaciones empresariales suministran un autorizador que vincula a los principales a los alcances de espacio de nombres.

Las políticas de permitir y denegar son variantes disjuntas de NamespaceAuthzDecision. La falta de obtención de una decisión autoritativa es un NamespaceAuthorizationError separado que preserva la cadena de origen exacta; el enrutador registra un evento de denegación de cierre y devuelve el fallo de autoridad en lugar de etiquetarlo incorrectamente como una denegación de política. Si esa auditoría de denegación requerida también falla, ambas fallas se preservan en un error de herramienta compuesto. La autorización de espacio de nombres se ejecuta después de las verificaciones de política de herramientas estáticas y antes de la ejecución de la herramienta. Todos los resultados emiten eventos de auditoría dedicados (namespace_authz).

Referencias de implementación:

Interfaz de autorización de espacio de nombres: F:crates/decision-gate-mcp/src/namespace_authz.rs L29-L65
Aplicación y emisión de auditoría: F:crates/decision-gate-mcp/src/tools/policy.rs L36-L119

Medición de Uso y Cuotas (Conectable)

La medición de uso y las verificaciones de cuota se aplican mediante un gancho UsageMeter intercambiable. La composición OSS admitida utiliza el mismo sumidero de gobernanza duradera que la auditoría de solicitudes; los marcadores de no-op explícitos rechazan cada operación y no pueden satisfacer el cableado de inicio duradero. Las implementaciones empresariales suministran el adaptador de cuota de plataforma. Las reservas de uso se ejecutan antes de la ejecución de la herramienta; los rechazos emiten eventos usage_audit. Una admisión sellada retiene el principal autenticado. La resolución rechaza la sustitución de principal, comete un resolution_attempt distinto, solicita a la autoridad de cuota la transición idempotente y emite resolution_finalized solo después de la confirmación de la autoridad. La costura de uso recibe tres entradas de identidad distintas: la procedencia del llamador (caller_request_id), la identidad de solicitud del servidor autoritativo (request_id), y un idempotency_key de llamada a herramienta dedicado. Decision Gate deriva esa clave de idempotencia del id JSON-RPC normalizado cuando está disponible, retrocediendo al request_id del servidor solo cuando el mensaje de protocolo no lleva un identificador JSON-RPC utilizable. Los identificadores JSON-RPC seguros pasan directamente; los identificadores inseguros se transforman de manera determinista en jsonrpc-sha256:<hex> para preservar el comportamiento de cuota/idempotencia empresarial que falla en cerrado sin filtrar la identidad JSON-RPC en los encabezados de transporte, IDs de solicitud de auditoría o IDs de solicitud de telemetría.

Referencias de implementación:

Interfaz de medición de uso: F:crates/decision-gate-mcp/src/usage.rs L28-L105
Aplicación y emisión de auditoría: F:crates/decision-gate-mcp/src/tools/policy.rs L121-L213

Eventos de Auditoría de Autenticación

Las decisiones de autenticación emiten eventos de auditoría estructurados mcp_request_authentication con contexto de acción, transporte, sujeto, método y detalles de fallo. La acción identifica la operación intentada en evidencia; no es una entrada a la política de autenticación. El sumidero de auditoría predeterminado registra líneas JSON en stderr; las pruebas pueden usar un sumidero no operativo. F:crates/decision-gate-mcp/src/auth.rs L379-L445

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

Divulgación de Evaluación de Etapas

scenario_evaluate_stage devuelve la vista de ejecución aceptada, no los valores de observación en bruto. El material de intento/evidencia permanece en la historia aceptada y en las familias de ejecución según la política de divulgación de evidencia. scenario_precheck_stage devuelve solo el resultado semántico y el rastro para la evidencia local enviada por el llamador o explícita y no hace ninguna afirmación de progreso aceptado. La configuración de retroalimentación de cursor eliminada no tiene un alias de compatibilidad.

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. Internamente, el servidor también retiene un código público seguro de proyección, un código de razón opcional y una identidad exacta canónica en el objeto de error para sumideros de auditoría/telemetría, pero esos campos no se serializan en el cable JSON-RPC público por defecto. La proyección pública de MCP permanece en Docs/generated/decision-gate/mcp_errors.json, mientras que la fuente de completitud canónica OSS más rica es ahora Docs/generated/decision-gate/error_catalog.json. F:crates/decision-gate-mcp/src/server.rs L1268-L1283 F:crates/decision-gate-mcp/src/server.rs L1672-L1707 F:crates/decision-gate-mcp/src/server.rs L2140-L2198 F:crates/decision-gate-mcp/src/audit.rs L48-L78 F:crates/decision-gate-mcp/src/telemetry.rs L102-L120

Artefactos de Autoridad de Telemetría

Decision Gate publica eventos de telemetría generados y artefactos de autoridad de operador-seam:

Docs/generated/decision-gate/telemetry_event_catalog.json
Docs/generated/decision-gate/telemetry_operator_seams.json

Estos artefactos se generan a partir de manifiestos de origen de propiedad de DG en crates/decision-gate-contract/catalogs/ y congelan códigos de evento y costuras de operador de alto riesgo que se espera que la gobernanza de observabilidad proteja. La identidad de la familia de métricas, etiquetas, texto de ayuda, unidades, tipo, cardinalidad y perfiles de cubo de histograma son propiedad de un catálogo de telemetría de plataforma suministrado por el espacio de trabajo de integración; esa autoridad externa no es una ruta de repositorio de Decision Gate, y DG no debe llevar un espejo de catálogo de métricas que contenga filas.

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:

ToolError	HTTP	Código JSON-RPC	Mensaje
No autenticado	401	-32001	no autenticado
No autorizado	403	-32003	no autorizado
Parámetros inválidos	400	-32602	mensaje proporcionado
Violación de capacidad	400	-32602	`code: message`
Herramienta desconocida	400	-32601	herramienta desconocida
Respuesta demasiado grande	200	-32070	mensaje proporcionado
Límite de tasa	200	-32071	mensaje proporcionado
No encontrado	200	-32004	mensaje proporcionado
Conflicto	200	-32009	mensaje proporcionado
Evidencia	200	-32020	mensaje proporcionado
Plano de control	200	-32030	mensaje proporcionado
Ejecutar paquete	200	-32040	mensaje proporcionado
Autoridad de límite de tasa	200	-32050	autoridad de límite de tasa fallida
Interno	200	-32050	mensaje proporcionado
Serialización	200	-32060	la serialización falló

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

Respaldo de Identidad Exacta

El mapeo JSON-RPC sigue siendo el contrato público estable, pero ahora está respaldado por identidades exactas de propiedad del catálogo. Las variantes de ToolError enrutadas y los rechazos de ingreso del servidor se resuelven primero a identidades simbólicas/númericas canónicas OSS y solo luego se proyectan en la taxonomía JSON-RPC pública. F:crates/decision-gate-mcp/src/tools/error.rs L126-L189 F:crates/decision-gate-mcp/src/server.rs L2270-L2307

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 Identidad de Solicitud

Las respuestas HTTP/SSE siempre incluyen un UUIDv7 canónico en minúsculas y con guiones emitido por el servidor en x-request-id. Si el llamador proporciona un x-caller-request-id válido, se devuelve como procedencia del llamador, pero nunca reemplaza el identificador de solicitud del servidor autoritativo. Los IDs de solicitud de llamador inválidos son rechazados antes del análisis de la solicitud y no se devuelven. El rechazo utiliza HTTP 400 con el código de error JSON-RPC -32073 (invalid_caller_request_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

decision-gate-mcp::rate_limit es el único propietario de Decision Gate del algoritmo de ventana fija en proceso. La entrada de MCP y los documentos empresariales con alcance de cuenta proporcionan diferentes tipos de claves y políticas externas, pero no poseen copias del reloj, cubo, desalojo, contador o relación de publicación. La política admitida sella el conteo de solicitudes no cero, la ventana y la capacidad de clave y prueba que el horizonte de retención de dos ventanas es representable antes de que un limitador pueda existir.

Para una clave k, política (m, w, c), muestra monotónica serializada t, y estado retenido S, la admisión es una transición determinista parcial step(S, k, t) -> Result<(S', Allow | Limited(retry)), E>. Una transición exitosa publica el estado completo siguiente y avanza un marcador de agua monotónico global. El fallo de sincronización, la regresión del reloj, el agotamiento de capacidad, el fallo del contador o el fallo de proyección de reintento no publican estado. Cualquier resto de reintento positivo de menos de un milisegundo se proyecta al piso público nombrado de un milisegundo; no puede convertirse en una pista de reintento cero.

El servidor impone:

Límites de solicitudes en curso (rechazar con 503 y -32072, tipo inflight_limit, código de razón dg.server.inflight_limit_exhausted).
Limitación de ventana de tasa (rechazar con 429 y -32071, tipo rate_limited, código de razón dg.server.rate_limit_window_exhausted, incluyendo sugerencias de retry-after).
Saturación de capacidad del limitador de tasa (rechazar con 503 y -32074, tipo rate_limiter_capacity, código de razón dg.server.rate_limiter_capacity_exhausted).
Límites de tamaño de carga útil (rechazar con 413 y -32070).

La autoridad de ventana fija posee un mapa acotado más una marca de agua monótona publicada globalmente. Solo toma muestras después de serializar el acceso, valida el orden del reloj y cada cálculo falible antes de la publicación, y deja el estado exacto anterior sin cambios en la regresión del reloj, agotamiento de capacidad, fallo aritmético o sincronización envenenada. Por lo tanto, la reordenación ordinaria del programador no puede clasificarse erróneamente como regresión del reloj, mientras que cambiar las claves de atribución no puede ocultar una regresión real.

La adquisición local tiene su propia operación validada y presupuesto de concurrencia. El perfil inicial no contiene ninguna ruta de adquisición de red saliente.

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/rate_limit.rs F:crates/decision-gate-mcp/src/server.rs

Invariantes

La identidad de solicitud no confiable nunca se convierte en autoritativa sin validación.
La autenticación/autorización faltante o denegada falla en cierre antes del trabajo de la herramienta.
La autorización de espacio de nombres es una decisión de acceso, no una decisión de colocación.
La divulgación preserva errores públicos estables sin exponer detalles sensibles.

Modos de Fallo y Matriz de Recuperación

Modo de fallo	Comportamiento de fallo cerrado	Recuperación
Identidad de solicitud inválida	Rechazar antes de la autorización/ejecución de la herramienta.	Corregir la entrada del llamador.
Autenticación no disponible o denegada	Rechazar solicitud.	Restaurar configuración de autenticación/backend o credenciales.
Autorización de espacio de nombres no disponible	Denegar solicitud con alcance de espacio de nombres.	Restaurar autoridad y reintentar.
Límite de tasa/uso excedido	Devolver respuesta estructurada reintentable donde sea aplicable.	Esperar o restaurar capacidad/cuota.

Anclajes de Implementación Archivo por Archivo

Área	Archivo	Notas
Superficie de configuración de Auth	`crates/decision-gate-config/src/config.rs`	Modos de autenticación, listas de permitidos de tokens/sujetos, lista de permitidos de herramientas.
Motor de política de autenticación	`crates/decision-gate-mcp/src/auth.rs`	DefaultRequestAuthenticator, modos de autenticación, eventos de auditoría, análisis de tokens.
Integración de autenticación de herramientas	`crates/decision-gate-mcp/src/tools/router.rs`	Autorización por llamada + emisión de auditoría.
Interfaz de autorización de espacio de nombres	`crates/decision-gate-mcp/src/namespace_authz.rs`	Costura de autorización de espacio de nombres enchufable.
Interfaz de medición de uso	`crates/decision-gate-mcp/src/usage.rs`	Medición de uso enchufable + costura de aplicación de cuotas.
Autoridad de solicitud de ventana fija	`crates/decision-gate-mcp/src/rate_limit.rs`	Política sellada, estado monotónico, retención limitada y publicación atómica.
Divulgación de JSON-RPC	`crates/decision-gate-mcp/src/server.rs`	Mapeo de errores y códigos de respuesta.

Prueba y Trazabilidad de Contratos

La autenticación, la autorización de espacio de nombres, la divulgación y las pruebas del servidor bajo crates/decision-gate-mcp/ cubren el contrato de ingreso actual.
Los artefactos de contrato generados congelan proyecciones de error y telemetría públicas.

Ganchos de Preparación Operativa

Monitorear denegaciones de autenticación, denegaciones de autorización de espacio de nombres, rechazos de cuota, y categorías de error seguras para la divulgación.
Un camino de autorización saludable no prueba la colocación del evaluador o la propiedad del escritor; esos requieren evidencia de celda de espacio de nombres futura separada.

Reglas de Mantenimiento

Preservar la distinción entre el alcance de autorización y la autoridad de colocación.
Actualizar los artefactos de contrato generados cada vez que el texto de divulgación pública o el esquema cambien.

Declaración de Delta del Modelo de Amenaza

Modelo de Amenaza Delta: ninguno para esta corrección de terminología; no se cambió la política de ingreso ni el comportamiento de autorización en tiempo de ejecución.