Skip to content
ContextUnity

Dispatcher & Security

The Dispatcher is ContextRouter’s gRPC service layer — it receives incoming requests, validates tokens, and routes them to the appropriate LangGraph agent.

gRPC Service

The Dispatcher exposes the core operations of the Router. The primary methods take a ContextUnit and return one or stream them back.

service RouterService {
    rpc ExecuteAgent(ContextUnit) returns (ContextUnit);
    rpc StreamAgent(ContextUnit) returns (stream ContextUnit);
    rpc ExecuteDispatcher(ContextUnit) returns (ContextUnit);
    rpc StreamDispatcher(ContextUnit) returns (stream ContextUnit);
    rpc RegisterManifest(ContextUnit) returns (ContextUnit);
    rpc ToolExecutorStream(stream ContextUnit) returns (stream ContextUnit);
    rpc ExecuteNode(ContextUnit) returns (ContextUnit);
    rpc IntrospectRegistrations(ContextUnit) returns (ContextUnit);
}

ExecuteAgent / StreamAgent

Used when you force the execution of a specific graph (e.g., you explicitly want the gardener or matcher agent to run, bypassing intent detection).

ExecuteDispatcher / StreamDispatcher

Used for open-ended interactions. Passes the request to a central routing graph. The detect_intent node will analyze the user’s prompt and automatically decide which sub-agent is best suited to handle it.

RegisterManifest

Registers a compiled project bundle containing graph definitions, tenant scope, and federated tool references. The Router rejects raw manifests, inline secrets, and legacy project-secret payloads.

ToolExecutorStream

Bi-directional streaming for federated tool execution. External projects connect to Router with a ContextToken bearing stream:executor or stream:executor:{project_id}; the ready message binds project_id and registered tool names without a separate stream secret.

Security Flow

router-dispatcher

Token Validation & Shield

Before any gRPC request reaches the logic layer, it must survive the Interceptor chain.

As detailed in the Security Integration guide, the Router verifies the ContextToken mathematically.

  1. Extract authorization header from metadata
  2. Verify token (Ed25519 signature or Shield delegation)
  3. Check is_expired()
  4. Validate can_access_tenant(tenant_id)
  5. Inject validated token into the request context

AI Firewall (Enterprise / Pro Module)

When ContextShield is configured as the Enterprise AI Firewall, Router delegates security checks via a gRPC Scan call in service/shield_check.py. In the Open Source version, this module fails-open and permits request execution directly.

from contextunity.router.service.shield_check import check_user_input


# Scan input for prompt injection and jailbreaks via ContextShield
scan_result = await check_user_input(
    user_input=text,
    request_id=request_id,
    tenant=tenant_id
)


if scan_result.blocked:
    raise SecurityError(f"Blocked by Shield (Pro): {scan_result.reason}")

Note: The Router uses a Token as Single Point of Truth (SPOT) pattern, meaning the caller’s JWT is forwarded to Shield to attribute the security scan correctly. For this to succeed, tokens possessing router:execute implicitly inherit the shield:check authority necessary to be scanned.