Integració del Proveïdor de Decision Gate + Arquitectura del Registre de Capacitats

Audience: Engineers implementing provider integration or capability Audiència: Enginyers que implementen la integració de proveïdors o la validació de capacitats per a consultes de verificació, condicions i evidències.

Taula de continguts

Visió Executiva
Configuració del Proveïdor
Registre de Capacitats
Contracts de Proveïdors Externs
Federació de Proveïdors d’Evidències
Tool-Level Enforcement
Bloqueig de Contracte Typed REST/OpenAPI V3
File per Fitxer Referència Creuada

Executive Overview

Decision Gate dóna suport a tres tipus de proveïdors:

Proveïdors integrats (compilats en el binari)
Proveïdors MCP externs (transport stdio o HTTP)
Proveïdors tipats (capacitat precompilada + artefactes de perfil d’execució)

Els contractes de capacitat del proveïdor són l’esquema autoritatiu per als paràmetres de comprovació, resultats i comparadors permesos. El registre de capacitats valida les especificacions d’escenaris i les consultes d’evidència abans de l’avaluació. La federació d’evidències dirigeix les consultes als proveïdors i aplica les polítiques de confiança. F:crates/decision-gate-config/src/config.rs L1883-L1990 F:crates/decision-gate-mcp/src/capabilities.rs L229-L379 F:crates/decision-gate-mcp/src/evidence.rs L138-L210

Configuració del proveïdor

La configuració del proveïdor es defineix en ProviderConfig:

tipus: integrat, mcp, o tipificat
command / url: selecció de transport per a proveïdors MCP
capabilities_path: ruta JSON del contracte (requerida per a proveïdors MCP/typed)
runtime_profile_path: ruta JSON del perfil d’execució tipat (requerida per a proveïdors tipats)
typed_protocol: selector de protocol de temps d’execució tipat (openapi_http o grpc)
auth.bearer_token: autenticació del proveïdor opcional
trust: substitució de confiança per proveïdor
allow_raw: opt-in per a la divulgació d’evidències en brut
timeouts: temps d’espera per a la connexió i les sol·licituds HTTP

Els controls de descoberta es defineixen a provider_discovery:

allowlist / denylist: restringir quins contractes de proveïdor es divulguen
max_response_bytes: mida màxima de la resposta de descoberta

La validació imposa:

Els proveïdors de MCP han de especificar command o url i capabilities_path.
Typed providers must specify capabilities_path, runtime_profile_path, i typed_protocol.
allow_insecure_http és necessari per a URLs http://.
Els noms dels proveïdors són únics i es retallen.
Els identificadors integrats (time, env, json, http, rest) estan reservats; els proveïdors MCP no poden utilitzar-los.
Built-ins must use a reserved identifier and reject MCP-only fields (command, url, Els identificadors integrats han d’utilitzar un identificador reservat i rebutjar els camps només MCP (command, url, allow_insecure_http, auth, capabilities_path).
Els proveïdors de MCP rebutgen els camps només de tipus (runtime_profile_path, typed_protocol).
Typed providers reject MCP-only fields (command, url, allow_insecure_http, auth) i càrregues útils config incorporades.

F:crates/decision-gate-config/src/config.rs L1883-L1990

Registre de Capacitats

El registre de capacitats carrega contractes de proveïdors i compila esquemes JSON per a comprovar paràmetres i resultats. Valida:

Proveïdor i comprovar existència
Presència de paràmetres requerits
Conformitat amb l’esquema de paràmetres
Conformitat amb l’esquema de valor esperat
Llistes blanques de comparadors
Anchor types declared by provider contracts (e.g., file_path_rooted for the Tipus d’ancoratge declarats pels contractes del proveïdor (per exemple, file_path_rooted per al proveïdor json integrat)
Rebuig de duplicats check_id (fail-closed; sense semàntica d’escriptura silenciosa)

F:crates/decision-gate-mcp/src/capabilities.rs L313-L379 F:crates/decision-gate-mcp/src/capabilities.rs L598-L636

Les consultes del registre de capacitats són utilitzades tant per les eines de definició d’escenaris com per les eines de consulta d’evidències. F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2050 F:crates/decision-gate-mcp/src/tools/router.rs L979-L1017

Contracts de Proveïdors Externs

Els proveïdors externs han de subministrar un fitxer JSON de contracte que:

Coincideix amb l’identificador del proveïdor configurat
Declares transport matching provider type:
- Proveïdors MCP: transport = "mcp"
- Proveïdors tipificats: transport = "typed"
Define comprovacions amb llistes de comparadors permeses

Els contractes són limitats en mida i validats per ruta; els contractes invàlids fallen tancats. Per a les importacions OpenAPI tipades, comprova que allowed_comparators es sintetitzin a partir de l’esquema de resultat normalitzat utilitzant la matriu de classes de tipus de comparador estricte i l’ordenació canònica de comparadors. F:crates/decision-gate-mcp/src/capabilities.rs L533-L591 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L109 F:crates/decision-gate-typed/src/openapi/comparator_derivation.rs L52-L114

Federació de Proveïdors d’Evidències

La federació d’evidències combina proveïdors integrats i proveïdors MCP:

Els integrats es registren a través del registre de proveïdors.
Els proveïdors MCP es creen amb transport stdio o HTTP.
Typed providers are instantiated from runtime profile artifacts and execute comprovacions definides pel perfil a través del proveïdor d’execució tipat.
El registre de proveïdors rebutja registres duplicats per evitar sobrescriptures silencioses.
Stdio provider processes are terminated on drop to avoid orphaned provider Els processos del proveïdor Stdio es finalitzen en caiguda per evitar temps d’execució orfes del proveïdor durant l’apagat o la desinstal·lació de proves.
Les polítiques del proveïdor (trust + allow_raw) s’apliquen per proveïdor.
Evidence results may include structured error metadata (code, message, Els resultats d’evidència poden incloure metadades d’error estructurat (code, message, details) per suportar bucles de recuperació deterministes.
HTTP evidence providers enforce timeouts, disallow redirects, apply response size limits, fail closed on truncated bodies (Content-Length mismatch), pin DNS resolution per request, and deny private/link-local peers by default a menys que s’hagi optat explícitament.
The built-in REST provider reuses the same HTTP security controls and adds GET-only extraction checks (json_path, header) plus header/auth hygiene aplicació per a noms d’encapçalament gestionats per l’autenticació i reservats.
The typed runtime provider applies the same hardened HTTP controls for openapi_http execution, enforces profile digest integrity, validates response status/content-type against profile policy, and emits deterministic anclatges que utilitzen metadades de perfil.
Typed lifecycle catalog semantics now exist in OSS compile tooling to support profile version registration, activation, rollback, and digest drift detection (decision-gate-typed), and OSS lifecycle tool plumbing is active via typed_providers_import, typed_providers_register, typed_providers_list, typed_providers_get, typed_providers_activate, i typed_providers_deprecate.
Typed runtime resolution now includes a resolver seam (TypedProfileResolver) keyed by (tenant_id, namespace_id, provider_id). Default OSS behavior resolves from scoped in-memory lifecycle state and falls back to static typed profile config entries. Resolver calls now snapshot the resolver handle before invocation so runtime la resolució no s’executa mentre es manté el mutex de resolució interna.
Built-in REST runtime now includes policy evaluator seams (RestPolicyEvaluator) for egress host/scheme decisions and auth-scheme decisions. Deny paths return deterministic reason codes.

F:crates/decision-gate-mcp/src/evidence.rs L138-L210 F:crates/decision-gate-mcp/src/evidence.rs L248-L266 F:crates/decision-gate-providers/src/http.rs L82-L239 F:crates/decision-gate-providers/src/rest.rs L124-L570 F:crates/decision-gate-typed/src/lifecycle.rs L1-L286

La política de confiança (verificació de signatures) s’executa per resposta del proveïdor. F:crates/decision-gate-mcp/src/evidence.rs L636-L677

Tool-Level Enforcement

El comportament de l’eina imposa la política de capacitat i divulgació:

scenario_define valida l’especificació contra les capacitats abans de registrar.
evidence_query valida les consultes i aplica la política de redacció d’evidències en brut.
evidence_query execution is offloaded to a blocking task to isolate evidence_query s’executa en una tasca bloquejant per aïllar proveïdors bloquejants (HTTP) del temps d’execució asíncron de MCP.
provider_contract_get / provider_check_schema_get apply disclosure policy and provider_contract_get / provider_check_schema_get s’apliquen a la política de divulgació i retornen contractes de proveïdor canònics o esquemes de comprovació.
Typed lifecycle tools (typed_providers_import/register/list/get/activate/deprecate) require explicit tenant_id + namespace_id scope fields and provide deterministic scoped artifact registration, active-version selection, rollback-aware deprecation, digest drift status inspection, and bounded typed import/runtime security limits (timeout_ms, max_response_bytes, outbound_max_inflight, retry bounds, and allowlist cardinality). typed_providers_import requires an explicit credential_bindings field on every request ({} for unauthenticated imports) and explicit secured-scheme-to-credential_binding mappings for secured OpenAPI imports. Cada mapeig assegurat requereix tant metadades de renderització de localitzador com de valor de cable.
Provider-scoped authz context now includes provider_id for typed lifecycle tools and evidence_query, enabling provider-level enterprise authorization política a la costura tenant-authz.
Comparator allow-lists are enforced from provider contracts; json.path Les llistes blanques de comparadors s’apliquen a partir dels contractes dels proveïdors; json.path exposa tota la superfície del comparador per a proves JSON deterministes.

F:crates/decision-gate-mcp/src/tools/router.rs L1106-L1236 F:crates/decision-gate-mcp/src/tools/router.rs L1238-L1298 F:crates/decision-gate-mcp/src/tools/router.rs L3173-L3940 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L127-L210 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L213-L452 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L455-L544

Contracte de bloqueig Typed REST/OpenAPI V4

Aquesta secció és el bloqueig de decisió a nivell d’arquitectura per al comportament del proveïdor OSS de tipus REST/OpenAPI. És intencionadament estable, de manera que el moviment de fulls de ruta/arxius no canviï el contracte actiu.

Importació de bloqueig de frontera (OSS V4):

OpenAPI version policy accepts 3.0.x and 3.1.x; other versions fail tancat.
External ref mode is local_file_only in OSS runtime behavior. Network ref els camins d’execució es processen per a la classificació de polítiques però es rebutgen.
Unsupported or ambiguous constructs must fail closed with deterministic metadades de mapeig/remediació de taxonomia.
Unsupported taxonomy and remediation metadata are single-source and enum-backed (OpenapiUnsupportedCode + OpenapiImportErrorKind), not message-substring acoblat.
Unsupported taxonomy fixture parity is enforced by typed importer unit proves de contracte, bloquejant la desviació de fixtures/implementacions en CI.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L301 F:crates/decision-gate-typed/src/openapi/refs.rs L22-L394 F:crates/decision-gate-typed/src/openapi/errors.rs L12-L212 F:crates/decision-gate-typed/src/openapi/errors.rs L447-L558 F:crates/decision-gate-typed/tests/openapi_unsupported_taxonomy_contract.rs L1-L105

Síntesi/bloqueig d’execució (OSS V4):

Projection-first synthesis is mandatory for JSON object/array-complex les respostes: els esquemes han de declarar x-decision-gate.projections.
OpenAPI import emits one check per declared projection entry per estat/mitjà tupla; l’entrada llegat response_projection_mode s’ha eliminat.
json_only media support remains default unless explicit overrides són proporcionats.
Runtime request binding supports path, query, header, cookie, and objectius body opcionals amb conflictes de fallada tancada i comprovacions d’higiene.
L’extracció en temps d’execució continua estant restringida per l’estat/tipus de contingut i falla tancada.
Runtime profile profile_version is hard-locked to typed-runtime-v4; older les versions de perfil són rebutjades.
TypedOperationProfile always carries required operation-effective auth alternatives; la recuperació d’autenticació a nivell de proveïdor no forma part del model d’execució.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L248 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L242 F:crates/decision-gate-typed/src/runtime_codegen.rs L42-L93 F:crates/decision-gate-providers/src/typed.rs L687-L799

Auth + bloqueig de credencials (OSS V4):

Effective security is resolved per operation:
- operation.security substitueix security de nivell superior.
- security: [] significa operació no autenticada.
- L’objecte de requisit buit ({}) contribueix a una alternativa no autenticada.
Supported requirement shapes:
- Un requisit que conté un esquema suportat.
- Multiple alternatives where each alternative contains exactly one supported esquema.
Supported schemes remain http bearer/basic and apiKey in header|query|cookie.
Credential locators are explicit and scheme-locked:
- secret://... es resol a través del backend de secrets OSS xifrat local.
- env://... is development-only and disabled unless dev.allow_dev_env_credentials=true.
- Els noms de variables d’entorn sense format i els esquemes de localització desconeguts són rebutjats.
Credential values are canonical raw secrets; runtime applies explicit value_render metadata (identity or deterministic prefix) before header/query/injecció de cookies.
apiKey alternatives retain exact OpenAPI-derived name and location; no els noms d’API de clau fixa sintètica s’utilitzen en temps d’execució.
Import requires an explicit credential_bindings field and explicit credential_binding mapping input for every referenced secured scheme; els camps/mapeigs que falten fallen tancats.
Unsupported security types/schemes and unsupported requirement shapes (oauth2, openIdConnect, unsupported http schemes, unsupported apiKey locations, multi-scheme AND, missing scheme refs, malformed security els objectes) fallen tancats amb una taxonomia determinista.

F:crates/decision-gate-typed/src/openapi/security_mapping.rs L11-L216 F:crates/decision-gate-typed/src/openapi/errors.rs L125-L155 F:crates/decision-gate-providers/src/typed.rs L789-L904 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L55-L163

Resiliència de sortida + bloqueig de límits (OSS V3):

Runtime security policy includes per-provider outbound inflight caps and bounded retry policy (max_attempts, initial_backoff_ms, max_backoff_ms).
Runtime retries are deterministic and limited to timeout/429/503, with suport Retry-After limitat quan s’codifica com a segons.
La importació/registre rebutja els límits/reintents de sortida mal formats.

F:crates/decision-gate-contract/src/types.rs L403-L439 F:crates/decision-gate-providers/src/typed.rs L448-L463 F:crates/decision-gate-providers/src/typed.rs L958-L980 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L586-L663

Requisit de control de canvis:

Any change to the above lock values requires same-change updates to:
- aquesta secció,
- Fixtures de conformitat OpenAPI (system-tests/tests/fixtures/openapi_compat/),
- contractes de política/informe de cobertura REST (system-tests/tests/fixtures/coverage/),
- i deltes del model de amenaces quan les fronteres de confiança s’amplien.

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Configuració del proveïdor + validació	`crates/decision-gate-config/src/config.rs`	Tipus de proveïdor, transport, ruta del contracte, temps d’espera, descoberta permetre/denegar.
Registre de capacitats	`crates/decision-gate-mcp/src/capabilities.rs`	Càrrega de contractes, compilació d’esquemes, validació.
Federació d’evidències	`crates/decision-gate-mcp/src/evidence.rs`	Registre de proveïdors + aplicació de confiança.
Proveïdor de temps d’execució tipificat	`crates/decision-gate-providers/src/typed.rs`	Càrrega de perfil d’execució i execució de comprovació tipificada.
IR tipificat + adaptadors	`crates/decision-gate-typed/src/lib.rs`	Fonament d’importació/codi generat tipificat independent del protocol.
Catàleg de cicle de vida tipificat	`crates/decision-gate-typed/src/lifecycle.rs`	Versionat de perfil OSS, activació/reversió i primitives d’estat de deriva de resum.
Façana d’adaptador OpenAPI	`crates/decision-gate-typed/src/adapter_openapi.rs`	Reexportació de compatibilitat per a l’API del mòdul `openapi`.
Interns d’adaptador OpenAPI	`crates/decision-gate-typed/src/openapi/`	Divisió de mòdul per a opcions/errors/conformitat/referències/esquema/seguretat/comprovació/lògica de comparador.
Orquestració d’eines de cicle de vida tipificat	`crates/decision-gate-mcp/src/tools/typed/lifecycle.rs`	Anàlisi d’importació/registre/llista/obtenir/activar/deprecar tipificada i cablejat d’estat del cicle de vida.
Integració d’eines	`crates/decision-gate-mcp/src/tools/router.rs`	Despatx d’eines, portes d’autenticació/divulgació i envoltura de controlador asíncron.