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
use serde::{Deserialize, Serialize};
use zeroize::{Zeroize, Zeroizing};
use super::{OperationValidationError, OwnedEffectKind, OwnedEffectV1, validate_scope_identifier};
use crate::{AgentIngressProtocolV1, CanonicalDigest};
pub const AGENT_ACCESS_GRANT_EFFECT_SCHEMA_V1: &str = "hiroute.agent-access-grant-effect/v1";
const MATERIAL_ENTROPY_BYTES: usize = 32;
const MATERIAL_BASE64URL_BYTES: usize = 43;
const BASE64URL: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
/// A HiRoute-local bearer, generated from 256 bits of CSPRNG entropy or supplied by the user.
///
/// This type deliberately implements neither `Debug`, `Display`, `Clone`, nor serde traits.
/// Callers may only expose it at the explicitly protected helper/header boundary.
///
/// ```compile_fail
/// use hiroute_domain::AgentAccessGrantMaterial;
/// fn requires_debug<T: std::fmt::Debug>() {}
/// requires_debug::<AgentAccessGrantMaterial>();
/// ```
///
/// ```compile_fail
/// use hiroute_domain::AgentAccessGrantMaterial;
/// fn requires_display<T: std::fmt::Display>() {}
/// requires_display::<AgentAccessGrantMaterial>();
/// ```
///
/// ```compile_fail
/// use hiroute_domain::AgentAccessGrantMaterial;
/// fn requires_serialize<T: serde::Serialize>() {}
/// requires_serialize::<AgentAccessGrantMaterial>();
/// ```
pub struct AgentAccessGrantMaterial(Zeroizing<Vec<u8>>);
impl AgentAccessGrantMaterial {
/// Encodes exactly 256 bits supplied by the storage authority. The storage implementation is
/// responsible for filling `entropy` directly from the operating system CSPRNG.
pub fn from_csprng_entropy(mut entropy: [u8; MATERIAL_ENTROPY_BYTES]) -> Self {
let encoded = encode_base64url_no_pad(&entropy);
entropy.zeroize();
Self(Zeroizing::new(encoded))
}
/// Reconstructs material only after an authenticated AEAD record has been opened.
pub fn from_authenticated_storage(bytes: Vec<u8>) -> Result<Self, OperationValidationError> {
let bytes = Zeroizing::new(bytes);
if !valid_user_agent_token(&bytes) {
return Err(OperationValidationError::InvalidAgentAccessGrantMaterial);
}
Ok(Self(bytes))
}
pub fn from_user_input(bytes: Vec<u8>) -> Result<Self, OperationValidationError> {
Self::from_authenticated_storage(bytes)
}
pub fn expose(&self) -> &[u8] {
self.0.as_slice()
}
pub fn sha256(&self) -> CanonicalDigest {
CanonicalDigest::of_bytes(self.expose())
}
}
/// A custom bearer must be safe in HTTP headers and both native client configuration formats.
/// The minimum length avoids accidentally accepting a short human password as an API bearer.
pub fn valid_user_agent_token(bytes: &[u8]) -> bool {
(16..=128).contains(&bytes.len())
&& bytes
.iter()
.all(|byte| byte.is_ascii_alphanumeric() || b"._~-".contains(byte))
}
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentAccessGrantScopeV1 {
connection_id: String,
model_grant: crate::AgentModelGrantV2,
}
impl AgentAccessGrantScopeV1 {
pub fn new(
connection_id: impl Into<String>,
model_grant: crate::AgentModelGrantV2,
) -> Result<Self, OperationValidationError> {
let scope = Self {
connection_id: connection_id.into(),
model_grant,
};
scope.validate()?;
Ok(scope)
}
pub fn validate(&self) -> Result<(), OperationValidationError> {
validate_scope_identifier(&self.connection_id)?;
if !self.connection_id.starts_with("agent-connection/") {
return Err(OperationValidationError::InvalidAgentAccessGrantScope);
}
self.model_grant
.validate()
.map_err(|_| OperationValidationError::InvalidAgentAccessGrantScope)
}
pub fn connection_id(&self) -> &str {
&self.connection_id
}
pub const fn protocol(&self) -> AgentIngressProtocolV1 {
self.model_grant.protocol
}
pub fn model_grant(&self) -> &crate::AgentModelGrantV2 {
&self.model_grant
}
pub fn digest(&self) -> Result<CanonicalDigest, OperationValidationError> {
self.validate()?;
CanonicalDigest::of(self).map_err(OperationValidationError::Digest)
}
}
#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentAccessGrantMutationKindV1 {
Ensure,
Revoke,
}
#[derive(schemars::JsonSchema, Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum AgentAccessGrantMaterialActionV1 {
#[default]
Preserve,
Regenerate,
Set {
input_slot: String,
fingerprint: CanonicalDigest,
},
}
impl AgentAccessGrantMaterialActionV1 {
pub fn input(&self) -> Option<(&str, &CanonicalDigest)> {
match self {
Self::Set {
input_slot,
fingerprint,
} => Some((input_slot, fingerprint)),
_ => None,
}
}
}
/// A durable non-secret request. Material is intentionally absent and can only be generated by
/// the SecretStore after the Operation has crossed durable Apply admission.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentAccessGrantMutationV1 {
kind: AgentAccessGrantMutationKindV1,
owner_scope: String,
connection_id: String,
expected_generation: u64,
#[serde(skip_serializing_if = "Option::is_none")]
desired_scope: Option<AgentAccessGrantScopeV1>,
#[serde(default)]
material_action: AgentAccessGrantMaterialActionV1,
}
impl AgentAccessGrantMutationV1 {
pub fn ensure(
owner_scope: impl Into<String>,
desired_scope: AgentAccessGrantScopeV1,
expected_generation: u64,
) -> Result<Self, OperationValidationError> {
let mutation = Self {
kind: AgentAccessGrantMutationKindV1::Ensure,
owner_scope: owner_scope.into(),
connection_id: desired_scope.connection_id.clone(),
expected_generation,
desired_scope: Some(desired_scope),
material_action: AgentAccessGrantMaterialActionV1::Preserve,
};
mutation.validate()?;
Ok(mutation)
}
pub fn with_material_action(
mut self,
material_action: AgentAccessGrantMaterialActionV1,
) -> Result<Self, OperationValidationError> {
self.material_action = material_action;
self.validate()?;
Ok(self)
}
pub fn revoke(
owner_scope: impl Into<String>,
connection_id: impl Into<String>,
expected_generation: u64,
) -> Result<Self, OperationValidationError> {
let mutation = Self {
kind: AgentAccessGrantMutationKindV1::Revoke,
owner_scope: owner_scope.into(),
connection_id: connection_id.into(),
expected_generation,
desired_scope: None,
material_action: AgentAccessGrantMaterialActionV1::Preserve,
};
mutation.validate()?;
Ok(mutation)
}
pub fn validate(&self) -> Result<(), OperationValidationError> {
validate_scope_identifier(&self.owner_scope)?;
validate_scope_identifier(&self.connection_id)?;
if !self.connection_id.starts_with("agent-connection/") {
return Err(OperationValidationError::InvalidAgentAccessGrantMutation);
}
if let Some((input_slot, fingerprint)) = self.material_action.input() {
validate_scope_identifier(input_slot)?;
if !input_slot.starts_with("candidate/native/agent-token-")
|| CanonicalDigest::parse(fingerprint.as_str().to_owned()).is_err()
{
return Err(OperationValidationError::InvalidAgentAccessGrantMutation);
}
}
match (self.kind, &self.desired_scope) {
(AgentAccessGrantMutationKindV1::Ensure, Some(scope)) => {
scope.validate()?;
if scope.connection_id != self.connection_id {
return Err(OperationValidationError::InvalidAgentAccessGrantMutation);
}
}
(AgentAccessGrantMutationKindV1::Revoke, None)
if matches!(
self.material_action,
AgentAccessGrantMaterialActionV1::Preserve
) => {}
_ => return Err(OperationValidationError::InvalidAgentAccessGrantMutation),
}
Ok(())
}
pub const fn kind(&self) -> AgentAccessGrantMutationKindV1 {
self.kind
}
pub fn owner_scope(&self) -> &str {
&self.owner_scope
}
pub fn connection_id(&self) -> &str {
&self.connection_id
}
pub const fn expected_generation(&self) -> u64 {
self.expected_generation
}
pub fn desired_scope(&self) -> Option<&AgentAccessGrantScopeV1> {
self.desired_scope.as_ref()
}
pub fn material_action(&self) -> &AgentAccessGrantMaterialActionV1 {
&self.material_action
}
}
/// The only durable/public projection of grant material.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentAccessGrantRefV1 {
grant_id: String,
owner_scope: String,
scope: AgentAccessGrantScopeV1,
generation: u64,
material_sha256: CanonicalDigest,
}
impl AgentAccessGrantRefV1 {
pub fn new(
grant_id: impl Into<String>,
owner_scope: impl Into<String>,
scope: AgentAccessGrantScopeV1,
generation: u64,
material_sha256: CanonicalDigest,
) -> Result<Self, OperationValidationError> {
let reference = Self {
grant_id: grant_id.into(),
owner_scope: owner_scope.into(),
scope,
generation,
material_sha256,
};
reference.validate()?;
Ok(reference)
}
pub fn validate(&self) -> Result<(), OperationValidationError> {
validate_scope_identifier(&self.owner_scope)?;
self.scope.validate()?;
let valid_id = self.grant_id.len() == 38
&& self.grant_id.starts_with("grant_")
&& self.grant_id[6..]
.bytes()
.all(|byte| byte.is_ascii_hexdigit());
if !valid_id
|| self.generation == 0
|| CanonicalDigest::parse(self.material_sha256.as_str().to_owned()).is_err()
{
return Err(OperationValidationError::InvalidAgentAccessGrantRef);
}
Ok(())
}
pub fn grant_id(&self) -> &str {
&self.grant_id
}
pub fn owner_scope(&self) -> &str {
&self.owner_scope
}
pub fn connection_id(&self) -> &str {
self.scope.connection_id()
}
pub fn scope(&self) -> &AgentAccessGrantScopeV1 {
&self.scope
}
pub const fn generation(&self) -> u64 {
self.generation
}
pub fn material_sha256(&self) -> &CanonicalDigest {
&self.material_sha256
}
/// Reconstructs the non-secret staged reference returned by an operation-bound SecretStore
/// observation. Callers must obtain `effect` from `observe_agent_access_grant`; this parser
/// additionally binds every field back to the immutable ensure mutation.
pub fn from_ensure_effect(
effect: &OwnedEffectV1,
mutation: &AgentAccessGrantMutationV1,
) -> Result<Self, OperationValidationError> {
mutation.validate()?;
if mutation.kind != AgentAccessGrantMutationKindV1::Ensure
|| !is_agent_access_grant_effect(effect)
|| effect.effect_id != format!("agent-access-grant:{}", mutation.connection_id)
|| effect.target != mutation.connection_id
{
return Err(OperationValidationError::InvalidAgentAccessGrantRef);
}
let metadata = effect
.compensation
.as_object()
.ok_or(OperationValidationError::InvalidAgentAccessGrantRef)?;
let text = |field: &str| {
metadata
.get(field)
.and_then(serde_json::Value::as_str)
.ok_or(OperationValidationError::InvalidAgentAccessGrantRef)
};
let connection_id = text("connection_id")?;
let owner_scope = text("owner_scope")?;
let grant_id = text("grant_id")?;
let scope_hash = CanonicalDigest::parse(text("scope_hash")?.to_owned())
.map_err(|_| OperationValidationError::InvalidAgentAccessGrantRef)?;
let material_sha256 = CanonicalDigest::parse(text("material_sha256")?.to_owned())
.map_err(|_| OperationValidationError::InvalidAgentAccessGrantRef)?;
let generation = metadata
.get("generation")
.and_then(serde_json::Value::as_u64)
.ok_or(OperationValidationError::InvalidAgentAccessGrantRef)?;
let desired_scope = mutation
.desired_scope
.as_ref()
.ok_or(OperationValidationError::InvalidAgentAccessGrantRef)?;
if connection_id != mutation.connection_id
|| owner_scope != mutation.owner_scope
|| scope_hash != desired_scope.digest()?
|| effect.after_fingerprint.as_ref() != Some(&material_sha256)
|| !matches!(
generation,
value if value == mutation.expected_generation
|| mutation.expected_generation.checked_add(1) == Some(value)
)
{
return Err(OperationValidationError::InvalidAgentAccessGrantRef);
}
Self::new(
grant_id,
owner_scope,
desired_scope.clone(),
generation,
material_sha256,
)
}
}
pub fn is_agent_access_grant_effect(effect: &OwnedEffectV1) -> bool {
effect.kind == OwnedEffectKind::Secret
&& effect.effect_id.starts_with("agent-access-grant:")
&& effect
.compensation
.get("schema")
.and_then(serde_json::Value::as_str)
== Some(AGENT_ACCESS_GRANT_EFFECT_SCHEMA_V1)
}
fn encode_base64url_no_pad(input: &[u8; MATERIAL_ENTROPY_BYTES]) -> Vec<u8> {
let mut output = Vec::with_capacity(MATERIAL_BASE64URL_BYTES);
let mut index = 0;
while index + 3 <= input.len() {
let value = (u32::from(input[index]) << 16)
| (u32::from(input[index + 1]) << 8)
| u32::from(input[index + 2]);
output.push(BASE64URL[((value >> 18) & 0x3f) as usize]);
output.push(BASE64URL[((value >> 12) & 0x3f) as usize]);
output.push(BASE64URL[((value >> 6) & 0x3f) as usize]);
output.push(BASE64URL[(value & 0x3f) as usize]);
index += 3;
}
let value = (u32::from(input[index]) << 16) | (u32::from(input[index + 1]) << 8);
output.push(BASE64URL[((value >> 18) & 0x3f) as usize]);
output.push(BASE64URL[((value >> 12) & 0x3f) as usize]);
output.push(BASE64URL[((value >> 6) & 0x3f) as usize]);
debug_assert_eq!(output.len(), MATERIAL_BASE64URL_BYTES);
output
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
#[test]
fn material_is_fixed_printable_base64url_and_hash_only_is_serializable() {
let material = AgentAccessGrantMaterial::from_csprng_entropy([0xa5; 32]);
assert_eq!(material.expose().len(), 43);
assert!(
material
.expose()
.iter()
.all(|byte| BASE64URL.contains(byte))
);
let hash = material.sha256();
assert_eq!(hash.as_str().len(), 71);
}
#[test]
fn custom_material_accepts_only_bounded_header_safe_ascii() {
for invalid in [
b"short".as_slice(),
b"contains a space-and-long".as_slice(),
b"contains\nnewline-and-long".as_slice(),
b"contains:colon-and-long".as_slice(),
] {
assert!(!valid_user_agent_token(invalid));
assert!(AgentAccessGrantMaterial::from_user_input(invalid.to_vec()).is_err());
}
let valid = b"custom-token_01.~abcd";
assert!(valid_user_agent_token(valid));
assert_eq!(
AgentAccessGrantMaterial::from_user_input(valid.to_vec())
.unwrap()
.expose(),
valid
);
}
#[test]
fn ensure_effect_reference_rejects_a_mismatched_effect_identity() {
let scope = AgentAccessGrantScopeV1::new(
"agent-connection/claude",
crate::AgentModelGrantV2::seal(
AgentIngressProtocolV1::Messages,
std::collections::BTreeMap::from([(
"hiroute/0011223344556677".into(),
crate::AgentModelRouteV2::Plan {
plan_id: crate::AgentPlanId::parse("plan/test").unwrap(),
alias: crate::ModelAlias::parse("hiroute/0011223344556677").unwrap(),
revision: 1,
semantic_digest: CanonicalDigest::of_bytes(b"plan-grant"),
},
)]),
)
.unwrap(),
)
.unwrap();
let mutation =
AgentAccessGrantMutationV1::ensure("personal/default", scope.clone(), 0).unwrap();
let material = AgentAccessGrantMaterial::from_csprng_entropy([0x5a; 32]);
let hash = material.sha256();
let effect = OwnedEffectV1 {
effect_id: "agent-access-grant:agent-connection/other".to_owned(),
kind: OwnedEffectKind::Secret,
target: "agent-connection/claude".to_owned(),
before_fingerprint: None,
after_fingerprint: Some(hash.clone()),
compensation: json!({
"schema": AGENT_ACCESS_GRANT_EFFECT_SCHEMA_V1,
"operation_id": "op_11111111111111111111111111111111",
"connection_id": "agent-connection/claude",
"owner_scope": "personal/default",
"grant_id": "grant_11111111111111111111111111111111",
"generation": 1,
"scope_hash": scope.digest().unwrap(),
"material_sha256": hash,
})
.into(),
};
assert!(AgentAccessGrantRefV1::from_ensure_effect(&effect, &mutation).is_err());
}
}