Documentació

Cerca Arxiu

Escriu per cercar a Arxiu.

Arquitectura d'Autenticació, Política i Divulgació de Decision Gate

Política d'autenticació, autorització i divulgació.

En aquesta pàgina Secció actual: Taula de continguts

Audiència: Enginyers que implementen o revisen el comportament d’autenticació, autorització i divulgació d’errors de MCP.

Taula de continguts

  1. Visió Executiva
  2. Context de la sol·licitud i identitat
  3. Modes d’autenticació
  4. Visibilitat de l’Eina i Política de Crida
  5. Autorització de Namespace (Connectable)
  6. Mesura d’ús i quotes (Plugable)
  7. Esdeveniments d’Auditoria d’Autenticació
  8. Postura de Divulgació (JSON-RPC i HTTP)
  9. Limitació de Taxa i Respostes d’Overload
  10. Ancoratges d’Implementació Fitxer per Fitxer

Executive Overview

Decision GateLa porta de decisió MCP imposa una autenticació estricta i tancada per defecte, així com una política d’autorització de propietat separada. L’autenticació és conscient del transport (stdio, HTTP, SSE), configurada a través de server.auth, i és propietat de RequestAuthenticator. RequestAuthenticator rep només la identitat de la sol·licitud; no rep una acció d’eina i no pot convertir-se en un segon propietari de política d’eina. ToolVisibilityResolver és l’únic propietari de la política de descoberta i invocació d’eines estàtiques, configurada per server.tools. Una capa d’autorització de namespace separada i connectable imposa l’abast del namespace abans de l’execució de l’eina. Cada crida semàntica suportada passa el seu namespace exacte a la costura d’autorització. El perfil inicial no té cap crida d’eina amb abast de proveïdor ni autoritat de consulta d’evidència independent. L’evidència del cridant entra només a través dels portadors de precomprovació/evaluació de l’escenari; les afirmacions de font i garantia són construïdes pel servidor, no acceptades dels camps del cridant. El temps anomenat, l’entorn immutable i l’adquisició de documents arrelats utilitzen autoritats locals registrades per l’operador i la relació de vinculació propietat de l’escenari en lloc de l’RBAC amb abast de proveïdor. Les decisions d’autenticació emeten esdeveniments d’auditoria estructurats, i les fallades de sol·licitud es mapegen a codis d’error JSON-RPC estables i codis d’estat HTTP per a una divulgació i etiquetatge de mètriques deterministes. Internament, MCP ara manté una identitat simbòlica/númerica exacta amb suport de catàleg més codis públics segurs per a auditoria i telemetria, mantenint la projecció externa de l’envolta JSON-RPC en primer lloc. Els artefactes d’autoritat DG generats sota Docs/generated/decision-gate/ congelen aquelles semàntiques d’error OSS i telemetria en forma llegible per màquina perquè les eines de verificació privada consumeixin contractes propietat de DG en lloc d’inferir-los ad hoc dels detalls d’implementació. 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

Abast i No Objectius

L’abast és la identitat d’entrada de MCP, l’autenticació, l’autorització, els ganxos d’autorització de namespace, la divulgació, l’auditoria i el maneig de sobrecàrregues. Aquest document no defineix la col·locació del namespace, la propietat de l’evaluador, el tancament o la replicació; l’abast d’autorització és distint d’aquestes futures responsabilitats del pla de control.

Responsabilitats de la Capçalera

  • L’ingress normalitza la identitat de transport no fiable i les metadades de sol·licitud.
  • L’autenticació estableix el context principal.
  • ToolVisibilityResolver i l’autorització de namespace decideixen si una sol·licitud pot executar-se.
  • La divulgació i l’auditoria projecten el resultat sense debilitar la decisió.

Context de la sol·licitud i identitat

Context de la Sol·licitud

Les sol·licituds entrants es normalitzen en un RequestContext que registra el transport, l’IP del peer, l’encapçalament d’autenticació i metadades opcionals d’identitat de sol·licitud autoritzada/cridant. Per a transports HTTP/SSE, el sol únic portador de credencials d’aplicació és l’encapçalament Authorization. Els subjectes de certificat afirmats pel cridant no són un canal d’identitat admès. La procedència proporcionada pel cridant arriba a través de x-caller-request-id i es tracta com a entrada insegura: es valida estrictament i es rebutja si és invàlida. El servidor sempre emet el seu propi UUIDv7 canònic x-request-id i el retorna en les respostes, proporcionant un identificador estable i auditable fins i tot quan falta la procedència del cridant. MCP a més rastreja el id JSON-RPC per missatge com un camp de context de sol·licitud intern, però aquest identificador de protocol es manté separat tant de la procedència del cridant com de l’ID de sol·licitud autoritzada del servidor. No es retorna com un encapçalament HTTP/SSE i no substitueix els canals d’identitat de sol·licitud d’auditoria o telemetria. 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

Identitat Principal

AuthContext és un transportador de principal etiquetat segellat. Les seves variants vinculen un subjecte local derivat del transport o un resum de token canònic directament al mètode d’autenticació que coincideix; els cridants no poden construir camps d’opció desajustats o un context “autenticat” anònim/malformat. L’admissió local assigna exactament el subjecte stdio o loopback del transport. L’admissió de portador emmagatzema el ContentDigest sha256 tipificat, y la identitat ACL/ús es projecta només a partir d’aquesta variant segellada. No hi ha un principal de fallback fabricat per a un estat invàlid. F:crates/decision-gate-mcp/src/auth.rs L181-L216 F:crates/decision-gate-mcp/src/auth.rs L503-L517

Modes d’autenticació

El mode d’autenticació es configura a través de server.auth.mode:

  • local_only: s’accepta stdio; HTTP/SSE només s’accepten per a IPs de loopback.
  • bearer_token: el material del verificador del token de portador ha de resoldre’s des de cada referència secreta server.auth.bearer_tokens configurada abans de la publicació.

Superfície de configuració:

Detalls d’implementació:

  • Local només rebutja HTTP/SSE no de retroalimentació.
  • Les referències del secret de portador es resolen atòmicament en iniciar; el material en brut és limitat, validat, hashat en digests de verificador, i descartat. Les credencials de sol·licitud es parsegen amb validació de mida i esquema i es comparen amb cada digest de verificador sense un oracle de coincidència de sortida anticipada.
  • El TLS del servidor protegeix el transport. No crea la identitat de l’aplicació. F:crates/decision-gate-mcp/src/auth.rs L479-L552

Visibilitat de l’Eina i Política de Crida

ToolVisibilityResolver és l’únic propietari de la política d’eines estàtiques. Els conjunts server.tools.allowlist i server.tools.denylist governen tant tools/list com la invocació directa. Una eina que no és invocable es projecta com UnknownTool, prevenint la descoberta a través de diferents divulgacions de crida/llista. Els noms d’eines desconegudes i els conjunts de polítiques excessius fallen en l’admissió de configuració. La superfície server.auth.allowed_tools eliminada no té cap àlies de parser ni pont d’execució; la seva presència és un error de camp desconegut. F:crates/decision-gate-mcp/src/tools/visibility.rs F:crates/decision-gate-config/src/config.rs

Els resultats d’autenticació s’emeten pel router d’eines abans de la política d’eines:

Descripció del Flux/Seqüència Principal

  1. El servidor normalitza el context de la sol·licitud i rebutja les entrades d’identitat malformades.
  2. L’autenticació estableix un principal o rebutja la sol·licitud.
  3. La política de l’eina, l’autorització de l’espai de noms, i les comprovacions de quota aplicables s’executen abans de l’efecte secundari de l’eina.
  4. El resultat és auditat i projectat a través de la política de divulgació JSON-RPC/HTTP.

Autorització de Namespace (Connectable)

L’autorització de namespace s’imposa mitjançant un ganxo NamespaceAuthorizer connectable. La implementació independent permet només l’autenticació local que porta un rebut de governança d’autenticació durable i requereix context de namespace per a cada eina que porti namespace. Les implementacions empresarials subministren un autoritzador que vincula els principals als abasts de namespace.

Les polítiques d’autorització i denegació són variants disjuntes de NamespaceAuthzDecision. La fallada d’obtenir una decisió autoritzada és un NamespaceAuthorizationError separat que preserva la cadena de font exacta; el router registra un esdeveniment de denegació tancada i retorna la fallada d’autoritat en lloc de mal etiquetar-la com una denegació de política. Si aquesta auditoria de denegació requerida també falla, ambdues fallades es preserven en un error compost de l’eina. L’autorització de namespace s’executa després de les comprovacions de política d’eines estàtiques i abans de l’execució de l’eina. Tots els resultats emeten esdeveniments d’auditoria dedicats (namespace_authz).

Referències d’implementació:

Mesura d’Ús i Quotes (Connectables)

La mesura d’ús i les verificacions de quota s’apliquen mitjançant un ganxo UsageMeter connectable. La composició OSS admesa utilitza el mateix dipòsit de governança durable que l’auditoria de sol·licituds; marcadors explícits de no-op rebutgen cada operació i no poden satisfer el cablejat d’inici durable. Les implementacions empresarials subministren l’adaptador de quota de plataforma. Les reserves d’ús s’executen abans de l’execució de l’eina; les denegacions emeten esdeveniments usage_audit. Una admissió segellada reté el principal autenticat. La resolució rebutja la substitució del principal, compromet un resolution_attempt distint, demana a l’autoritat de quota la transició idempotent, i emet resolution_finalized només després de la confirmació de l’autoritat. La costura d’ús rep una entrada d’identitat distintiva: la procedència del cridant (caller_request_id), la identitat de sol·licitud del servidor autoritzada (request_id), y un idempotency_key de crida d’eina dedicat. Decision Gate deriva aquesta clau d’idempotència de l’id JSON-RPC normalitzat quan està disponible, retrocedint només al request_id del servidor quan el missatge de protocol no porta un identificador JSON-RPC utilitzable. Els identificadors JSON-RPC segurs passen directament; els identificadors insegurs es transformen de manera determinista en jsonrpc-sha256:<hex> per preservar el comportament de quota/idempotència d’empresa tancat sense filtrar la identitat JSON-RPC en els encapçalaments de transport, IDs de sol·licitud d’auditoria, o IDs de sol·licitud de telemetria.

Referències d’implementació:

Esdeveniments d’Auditoria d’Autenticació

Les decisions d’autenticació emeten esdeveniments d’auditoria estructurats mcp_request_authentication amb context d’acció, transport, subjecte, mètode i detalls de fallada. L’acció identifica l’operació intentada com a evidència; no és una entrada per a la política d’autenticació. L’escorre de registre per defecte registra línies JSON a stderr; les proves poden utilitzar un escorre de no-op. F:crates/decision-gate-mcp/src/auth.rs L379-L445

Postura de Divulgació (JSON-RPC i HTTP)

Divulgació de l’Avaluació de l’Estadi

scenario_evaluate_stage retorna la vista d’execució acceptada, no els valors d’observació en brut. Els materials d’intent/prova romanen a la història acceptada i a les famílies de runpack d’acord amb la política de divulgació d’evidències. scenario_precheck_stage retorna només el resultat semàntic i la traçabilitat per a l’evidència local submesa pel cridant o explícita i no fa cap reclamació de progrés acceptat. La configuració de retroalimentació del cursor eliminat no té un àlies de compatibilitat.

JSON-RPC Error Envelope

El servidor MCP respon amb codis d’error JSON-RPC i metadades estructurades (kind, retryable, request_id, opcional retry_after_ms). Els tipus d’error són etiquetes estables utilitzades per a mètriques i categorizació d’auditoria. Internament, el servidor també reté un codi públic segur de projecció, un codi de raó opcional, i una identitat exacta canònica sobre l’objecte d’error per a dipòsits d’auditoria/telemetria, però aquests camps no es serialitzen al cablejat públic JSON-RPC per defecte. La projecció pública MCP roman Docs/generated/decision-gate/mcp_errors.json, mentre que la font de completitud canònica OSS més rica és ara 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

Artefactes d’Autoritat de Telemetria

Decision Gate publica esdeveniments de telemetria generats i artefactes d’autoritat operator-seam:

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

Aquests artefactes es generen a partir de manifestos de font propietaris de DG a crates/decision-gate-contract/catalogs/ i congelen codis d’esdeveniment i costures d’operador d’alt risc que s’espera que la governança d’observabilitat protegeixi. La identitat de família de mètriques, etiquetes, text d’ajuda, unitats, tipus, cardinalitat, i perfils de cub de histograma són propietat d’un catàleg de telemetria de plataforma subministrat pel workspace d’integració; aquesta autoritat externa no és un camí de repositori de Decision Gate, y DG no ha de portar un mirall de catàleg de mètriques que porti files.

Mapeig d’Errors (Errors de l’Eina)

Els errors de l’eina es mapegen a l’estat HTTP + codis d’error JSON-RPC:

ToolErrorHTTPCodi JSON-RPCMissatge
No autenticat401-32001no autenticat
No autoritzat403-32003no autoritzat
ParàmetresInvàlids400-32602missatge proporcionat
ViolacióDeCapacitat400-32602code: message
EinaDesconeguda400-32601eina desconeguda
Resposta massa gran200-32070missatge proporcionat
Limitat per taxa200-32071missatge proporcionat
No trobat200-32004missatge proporcionat
Conflicte200-32009missatge proporcionat
Prova200-32020missatge proporcionat
PlaDeControl200-32030missatge proporcionat
ExecutarPaquet200-32040missatge proporcionat
AutoritatLimitacióTaxa200-32050l’autoritat de limitació de taxa ha fallat
Intern200-32050missatge proporcionat
Serialització200-32060la serialització ha fallat

Aquests mapeigs s’implementen en jsonrpc_error. F:crates/decision-gate-mcp/src/server.rs L1984-L2015

Suport d’Identitat Exacta

El mapeig JSON-RPC roman el contracte públic estable, però ara està recolzat per identitats exactes propietàries del catàleg. Les variants d’error ToolError rutejades i les rejeccions d’ingress del servidor es resolen primer a identitats simbòliques/númeriques canòniques OSS i només llavors es projecten a la taxonomia pública JSON-RPC. F:crates/decision-gate-mcp/src/tools/error.rs L126-L189 F:crates/decision-gate-mcp/src/server.rs L2270-L2307

Capçalera del Repte d’Autenticació (RFC 6750)

Les respostes HTTP/SSE per a sol·licituds no autenticades inclouen un capçalera WWW-Authenticate amb un àmbit Bearer quan l’autenticació amb token Bearer està habilitada. Això s’alinea amb l’RFC 6750 i manté els desafiaments d’autenticació explícits sense filtrar detalls de validació del token. F:crates/decision-gate-mcp/src/auth.rs L46-L75 F:crates/decision-gate-mcp/src/server.rs L1706-L1718

Encapsulaments d’Identitat de Sol·licitud

Les respostes HTTP/SSE sempre inclouen un UUIDv7 canònic en minúscules emès pel servidor amb guions a x-request-id. Si el sol·licitant proporciona un x-caller-request-id vàlid, es retorna com a procedència del sol·licitant, però mai substitueix l’identificador de sol·licitud autoritatiu del servidor. Els IDs de sol·licitud no vàlids són rebutjats abans de l’anàlisi de la sol·licitud i no es retornen. El rebuig utilitza HTTP 400 amb el codi d’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

Errors en la Anàlisi de Sol·licituds

Versions de JSON-RPC no vàlides, mètodes desconeguts i cossos de sol·licitud mal formats són rebutjats amb codis d’error estàndard de JSON-RPC i HTTP 400. F:crates/decision-gate-mcp/src/server.rs L1505-L1583

Limitació de Taxa i Respostes d’Overload

decision-gate-mcp::rate_limit és l’únic propietari de Decision Gate de l’algorisme de finestra fixa en procés. Els documents d’entrada MCP i d’empresa amb abast d’account subministren diferents tipus de claus i polítiques externes, però no posseeixen còpies del rellotge, cub, desallotjament, comptador o relació de publicació. La política admesa segella el recompte de sol·licituds no zero, la finestra i la capacitat de claus i prova que l’horitzó de retenció de dues finestres és representable abans que un limitador pugui existir.

Per a una clau k, política (m, w, c), mostra monotònica serialitzada t, i estat retingut S, l’admissió és una transició parcial determinista step(S, k, t) -> Result<(S', Allow | Limited(retry)), E>. Una transició exitosa publica l’estat següent complet i avança un watermark monotònic global. La fallada de sincronització, la regressió del rellotge, l’exhauriment de capacitat, la fallada del comptador o la fallada de projecció de reintents no publiquen cap estat. Qualsevol resta de reintents positiva de menys d’un mil·lisegon es projecta al sòl públic anomenat d’un mil·lisegon; no pot convertir-se en un suggeriment de reintents zero.

El servidor imposa:

  • Límits de sol·licituds en vol (rebutjar amb 503 i -32072, tipus inflight_limit, codi de raó dg.server.inflight_limit_exhausted).
  • Limitació de finestra de taxa (rebutjar amb 429 i -32071, tipus rate_limited, codi de raó dg.server.rate_limit_window_exhausted, incloent suggeriments de retry-after).
  • Saturació de capacitat del limitador de taxa (rebutjar amb 503 i -32074, tipus rate_limiter_capacity, codi de raó dg.server.rate_limiter_capacity_exhausted).
  • Límits de mida de càrrega útil (rebutjar amb 413 i -32070).

L’autoritat de finestra fixa posseeix un mapa limitat més un aigua monotònica publicada globalment. Només s’amostra després de serialitzar l’accés, valida l’ordre del rellotge i cada càlcul fallible abans de la publicació, i deixa l’estat anterior exacte inalterat en la regressió del rellotge, l’exhauriment de capacitat, fallada aritmètica o sincronització enverinada. Per tant, la reordenació ordinària del programador no pot ser malclassificada com a regressió del rellotge, mentre que canviar les claus d’atribució no pot ocultar una regressió real.

L’adquisició local té el seu propi pressupost d’operació i concurrència validat. El perfil inicial no conté cap camí d’adquisició de xarxa sortint.

Aquestes fallades es reporten amb metadades d’error JSON-RPC estructurades i es marquen com a recuperables quan és apropiat. F:crates/decision-gate-mcp/src/rate_limit.rs F:crates/decision-gate-mcp/src/server.rs

Invariants

  • La identitat de sol·licitud no fiable mai esdevé autoritzada sense validació.
  • L’autenticació/autorització que falta o es nega falla tancada abans de la feina de l’eina.
  • L’autorització de namespace és una decisió d’accés, no una decisió de col·locació.
  • La divulgació preserva errors públics estables sense exposar detalls sensibles.

Modes de Fallida i Matriu de Recuperació

Mode de fallidaComportament tancatRecuperació
Identitat de sol·licitud invàlidaRebutjar abans de l’autorització/execució de l’eina.Corregir la entrada del cridant.
Autenticació no disponible o denegadaRebutjar la sol·licitud.Restaurar la configuració d’autenticació/backend o credencials.
Autorització de namespace no disponibleDenegar la sol·licitud d’àmbit de namespace.Restaurar l’autoritat i tornar a intentar.
Límits de taxa/ús superatsRetornar una resposta estructurada recuperable on sigui aplicable.Esperar o restaurar capacitat/quota.

Ancoratges d’Implementació Fitxer per Fitxer

ÀreaFitxerNotes
Superfície de configuració d’authcrates/decision-gate-config/src/config.rsModes d’auth, llistes d’autorització de tokens/subjectes, llista d’autorització d’eines.
Motor de política d’authcrates/decision-gate-mcp/src/auth.rsDefaultRequestAuthenticator, modes d’auth, esdeveniments d’auditoria, anàlisi de tokens.
Integració d’auth d’einescrates/decision-gate-mcp/src/tools/router.rsAutorització per crida + emissió d’auditoria.
Interfície d’autorització de namespacecrates/decision-gate-mcp/src/namespace_authz.rsCostura d’autorització de namespace connectable.
Interfície de mesurament d’úscrates/decision-gate-mcp/src/usage.rsMesurament d’ús connectable + costura d’aplicació de quotes.
Autoritat de sol·licitud de finestra fixacrates/decision-gate-mcp/src/rate_limit.rsPolítica segellada, estat monotònic, retenció limitada i publicació atòmica.
Divulgació JSON-RPCcrates/decision-gate-mcp/src/server.rsMapeig d’errors i codis de resposta.

Proves i Traçabilitat de Contractes

  • L’autenticació, l’autorització de l’espai de noms, la divulgació, i les proves del servidor sota crates/decision-gate-mcp/ cobreixen el contracte d’ingrés actual.
  • Els artefactes de contracte generats congelen les projeccions d’error i telemetria públiques.

Ganxos de Preparació Operativa

  • Monitoritzar les denegacions d’autenticació, les denegacions d’autorització de l’espai de noms, les rebuigs de quota, i les categories d’errors segurs per a la divulgació.
  • Un camí d’autorització saludable no prova la col·locació de l’evaluador ni la propietat de l’escriptor; aquests requereixen proves d’espai de noms de cel·la futures separades.

Regles de Manteniment

  • Preservar la distinció entre l’abast d’autorització i l’autoritat de col·locació.
  • Actualitzar els artefactes del contracte generats sempre que el text de divulgació pública o l’esquema canviïn.

Declaració Delta del Model de Ameaça

Model de Ameaça Delta: cap per a aquesta correcció de terminologia; no s’ha canviat cap política d’entrada ni comportament d’autorització d’execució.