Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
//! Narrow daemon-to-Gateway authority for one exact delegated Worker run.
//!
//! Gateway owns compilation and request binding. The daemon owns the token verifier, current
//! run safety projection, and the exact version it retained at admission. Neither side receives
//! a general grant or a way to mutate the other side's authority.
use std::sync::Arc;
use hiroute_domain::WorkspaceId;
use thiserror::Error;
use crate::server::publication::RunPublicationHandle;
use crate::server::request_plan::IngressProtocol;
use crate::server::request_plan::VerifiedRunObservationContext;
use super::super::publication::{CompiledGrant, PublishedGatewayPublication};
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RunRequestLocator {
workspace_id: WorkspaceId,
task_id: String,
run_id: String,
lease_id: String,
exact_plan_reference: String,
observation: RunObservationMetadata,
}
/// Exact Product identities retained when a delegated run is admitted. These
/// values carry no authority; Gateway may use them only after the run bearer,
/// current lease safety, protocol and alias have all been verified.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RunObservationMetadata {
plan_id: String,
plan_revision: u64,
publication_ref: String,
harness_id: String,
native_session_id: Option<String>,
parent_context_ref: Option<String>,
continued_from_run_id: Option<String>,
}
impl RunObservationMetadata {
#[allow(clippy::too_many_arguments)]
pub fn new(
plan_id: impl Into<String>,
plan_revision: u64,
publication_ref: impl Into<String>,
harness_id: impl Into<String>,
native_session_id: Option<String>,
parent_context_ref: Option<String>,
continued_from_run_id: Option<String>,
) -> Result<Self, RunRequestAuthorityError> {
let value = Self {
plan_id: plan_id.into(),
plan_revision,
publication_ref: publication_ref.into(),
harness_id: harness_id.into(),
native_session_id,
parent_context_ref,
continued_from_run_id,
};
if value.plan_revision == 0
|| !valid_observation_reference(&value.plan_id)
|| !valid_observation_reference(&value.publication_ref)
|| !matches!(
value.harness_id.as_str(),
"codex" | "claude" | "qoder" | "pi" | "dsh" | "opencode"
)
|| [
&value.native_session_id,
&value.parent_context_ref,
&value.continued_from_run_id,
]
.into_iter()
.flatten()
.any(|value| !valid_observation_reference(value))
{
return Err(RunRequestAuthorityError::Denied);
}
Ok(value)
}
}
impl RunRequestLocator {
pub fn new(
workspace_id: WorkspaceId,
task_id: impl Into<String>,
run_id: impl Into<String>,
lease_id: impl Into<String>,
exact_plan_reference: impl Into<String>,
observation: RunObservationMetadata,
) -> Result<Self, RunRequestAuthorityError> {
let value = Self {
workspace_id,
task_id: task_id.into(),
run_id: run_id.into(),
lease_id: lease_id.into(),
exact_plan_reference: exact_plan_reference.into(),
observation,
};
if [
&value.task_id,
&value.run_id,
&value.lease_id,
&value.exact_plan_reference,
]
.iter()
.any(|value| !valid_reference(value))
{
return Err(RunRequestAuthorityError::Denied);
}
Ok(value)
}
pub fn workspace_id(&self) -> &WorkspaceId {
&self.workspace_id
}
pub fn task_id(&self) -> &str {
&self.task_id
}
pub fn run_id(&self) -> &str {
&self.run_id
}
pub fn lease_id(&self) -> &str {
&self.lease_id
}
pub fn exact_plan_reference(&self) -> &str {
&self.exact_plan_reference
}
fn observation_context(&self) -> VerifiedRunObservationContext {
VerifiedRunObservationContext {
task_id: self.task_id.clone(),
run_id: self.run_id.clone(),
plan_id: self.observation.plan_id.clone(),
plan_revision: self.observation.plan_revision,
publication_ref: self.observation.publication_ref.clone(),
harness_id: self.observation.harness_id.clone(),
native_session_id: self.observation.native_session_id.clone(),
parent_context_ref: self.observation.parent_context_ref.clone(),
continued_from_run_id: self.observation.continued_from_run_id.clone(),
}
}
}
/// Daemon-owned request-time verification. It receives the raw bearer only inside the request
/// path and is responsible for checking the high-entropy run credential plus current revocation
/// and lease state without consulting an ambient publication.
pub trait RunRequestSafetyPort: Send + Sync {
fn authorize_request(
&self,
authorization: &str,
locator: &RunRequestLocator,
model_alias: &str,
protocol: IngressProtocol,
) -> Result<(), RunRequestAuthorityError>;
}
/// The daemon resolves a run token to an immutable exact-plan handle. Gateway never imports the
/// daemon, SQLite, or a current-publication lookup to satisfy this contract.
pub trait RunRequestAuthorityPort: Send + Sync {
fn authenticate_run(
&self,
authorization: &str,
protocol: IngressProtocol,
) -> Result<VerifiedRunRequestAuthority, RunRequestAuthorityError>;
}
#[derive(Clone)]
pub struct VerifiedRunRequestAuthority {
locator: RunRequestLocator,
publication: Arc<RunPublicationHandle>,
safety: Arc<dyn RunRequestSafetyPort>,
network_allowed: bool,
}
impl VerifiedRunRequestAuthority {
pub fn new(
locator: RunRequestLocator,
publication: Arc<RunPublicationHandle>,
safety: Arc<dyn RunRequestSafetyPort>,
network_allowed: bool,
) -> Result<Self, RunRequestAuthorityError> {
if publication.model_alias().is_empty() || locator.workspace_id().as_str().is_empty() {
return Err(RunRequestAuthorityError::Denied);
}
Ok(Self {
locator,
publication,
safety,
network_allowed,
})
}
pub fn locator(&self) -> &RunRequestLocator {
&self.locator
}
pub(crate) fn network_allowed(&self) -> bool {
self.network_allowed
}
pub(crate) fn observation_context(&self) -> VerifiedRunObservationContext {
self.locator.observation_context()
}
pub(crate) fn begin(
&self,
authorization: &str,
protocol: IngressProtocol,
) -> Result<(Arc<PublishedGatewayPublication>, CompiledGrant), RunRequestAuthorityError> {
if protocol != self.publication.protocol() {
return Err(RunRequestAuthorityError::Denied);
}
self.safety.authorize_request(
authorization,
&self.locator,
self.publication.model_alias(),
protocol,
)?;
let grant = self
.publication
.authenticate(authorization)
.ok_or(RunRequestAuthorityError::Denied)?;
if grant.protocol != protocol
|| !grant.route_protocols.is_empty()
|| grant.routes.len() != 1
|| !matches!(grant.routes.get(self.publication.model_alias()),
Some(crate::server::publication::CompiledGrantRoute::Plan { alias })
if alias.as_ref() == self.publication.model_alias())
{
return Err(RunRequestAuthorityError::Denied);
}
Ok((self.publication.publication(), grant))
}
pub(crate) fn authorize_alias(
&self,
alias: &str,
protocol: IngressProtocol,
) -> Result<(), RunRequestAuthorityError> {
if protocol != self.publication.protocol() || alias != self.publication.model_alias() {
return Err(RunRequestAuthorityError::Denied);
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
pub enum RunRequestAuthorityError {
#[error("delegated run request is denied")]
Denied,
#[error("delegated run authority is unavailable")]
Unavailable,
}
fn valid_reference(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 256
&& !value.contains("//")
&& !value.contains("..")
&& value.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b'/' | b':')
})
}
fn valid_observation_reference(value: &str) -> bool {
!value.is_empty() && value.len() <= 256 && !value.chars().any(char::is_control)
}
#[cfg(test)]
mod tests {
use std::sync::atomic::{AtomicUsize, Ordering};
use hiroute_domain::CanonicalDigest;
use super::*;
use crate::server::dispatch::GatewayRequestAuthority;
use crate::server::publication::{
AliasPlanV1, GatewayPublicationInstaller, GatewayPublicationSnapshotV3, GrantV1,
exact_test_candidate, token_sha256,
};
const TOKEN: &str = "hr_run_model_test-token";
static DIRECTORY_SEQUENCE: AtomicUsize = AtomicUsize::new(0);
fn empty_global() -> Arc<GatewayPublicationInstaller> {
let path = std::env::temp_dir().join(format!(
"hiroute-run-authority-{}-{}",
std::process::id(),
DIRECTORY_SEQUENCE.fetch_add(1, Ordering::Relaxed),
));
Arc::new(GatewayPublicationInstaller::open(path).unwrap())
}
struct Safety(AtomicUsize);
impl RunRequestSafetyPort for Safety {
fn authorize_request(
&self,
authorization: &str,
locator: &RunRequestLocator,
model_alias: &str,
protocol: IngressProtocol,
) -> Result<(), RunRequestAuthorityError> {
self.0.fetch_add(1, Ordering::Relaxed);
if authorization == format!("Bearer {TOKEN}")
&& locator.run_id() == "run/one"
&& model_alias == "worker-model"
&& protocol == IngressProtocol::Responses
{
Ok(())
} else {
Err(RunRequestAuthorityError::Denied)
}
}
}
struct Authority(VerifiedRunRequestAuthority);
impl RunRequestAuthorityPort for Authority {
fn authenticate_run(
&self,
_: &str,
_: IngressProtocol,
) -> Result<VerifiedRunRequestAuthority, RunRequestAuthorityError> {
Ok(self.0.clone())
}
}
fn observation_metadata(harness: &str) -> RunObservationMetadata {
RunObservationMetadata::new(
"plan/one",
7,
"publication/3/digest/sha256:abc",
harness,
Some("native/session-one".into()),
Some("task/root".into()),
Some("run/zero".into()),
)
.unwrap()
}
fn verified(safety: Arc<Safety>) -> VerifiedRunRequestAuthority {
verified_for_harness(safety, "codex")
}
fn verified_for_harness(safety: Arc<Safety>, harness: &str) -> VerifiedRunRequestAuthority {
let snapshot = GatewayPublicationSnapshotV3::seal(
"workspace",
"delegation-run/run-one",
1,
1,
"renderer",
vec![AliasPlanV1 {
served_model_id: "worker-model".into(),
purpose: "worker".into(),
agent_plan_revision: 7,
protocols: vec![IngressProtocol::Responses],
overall_timeout_ms: 1_000,
max_attempts: 1,
routing: None,
candidates: vec![exact_test_candidate(1, IngressProtocol::Responses, None)],
}],
vec![GrantV1 {
consumer: None,
route_protocols: Default::default(),
grant_id: "delegation-run/run-one".into(),
generation: 1,
bearer_token_sha256: token_sha256(TOKEN),
protocol: IngressProtocol::Responses,
routes: [crate::server::publication::test_plan_route(
"worker-model",
7,
)]
.into(),
}],
)
.unwrap();
let publication = RunPublicationHandle::compile_exact(
snapshot,
"worker-model",
IngressProtocol::Responses,
&CanonicalDigest::of_bytes(TOKEN.as_bytes()),
)
.unwrap();
VerifiedRunRequestAuthority::new(
RunRequestLocator::new(
WorkspaceId::parse("workspace").unwrap(),
"task/one",
"run/one",
"lease/one",
"plan/one/revision/7/digest/sha256:abc",
observation_metadata(harness),
)
.unwrap(),
publication,
safety,
false,
)
.unwrap()
}
#[test]
fn unknown_native_harness_cannot_enter_verified_run_observation() {
for harness in ["unknown", "", "qoder_cli", "Qoder"] {
assert!(matches!(
RunObservationMetadata::new(
"plan/one",
7,
"publication/one",
harness,
None,
None,
None
),
Err(RunRequestAuthorityError::Denied)
));
}
}
#[test]
fn search_permission_is_derived_only_from_verified_run_network_access() {
for allowed in [false, true] {
let mut run = verified(Arc::new(Safety(AtomicUsize::new(0))));
run.network_allowed = allowed;
let authority = GatewayRequestAuthority::new(empty_global())
.with_run_request_authority(Arc::new(Authority(run)));
let request = authority
.begin(
IngressProtocol::Responses,
Some("Bearer hr_run_model_test-token"),
)
.unwrap()
.authorize_alias("worker-model", std::time::Instant::now())
.unwrap();
assert_eq!(request.web_search_allowed(), allowed);
}
}
#[test]
fn verified_run_emits_exact_relation_without_transport_supplied_identity() {
use std::sync::mpsc;
use std::time::Duration;
use hiroute_domain::RunObservationLink;
use crate::server::core_runtime::observation::{
GatewayObservation, GatewayObservationSinks, ObservationAck, ObservationNack,
ObservationRecord, ObservationRecordSink, OtelContentPolicy, accounted_acknowledgement,
};
struct Capture(mpsc::Sender<Vec<u8>>);
impl ObservationRecordSink for Capture {
fn deliver(
&self,
record: &ObservationRecord,
) -> Result<ObservationAck, ObservationNack> {
self.0.send(record.payload().to_vec()).unwrap();
Ok(accounted_acknowledgement(record))
}
}
for harness in ["codex", "claude", "qoder", "pi", "dsh", "opencode"] {
let authority = GatewayRequestAuthority::new(empty_global())
.with_run_request_authority(Arc::new(Authority(verified_for_harness(
Arc::new(Safety(AtomicUsize::new(0))),
harness,
))));
let request = authority
.begin(IngressProtocol::Responses, Some(&format!("Bearer {TOKEN}")))
.unwrap()
.authorize_alias("worker-model", std::time::Instant::now())
.unwrap();
let (sender, receiver) = mpsc::channel();
let mut sinks = GatewayObservationSinks::discard();
sinks.run_relation = Arc::new(Capture(sender));
let observation = GatewayObservation::with_sinks_and_policy_and_workspace_key(
true,
64 * 1024,
sinks,
OtelContentPolicy::Disabled,
[7_u8; 32],
);
let _request_observation = observation.begin_request_with_content(
&request,
IngressProtocol::Responses,
&crate::context_hold::ContextIdentityFacts::request_scoped(),
true,
None,
);
let link: RunObservationLink =
serde_json::from_slice(&receiver.recv_timeout(Duration::from_secs(1)).unwrap())
.unwrap();
assert_eq!(link.workspace_id.as_str(), "workspace");
assert_eq!(link.task_id, "task/one");
assert_eq!(link.run_id, "run/one");
assert_eq!(link.plan_id, "plan/one");
assert_eq!(link.plan_revision, "7");
assert_eq!(link.publication_ref, "publication/3/digest/sha256:abc");
assert_eq!(link.harness_id, harness);
assert_eq!(link.protocol_kind, "responses");
assert_eq!(
link.native_session_id.as_deref(),
Some("native/session-one")
);
assert_eq!(link.parent_context_ref.as_deref(), Some("task/root"));
assert_eq!(link.continued_from_run_id.as_deref(), Some("run/zero"));
assert!(!link.producer_epoch.is_empty());
assert!(link.source_event_id.starts_with("relation-event-"));
}
}
#[cfg(unix)]
#[test]
fn production_listener_denies_injected_search_before_credential_resolution() {
use crate::server::composition::{
CredentialLease, CredentialResolver, PortError, ProductionPorts,
};
use std::io::{Read, Write};
use std::os::unix::fs::DirBuilderExt;
const CHILD: &str = "HIROUTE_SEARCH_DENIAL_TEST_CHILD";
if std::env::var_os(CHILD).is_none() {
struct OwnedPrivateDirectory(std::path::PathBuf);
impl Drop for OwnedPrivateDirectory {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
let root = OwnedPrivateDirectory(std::env::temp_dir().join(format!(
"hiroute-search-denial-{}-{}",
std::process::id(),
DIRECTORY_SEQUENCE.fetch_add(1, Ordering::Relaxed),
)));
std::fs::DirBuilder::new()
.mode(0o700)
.create(&root.0)
.unwrap();
let output = std::process::Command::new(std::env::current_exe().unwrap())
.args(["--exact", "server::dispatch::run::tests::production_listener_denies_injected_search_before_credential_resolution", "--nocapture"])
.env(CHILD, "1").env("HIROUTE_REPLAY_ROOT", root.0.join("replay"))
.output().unwrap();
assert!(
output.status.success(),
"{}",
String::from_utf8_lossy(&output.stderr)
);
assert!(String::from_utf8_lossy(&output.stdout).contains("1 passed"));
return;
}
struct Credentials(AtomicUsize);
#[async_trait::async_trait]
impl CredentialResolver for Credentials {
fn acquire(&self, _: &str) -> Result<CredentialLease, PortError> {
self.0.fetch_add(1, Ordering::Relaxed);
Err(PortError::Rejected)
}
async fn lease_exact(
&self,
_: crate::ports::CredentialLeaseRequest<'_>,
_: &crate::ports::ExecutionScope,
) -> Result<Option<crate::ports::CredentialLease>, PortError> {
self.0.fetch_add(1, Ordering::Relaxed);
Err(PortError::Rejected)
}
}
let credentials = Arc::new(Credentials(AtomicUsize::new(0)));
let mut ports = ProductionPorts::fail_closed(empty_global());
ports.credentials = credentials.clone();
let runtime = crate::server::core_runtime::ProductionGatewayRuntime::compose(ports)
.with_run_request_authority(Arc::new(Authority(verified(Arc::new(Safety(
AtomicUsize::new(0),
))))));
let address = std::net::TcpListener::bind("127.0.0.1:0")
.unwrap()
.local_addr()
.unwrap();
let mut gateway = crate::server::GatewayLauncher::from_runtime(address, Arc::new(runtime))
.unwrap()
.start_managed()
.unwrap();
let body = r#"{"model":"worker-model","input":"injected search","tools":[{"type":"web_search","external_web_access":true}]}"#;
let mut stream = std::net::TcpStream::connect(address).unwrap();
stream
.set_read_timeout(Some(std::time::Duration::from_secs(5)))
.unwrap();
write!(stream, "POST /v1/responses HTTP/1.1\r\nHost: {address}\r\nAuthorization: Bearer {TOKEN}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).unwrap();
let mut response = String::new();
stream
.take(32 * 1024)
.read_to_string(&mut response)
.unwrap();
gateway.shutdown();
gateway.join(std::time::Duration::from_secs(5)).unwrap();
assert!(response.starts_with("HTTP/1.1 403"), "{response}");
assert!(response.contains("WORKER_NETWORK_DENIED"), "{response}");
assert_eq!(credentials.0.load(Ordering::Relaxed), 0);
}
#[test]
fn exact_run_token_uses_its_own_pinned_publication_without_a_global_publication() {
let safety = Arc::new(Safety(AtomicUsize::new(0)));
let authority = GatewayRequestAuthority::new(empty_global())
.with_run_request_authority(Arc::new(Authority(verified(Arc::clone(&safety)))));
let request = authority
.begin(
IngressProtocol::Responses,
Some("Bearer hr_run_model_test-token"),
)
.unwrap()
.authorize_alias("worker-model", std::time::Instant::now())
.unwrap();
assert_eq!(request.served_model_id(), "worker-model");
assert_eq!(safety.0.load(Ordering::Relaxed), 1);
}
#[test]
fn run_authority_never_falls_back_to_a_different_alias_or_token() {
let authority = GatewayRequestAuthority::new(empty_global()).with_run_request_authority(
Arc::new(Authority(verified(Arc::new(Safety(AtomicUsize::new(0)))))),
);
let wrong_token = authority.begin(
IngressProtocol::Responses,
Some("Bearer hr_run_model_other-token"),
);
assert!(matches!(
wrong_token,
Err(super::super::DispatchError::Unauthorized)
));
let wrong_alias = authority
.begin(
IngressProtocol::Responses,
Some("Bearer hr_run_model_test-token"),
)
.unwrap()
.authorize_alias("ordinary-model", std::time::Instant::now());
assert!(matches!(
wrong_alias,
Err(super::super::DispatchError::Unauthorized)
));
}
#[test]
fn same_task_conversation_does_not_authorize_another_run() {
let mut other = verified(Arc::new(Safety(AtomicUsize::new(0))));
// Keeping the task identity does not transfer the first run's credential.
assert_eq!(other.locator.task_id(), "task/one");
other.locator.run_id = "run/two".into();
assert!(matches!(
other.begin(&format!("Bearer {TOKEN}"), IngressProtocol::Responses),
Err(RunRequestAuthorityError::Denied)
));
}
}