Skip to content

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

Rust

omx(team): auto-checkpoint worker-2 [3]

bellman57b3e3258bf2
diff --git a/rust/crates/runtime/src/approval_tokens.rs b/rust/crates/runtime/src/approval_tokens.rs
new file mode 100644
index 00000000..e220e442
--- /dev/null
+++ b/rust/crates/runtime/src/approval_tokens.rs
@@ -0,0 +1,495 @@
+use std::collections::BTreeMap;
+
+/// Machine-readable policy exception scope that an approval token may override.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ApprovalScope {
+ pub policy: String,
+ pub action: String,
+ pub repository: Option<String>,
+ pub branch: Option<String>,
+}
+
+impl ApprovalScope {
+ #[must_use]
+ pub fn new(policy: impl Into<String>, action: impl Into<String>) -> Self {
+ Self {
+ policy: policy.into(),
+ action: action.into(),
+ repository: None,
+ branch: None,
+ }
+ }
+
+ #[must_use]
+ pub fn with_repository(mut self, repository: impl Into<String>) -> Self {
+ self.repository = Some(repository.into());
+ self
+ }
+
+ #[must_use]
+ pub fn with_branch(mut self, branch: impl Into<String>) -> Self {
+ self.branch = Some(branch.into());
+ self
+ }
+}
+
+/// Actor/session hop recorded when an approval is delegated or consumed.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ApprovalDelegationHop {
+ pub actor: String,
+ pub session_id: Option<String>,
+ pub reason: String,
+}
+
+impl ApprovalDelegationHop {
+ #[must_use]
+ pub fn new(actor: impl Into<String>, reason: impl Into<String>) -> Self {
+ Self {
+ actor: actor.into(),
+ session_id: None,
+ reason: reason.into(),
+ }
+ }
+
+ #[must_use]
+ pub fn with_session_id(mut self, session_id: impl Into<String>) -> Self {
+ self.session_id = Some(session_id.into());
+ self
+ }
+}
+
+/// Current lifecycle state for a policy-exception approval token.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ApprovalTokenStatus {
+ Pending,
+ Granted,
+ Consumed,
+ Expired,
+ Revoked,
+}
+
+impl ApprovalTokenStatus {
+ #[must_use]
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::Pending => "approval_pending",
+ Self::Granted => "approval_granted",
+ Self::Consumed => "approval_consumed",
+ Self::Expired => "approval_expired",
+ Self::Revoked => "approval_revoked",
+ }
+ }
+}
+
+/// Typed policy errors returned when a token cannot authorize a blocked action.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ApprovalTokenError {
+ NoApproval,
+ ApprovalPending,
+ ApprovalExpired,
+ ApprovalRevoked,
+ ApprovalAlreadyConsumed,
+ ScopeMismatch {
+ expected: ApprovalScope,
+ actual: ApprovalScope,
+ },
+ UnauthorizedDelegate {
+ expected: String,
+ actual: String,
+ },
+}
+
+impl ApprovalTokenError {
+ #[must_use]
+ pub fn as_str(&self) -> &'static str {
+ match self {
+ Self::NoApproval => "no_approval",
+ Self::ApprovalPending => "approval_pending",
+ Self::ApprovalExpired => "approval_expired",
+ Self::ApprovalRevoked => "approval_revoked",
+ Self::ApprovalAlreadyConsumed => "approval_already_consumed",
+ Self::ScopeMismatch { .. } => "approval_scope_mismatch",
+ Self::UnauthorizedDelegate { .. } => "approval_unauthorized_delegate",
+ }
+ }
+}
+
+/// Approval grant bound to a policy/action scope, approving owner, and executor.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ApprovalTokenGrant {
+ pub token: String,
+ pub scope: ApprovalScope,
+ pub approving_actor: String,
+ pub approved_executor: String,
+ pub status: ApprovalTokenStatus,
+ pub expires_at_epoch_seconds: Option<u64>,
+ pub max_uses: u32,
+ pub uses: u32,
+ delegation_chain: Vec<ApprovalDelegationHop>,
+}
+
+impl ApprovalTokenGrant {
+ #[must_use]
+ pub fn pending(
+ token: impl Into<String>,
+ scope: ApprovalScope,
+ approving_actor: impl Into<String>,
+ approved_executor: impl Into<String>,
+ ) -> Self {
+ Self {
+ token: token.into(),
+ scope,
+ approving_actor: approving_actor.into(),
+ approved_executor: approved_executor.into(),
+ status: ApprovalTokenStatus::Pending,
+ expires_at_epoch_seconds: None,
+ max_uses: 1,
+ uses: 0,
+ delegation_chain: Vec::new(),
+ }
+ }
+
+ #[must_use]
+ pub fn granted(
+ token: impl Into<String>,
+ scope: ApprovalScope,
+ approving_actor: impl Into<String>,
+ approved_executor: impl Into<String>,
+ ) -> Self {
+ Self::pending(token, scope, approving_actor, approved_executor).approve()
+ }
+
+ #[must_use]
+ pub fn approve(mut self) -> Self {
+ self.status = ApprovalTokenStatus::Granted;
+ self
+ }
+
+ #[must_use]
+ pub fn expires_at(mut self, epoch_seconds: u64) -> Self {
+ self.expires_at_epoch_seconds = Some(epoch_seconds);
+ self
+ }
+
+ #[must_use]
+ pub fn with_max_uses(mut self, max_uses: u32) -> Self {
+ self.max_uses = max_uses.max(1);
+ self
+ }
+
+ #[must_use]
+ pub fn with_delegation_hop(mut self, hop: ApprovalDelegationHop) -> Self {
+ self.delegation_chain.push(hop);
+ self
+ }
+
+ #[must_use]
+ pub fn delegation_chain(&self) -> &[ApprovalDelegationHop] {
+ &self.delegation_chain
+ }
+}
+
+/// Auditable result of verifying or consuming an approval token.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ApprovalTokenAudit {
+ pub token: String,
+ pub scope: ApprovalScope,
+ pub approving_actor: String,
+ pub executing_actor: String,
+ pub status: ApprovalTokenStatus,
+ pub delegated_execution: bool,
+ pub delegation_chain: Vec<ApprovalDelegationHop>,
+ pub uses: u32,
+ pub max_uses: u32,
+}
+
+/// In-memory approval-token ledger with one-time-use and replay protection.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ApprovalTokenLedger {
+ grants: BTreeMap<String, ApprovalTokenGrant>,
+}
+
+impl ApprovalTokenLedger {
+ #[must_use]
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn insert(&mut self, grant: ApprovalTokenGrant) {
+ self.grants.insert(grant.token.clone(), grant);
+ }
+
+ #[must_use]
+ pub fn get(&self, token: &str) -> Option<&ApprovalTokenGrant> {
+ self.grants.get(token)
+ }
+
+ pub fn revoke(&mut self, token: &str) -> Result<ApprovalTokenAudit, ApprovalTokenError> {
+ let grant = self
+ .grants
+ .get_mut(token)
+ .ok_or(ApprovalTokenError::NoApproval)?;
+ grant.status = ApprovalTokenStatus::Revoked;
+ Ok(Self::audit_for(grant, &grant.approved_executor))
+ }
+
+ pub fn verify(
+ &self,
+ token: &str,
+ scope: &ApprovalScope,
+ executing_actor: &str,
+ now_epoch_seconds: u64,
+ ) -> Result<ApprovalTokenAudit, ApprovalTokenError> {
+ let grant = self.grants.get(token).ok_or(ApprovalTokenError::NoApproval)?;
+ Self::validate_grant(grant, scope, executing_actor, now_epoch_seconds)?;
+ Ok(Self::audit_for(grant, executing_actor))
+ }
+
+ pub fn consume(
+ &mut self,
+ token: &str,
+ scope: &ApprovalScope,
+ executing_actor: &str,
+ now_epoch_seconds: u64,
+ ) -> Result<ApprovalTokenAudit, ApprovalTokenError> {
+ let grant = self
+ .grants
+ .get_mut(token)
+ .ok_or(ApprovalTokenError::NoApproval)?;
+ Self::validate_grant(grant, scope, executing_actor, now_epoch_seconds)?;
+ grant.uses += 1;
+ if grant.uses >= grant.max_uses {
+ grant.status = ApprovalTokenStatus::Consumed;
+ }
+ Ok(Self::audit_for(grant, executing_actor))
+ }
+
+ fn validate_grant(
+ grant: &ApprovalTokenGrant,
+ scope: &ApprovalScope,
+ executing_actor: &str,
+ now_epoch_seconds: u64,
+ ) -> Result<(), ApprovalTokenError> {
+ match grant.status {
+ ApprovalTokenStatus::Pending => return Err(ApprovalTokenError::ApprovalPending),
+ ApprovalTokenStatus::Consumed => return Err(ApprovalTokenError::ApprovalAlreadyConsumed),
+ ApprovalTokenStatus::Expired => return Err(ApprovalTokenError::ApprovalExpired),
+ ApprovalTokenStatus::Revoked => return Err(ApprovalTokenError::ApprovalRevoked),
+ ApprovalTokenStatus::Granted => {}
+ }
+
+ if grant
+ .expires_at_epoch_seconds
+ .is_some_and(|expires_at| now_epoch_seconds > expires_at)
+ {
+ return Err(ApprovalTokenError::ApprovalExpired);
+ }
+
+ if grant.uses >= grant.max_uses {
+ return Err(ApprovalTokenError::ApprovalAlreadyConsumed);
+ }
+
+ if grant.scope != *scope {
+ return Err(ApprovalTokenError::ScopeMismatch {
+ expected: grant.scope.clone(),
+ actual: scope.clone(),
+ });
+ }
+
+ if grant.approved_executor != executing_actor {
+ return Err(ApprovalTokenError::UnauthorizedDelegate {
+ expected: grant.approved_executor.clone(),
+ actual: executing_actor.to_string(),
+ });
+ }
+
+ Ok(())
+ }
+
+ fn audit_for(grant: &ApprovalTokenGrant, executing_actor: &str) -> ApprovalTokenAudit {
+ let mut delegation_chain = grant.delegation_chain.clone();
+ if delegation_chain.is_empty() {
+ delegation_chain.push(ApprovalDelegationHop::new(
+ grant.approving_actor.clone(),
+ "approval granted",
+ ));
+ }
+ if grant.approving_actor != executing_actor
+ && !delegation_chain.iter().any(|hop| hop.actor == executing_actor)
+ {
+ delegation_chain.push(ApprovalDelegationHop::new(
+ executing_actor.to_string(),
+ "delegated execution",
+ ));
+ }
+
+ ApprovalTokenAudit {
+ token: grant.token.clone(),
+ scope: grant.scope.clone(),
+ approving_actor: grant.approving_actor.clone(),
+ executing_actor: executing_actor.to_string(),
+ status: grant.status,
+ delegated_execution: grant.approving_actor != executing_actor,
+ delegation_chain,
+ uses: grant.uses,
+ max_uses: grant.max_uses,
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{
+ ApprovalDelegationHop, ApprovalScope, ApprovalTokenError, ApprovalTokenGrant,
+ ApprovalTokenLedger, ApprovalTokenStatus,
+ };
+
+ #[test]
+ fn approval_token_blocks_until_owner_grants_policy_exception() {
+ let mut ledger = ApprovalTokenLedger::new();
+ let scope = ApprovalScope::new("main_push_forbidden", "git push")
+ .with_repository("sisyphus/claw-code")
+ .with_branch("main");
+ ledger.insert(ApprovalTokenGrant::pending(
+ "tok-pending",
+ scope.clone(),
+ "repo-owner",
+ "release-bot",
+ ));
+
+ assert!(matches!(
+ ledger.verify("tok-missing", &scope, "release-bot", 10),
+ Err(ApprovalTokenError::NoApproval)
+ ));
+ assert!(matches!(
+ ledger.verify("tok-pending", &scope, "release-bot", 10),
+ Err(ApprovalTokenError::ApprovalPending)
+ ));
+
+ ledger.insert(ApprovalTokenGrant::granted(
+ "tok-granted",
+ scope.clone(),
+ "repo-owner",
+ "release-bot",
+ ));
+ let audit = ledger
+ .verify("tok-granted", &scope, "release-bot", 10)
+ .expect("owner approval should verify");
+
+ assert_eq!(audit.status, ApprovalTokenStatus::Granted);
+ assert_eq!(audit.approving_actor, "repo-owner");
+ assert_eq!(audit.executing_actor, "release-bot");
+ assert!(audit.delegated_execution);
+ }
+
+ #[test]
+ fn approval_token_is_one_time_use_and_rejects_replay() {
+ let mut ledger = ApprovalTokenLedger::new();
+ let scope = ApprovalScope::new("release_requires_owner", "release publish")
+ .with_repository("sisyphus/claw-code");
+ ledger.insert(ApprovalTokenGrant::granted(
+ "tok-once",
+ scope.clone(),
+ "owner",
+ "release-bot",
+ ));
+
+ let first = ledger
+ .consume("tok-once", &scope, "release-bot", 10)
+ .expect("first use should consume token");
+ assert_eq!(first.status, ApprovalTokenStatus::Consumed);
+ assert_eq!(first.uses, 1);
+
+ assert!(matches!(
+ ledger.consume("tok-once", &scope, "release-bot", 11),
+ Err(ApprovalTokenError::ApprovalAlreadyConsumed)
+ ));
+ assert_eq!(
+ ledger.get("tok-once").map(|grant| grant.status),
+ Some(ApprovalTokenStatus::Consumed)
+ );
+ }
+
+ #[test]
+ fn approval_token_rejects_scope_expansion_expiry_and_revocation() {
+ let mut ledger = ApprovalTokenLedger::new();
+ let scope = ApprovalScope::new("main_push_forbidden", "git push")
+ .with_repository("sisyphus/claw-code")
+ .with_branch("main");
+ let dev_scope = ApprovalScope::new("main_push_forbidden", "git push")
+ .with_repository("sisyphus/claw-code")
+ .with_branch("dev");
+
+ ledger.insert(
+ ApprovalTokenGrant::granted("tok-expiring", scope.clone(), "owner", "bot")
+ .expires_at(20),
+ );
+
+ assert!(matches!(
+ ledger.verify("tok-expiring", &dev_scope, "bot", 10),
+ Err(ApprovalTokenError::ScopeMismatch { .. })
+ ));
+ assert!(matches!(
+ ledger.verify("tok-expiring", &scope, "bot", 21),
+ Err(ApprovalTokenError::ApprovalExpired)
+ ));
+
+ ledger.insert(ApprovalTokenGrant::granted(
+ "tok-revoked",
+ scope.clone(),
+ "owner",
+ "bot",
+ ));
+ let revoked = ledger
+ .revoke("tok-revoked")
+ .expect("revocation should be audited");
+ assert_eq!(revoked.status, ApprovalTokenStatus::Revoked);
+ assert!(matches!(
+ ledger.verify("tok-revoked", &scope, "bot", 10),
+ Err(ApprovalTokenError::ApprovalRevoked)
+ ));
+ }
+
+ #[test]
+ fn approval_token_preserves_delegation_traceability() {
+ let mut ledger = ApprovalTokenLedger::new();
+ let scope = ApprovalScope::new("deploy_requires_owner", "deploy prod");
+ ledger.insert(
+ ApprovalTokenGrant::granted("tok-delegated", scope.clone(), "owner", "deploy-bot")
+ .with_delegation_hop(
+ ApprovalDelegationHop::new("owner", "owner approval")
+ .with_session_id("session-owner"),
+ )
+ .with_delegation_hop(
+ ApprovalDelegationHop::new("lead-agent", "handoff to deploy bot")
+ .with_session_id("session-lead"),
+ ),
+ );
+
+ assert!(matches!(
+ ledger.verify("tok-delegated", &scope, "unexpected-bot", 10),
+ Err(ApprovalTokenError::UnauthorizedDelegate { expected, actual })
+ if expected == "deploy-bot" && actual == "unexpected-bot"
+ ));
+
+ let audit = ledger
+ .consume("tok-delegated", &scope, "deploy-bot", 10)
+ .expect("approved delegate should consume token");
+ let actors = audit
+ .delegation_chain
+ .iter()
+ .map(|hop| hop.actor.as_str())
+ .collect::<Vec<_>>();
+
+ assert!(audit.delegated_execution);
+ assert_eq!(actors, vec!["owner", "lead-agent", "deploy-bot"]);
+ assert_eq!(
+ audit.delegation_chain[0].session_id.as_deref(),
+ Some("session-owner")
+ );
+ assert_eq!(
+ audit.delegation_chain[1].session_id.as_deref(),
+ Some("session-lead")
+ );
+ }
+}