Arxi Decision Gate Asset Core
Docs
Decision Gate Docs

Deterministic, replayable gate evaluation with auditable decisions.

Asset Core docs

Decision Gate Authn/Authz + Disclosure Architecture

Audience: Engineers implementing or reviewing MCP authentication, authorization, and error disclosure behavior.

Table of Contents

  1. Executive Overview
  2. Request Context and Identity
  3. Authentication Modes
  4. Tool Authorization (Allowlist)
  5. Tenant Authorization (Pluggable)
  6. Usage Metering and Quotas (Pluggable)
  7. Auth Audit Events
  8. Disclosure Posture (JSON-RPC + HTTP)
  9. Rate Limiting and Overload Responses
  10. File-by-File Cross Reference

Executive Overview

Decision Gate MCP enforces strict, fail-closed authentication and authorization for tool calls. Authentication is transport-aware (stdio, HTTP, SSE) and configured via server.auth. Authorization is enforced per tool call via DefaultToolAuthz, with optional tool allowlists. A separate, pluggable tenant authorization layer can enforce tenant/namespace scoping before tool execution. Auth decisions emit structured audit events, and request failures are mapped to stable JSON-RPC error codes and HTTP status codes for deterministic disclosure and metrics labeling. F:crates/decision-gate-mcp/src/auth.rs L293-L372 F:crates/decision-gate-mcp/src/tools.rs L1436-L1454 F:crates/decision-gate-mcp/src/tools.rs L2857-L2878 F:crates/decision-gate-mcp/src/server.rs L1984-L2017

Request Context and Identity

Request Context

Incoming requests are normalized into a RequestContext that records transport, peer IP, auth header, client subject, and an optional request id plus correlation metadata. For HTTP/SSE transports, the context is built from the Authorization header and the x-decision-gate-client-subject header for mTLS proxy identity. Client-provided correlation identifiers arrive via x-correlation-id and are treated as unsafe input: they are strictly validated and rejected if invalid. The server always issues its own x-server-correlation-id and returns it on responses, providing a stable, auditable identifier even when client IDs are missing or rejected. 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

Principal Identity

AuthContext captures the authentication method plus either an explicit subject or a bearer token fingerprint. If a local-only request has no subject, the subject is set to stdio or loopback based on transport. For bearer tokens, a sha256 fingerprint is computed and used as a stable identity label. F:crates/decision-gate-mcp/src/auth.rs L181-L216 F:crates/decision-gate-mcp/src/auth.rs L503-L517

Authentication Modes

Auth mode is configured via server.auth.mode with supporting allowlists:

  • local_only: stdio is allowed; HTTP/SSE are only allowed for loopback IPs.
  • bearer_token: bearer token must match server.auth.bearer_tokens.
  • mtls: subject must be present in x-decision-gate-client-subject and match server.auth.mtls_subjects when configured.

Configuration surface:

Implementation details:

  • Local-only rejects non-loopback HTTP/SSE.
  • Bearer tokens are parsed with size and scheme validation; invalid/missing headers fail authentication.
  • mTLS requires a subject; unauthorized subjects are rejected. F:crates/decision-gate-mcp/src/auth.rs L479-L552

Tool Authorization (Allowlist)

Tool authorization is enforced per request by DefaultToolAuthz. If server.auth.allowed_tools is configured, any tool not in the allowlist is rejected with an unauthorized error. Invalid tool names in the allowlist are treated as a fail-closed configuration (empty allowlist). F:crates/decision-gate-mcp/src/auth.rs L293-L372

Tool authorization results are emitted by the tool router:

Tenant Authorization (Pluggable)

Tenant/namespace authorization is enforced by a pluggable TenantAuthorizer hook. The default implementation allows all access, but enterprise deployments can supply an authorizer that binds principals to tenant and namespace scopes. Tenant authorization runs after tool allowlist checks and before tool execution. Tenant denials emit dedicated audit events (tenant_authz).

Implementation references:

Usage Metering and Quotas (Pluggable)

Usage metering and quota checks are enforced by a pluggable UsageMeter hook. The default implementation is a no-op, but enterprise deployments can supply a meter that enforces quotas and records billing-grade usage. Usage checks run before tool execution; denials emit usage_audit events.

Implementation references:

Auth Audit Events

Auth decisions emit structured JSON audit events with transport, subject, method, and failure reason details. The default audit sink logs JSON lines to stderr; tests can use a no-op sink. F:crates/decision-gate-mcp/src/auth.rs L379-L445

Disclosure Posture (JSON-RPC + HTTP)

Feedback Disclosure (scenario_next)

scenario_next responses are summary-only by default. Optional feedback levels (trace, evidence) are gated by server.feedback.scenario_next policy, with role/subject checks resolved from server.auth.principals. Evidence feedback is still filtered through the evidence disclosure policy (raw values may be redacted unless explicitly allowed). F:crates/decision-gate-config/src/config.rs L452-L545 F:crates/decision-gate-mcp/src/tools.rs L2144-L2257

JSON-RPC Error Envelope

The MCP server responds using JSON-RPC error codes and structured metadata (kind, retryable, request_id, optional retry_after_ms). Error kinds are stable labels used for metrics and audit categorization. F:crates/decision-gate-mcp/src/server.rs L1961-L2043

Error Mapping (Tool Errors)

Tool errors are mapped to HTTP status + JSON-RPC error codes:

ToolErrorHTTPJSON-RPC CodeMessage
Unauthenticated401-32001unauthenticated
Unauthorized403-32003unauthorized
InvalidParams400-32602provided message
CapabilityViolation400-32602code: message
UnknownTool400-32601unknown tool
ResponseTooLarge200-32070provided message
RateLimited200-32071provided message
NotFound200-32004provided message
Conflict200-32009provided message
Evidence200-32020provided message
ControlPlane200-32030provided message
Runpack200-32040provided message
Internal200-32050provided message
Serialization200-32060serialization failed

These mappings are implemented in jsonrpc_error. F:crates/decision-gate-mcp/src/server.rs L1984-L2015

Auth Challenge Header (RFC 6750)

HTTP/SSE responses for unauthenticated requests include a WWW-Authenticate header with a Bearer realm when bearer token auth is enabled. This aligns with RFC 6750 and keeps auth challenges explicit without leaking token validation details. F:crates/decision-gate-mcp/src/auth.rs L46-L75 F:crates/decision-gate-mcp/src/server.rs L1706-L1718

Correlation Headers

HTTP/SSE responses always include a server-issued x-server-correlation-id. If the client supplied a valid x-correlation-id, it is echoed back. Invalid client correlation IDs are rejected before request parsing and are not echoed. The invalid-correlation rejection uses HTTP 400 with JSON-RPC error code -32073 (invalid_correlation_id). F:crates/decision-gate-mcp/src/server.rs L993-L1072 F:crates/decision-gate-mcp/src/server.rs L1648-L1749

Request Parsing Failures

Invalid JSON-RPC versions, unknown methods, and malformed request bodies are rejected with standard JSON-RPC error codes and HTTP 400. F:crates/decision-gate-mcp/src/server.rs L1505-L1583

Rate Limiting and Overload Responses

The server enforces:

  • Inflight request limits (reject with 503 and -32072).
  • Rate limiting (reject with 429 and -32071, including retry-after hints).
  • Payload size limits (reject with 413 and -32070).

These failures are reported with structured JSON-RPC error metadata and are marked retryable when appropriate. F:crates/decision-gate-mcp/src/server.rs L1505-L1568 F:crates/decision-gate-mcp/src/server.rs L2051-L2053

File-by-File Cross Reference

AreaFileNotes
Auth config surfacecrates/decision-gate-config/src/config.rsAuth modes, token/subject allowlists, tool allowlist.
Auth policy enginecrates/decision-gate-mcp/src/auth.rsDefaultToolAuthz, auth modes, audit events, token parsing.
Tool auth integrationcrates/decision-gate-mcp/src/tools.rsPer-call authorization + audit emission.
Tenant authz interfacecrates/decision-gate-mcp/src/tenant_authz.rsPluggable tenant/namespace authorization seam.
Usage metering interfacecrates/decision-gate-mcp/src/usage.rsPluggable usage metering + quota enforcement seam.
JSON-RPC disclosurecrates/decision-gate-mcp/src/server.rsError mapping and response codes.