Arxi Decision Gate Asset Core
Docs
Decision Gate Docs

Avaluació de portes determinista, reproduïble amb decisions auditable.

Asset Core docs

Protocol del Proveïdor d’Evidències

A Simple Vista

Què: protocol JSON-RPC 2.0 per a proveïdors d’evidències externes (MCP) Per què: Permetre que Decision Gate cridi fonts d’evidència personalitzades sense canvis al nucli Qui: Desenvolupadors de proveïdors, enginyers d’integració, implementadors de MCP Requisits previs: JSON-RPC 2.0 i evidence_flow_and_execution_model.md

Com Decision Gate Crida Proveïdors

  • Les trucades de Decision Gate utilitzen una eina: evidence_query.
  • Les trucades són sempre tools/call amb name = "evidence_query".
  • La Decision Gate no depèn de tools/list en temps d’execució; les capacitats del proveïdor es carreguen des de capabilities_path en la configuració.

Els proveïdors haurien d’implementar tools/list per a la compatibilitat amb MCP i plantilles SDK, però Decision Gate no depèn d’això.

Configuració del Proveïdor Extern

Els proveïdors externs utilitzen type = "mcp" i han de declarar capabilities_path:

[[providers]]
name = "git"
type = "mcp"
# stdio transport
command = ["/usr/local/bin/git-provider", "--repo", "/repo"]
capabilities_path = "contracts/git.json"

[[providers]]
name = "cloud"
type = "mcp"
# HTTP transport
url = "https://evidence.example.com/rpc"
allow_insecure_http = false
capabilities_path = "contracts/cloud.json"
# Optional auth + timeouts
# auth = { bearer_token = "YOUR_TOKEN" }
# timeouts = { connect_timeout_ms = 2000, request_timeout_ms = 10000 }

Els proveïdors integrats utilitzen type = "builtin" i no són servidors MCP. Els noms dels proveïdors han de ser únics; els identificadors integrats (time, env, json, http) estan reservats i no poden ser utilitzats pels proveïdors MCP.

Tool Call: evidence_query

Sol·licitud (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "evidence_query",
    "arguments": {
      "query": {
        "provider_id": "file-provider",
        "check_id": "file_size",
        "params": { "path": "report.json" }
      },
      "context": {
        "tenant_id": 1,
        "namespace_id": 1,
        "run_id": "run-123",
        "scenario_id": "ci-gate",
        "stage_id": "main",
        "trigger_id": "commit-abc",
        "trigger_time": { "kind": "unix_millis", "value": 1710000000000 },
        "correlation_id": null
      }
    }
  }
}

Resposta (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "value": { "kind": "json", "value": 1024 },
          "lane": "verified",
          "error": null,
          "evidence_hash": null,
          "evidence_ref": { "uri": "dg+file://evidence-root/report.json" },
          "evidence_anchor": {
            "anchor_type": "file_path_rooted",
            "anchor_value": "{\"path\":\"report.json\",\"root_id\":\"evidence-root\",\"size\":1024}"
          },
          "signature": null,
          "content_type": "application/json"
        }
      }
    ]
  }
}

Important: evidence_anchor.anchor_value és una cadena. Si necessiteu dades d’ancoratge estructurades, codifiqueu-les com a JSON canònic i emmagatzemeu la cadena JSON. Per a file_path_rooted, incloeu els camps escalar root_id i path.

Estructura d’EvidenceQuery

{
  "provider_id": "string",
  "check_id": "string",
  "params": "any"  // optional
}
  • provider_id coincideix amb el nom del proveïdor en la configuració.
  • check_id és el nom de la capacitat del proveïdor (no l’ID de condició de l’escenari).
  • params és específic del proveïdor; pot ser omès o null.

Estructura EvidenceContext

{
  "tenant_id": 1,
  "namespace_id": 1,
  "run_id": "run-123",
  "scenario_id": "ci-gate",
  "stage_id": "main",
  "trigger_id": "commit-abc",
  "trigger_time": { "kind": "unix_millis", "value": 1710000000000 },
  "correlation_id": null
}

El context és proporcionat per Decision Gate i està disponible per als proveïdors per a consultes deterministes (per exemple, comprovacions en un moment concret).

Estructura EvidenceResult

{
  "value": { "kind": "json|bytes", "value": "any" } | null,
  "lane": "verified|asserted",
  "error": { "code": "string", "message": "string", "details": "object|null" } | null,
  "evidence_hash": { "algorithm": "sha256", "value": "hex" } | null,
  "evidence_ref": { "uri": "string" } | null,
  "evidence_anchor": { "anchor_type": "string", "anchor_value": "string" } | null,
  "signature": { "scheme": "ed25519", "key_id": "string", "signature": [0, 1, 2] } | null,
  "content_type": "string" | null
}

Notes:

  • value.kind = "bytes" utilitza un array JSON d’enters 0..255.
  • signature.signature és un array JSON de bytes (la serialització Vec<u8>).
  • Si evidence_hash falta, Decision Gate el calcula a partir de value abans de la verificació.
  • Si evidence_hash està present, ha de coincidir amb el hash canònic de value o la resposta és rebutjada.

Gestió d’Errors

Els proveïdors haurien de retornar un EvidenceResult amb error establert per a fallades esperades (fitxers mancants, paràmetres no vàlids, etc.).

Si el proveïdor retorna un error JSON-RPC, Decision Gate ho tracta com una fallada del proveïdor i ho mostra com code = "provider_error" al seu costat.

Notes de Transport

stdio

  • Decision Gate genera el proveïdor utilitzant command = [..].
  • Els missatges estan emmarcats amb encapçalaments Content-Length.

HTTP

  • Decision Gate envia un POST JSON-RPC a la url configurada.
  • El token d’autorització opcional es pot configurar mitjançant auth.bearer_token.

Glossari

EvidenceQuery: Sol·licitud del proveïdor { provider_id, check_id, params }. EvidenceResult: Resposta del proveïdor (valor + metadades). MCP: Protocol de Context del Model (trucades d’eines JSON-RPC 2.0). Provider Contract: Fitxer JSON que declara verificacions, esquema de params, esquema de resultats i comparadors permesos.