Struct SecurityExtension 

pub struct SecurityExtension {
    pub labels: MonotonicSet<String>,
    pub classification: Option<String>,
    pub subject: Option<SubjectExtension>,
    pub client: Option<ClientExtension>,
    pub caller_workload: Option<WorkloadIdentity>,
    pub this_workload: Option<WorkloadIdentity>,
    pub auth_method: Option<String>,
    pub objects: HashMap<String, ObjectSecurityProfile>,
    pub data: HashMap<String, DataPolicy>,
}

Security-related extensions.

Carries security labels (monotonic add-only), classification, up to four distinct identity principals, and data-policy metadata. The four principal slots map to the identity sources documented in docs/specs/delegation-hooks-rust-spec.md §4.1:

• subject — the user (or service-as-user) initiating the request
• client — the OAuth client / application brokering the request
• caller_workload — the attested workload on the inbound network peer (SPIFFE-SVID, mTLS cert chain)
• this_workload — our own gateway’s attested identity, used for outbound calls

A request can populate any subset; identity-resolver plugins are expected to fill the slots they’re configured for. Policy authors reason about all four uniformly through the subject.* / client.* / caller_workload.* / this_workload.* bag namespaces.

Fields

labels: MonotonicSet<String>

Security labels (monotonic — add-only via MonotonicSet). No remove() method — enforced at compile time.

classification: Option<String>

Data classification level.

subject: Option<SubjectExtension>

Authenticated user identity (who is calling).

client: Option<ClientExtension>

Authenticated OAuth client / application brokering the request. Distinct from subject — the same user can connect through different clients (first-party web, third-party integration), and policies sometimes want to gate on which.

caller_workload: Option<WorkloadIdentity>

The inbound caller’s attested workload identity — the network peer’s SPIFFE-SVID or mTLS-attested identity. Distinct from client (the OAuth-layer identity of the application) and subject (the user). All three can be present on the same request when an agent acts on behalf of a user through our gateway, peered via mTLS.

this_workload: Option<WorkloadIdentity>

This agent / gateway’s own workload identity — the SPIFFE-SVID or attested identity we present when making outbound calls. Populated by the host at startup, not per request.

auth_method: Option<String>

Authentication method used (e.g., “jwt”, “mtls”, “spiffe”, “api_key”).

objects: HashMap<String, ObjectSecurityProfile>

Object security profiles keyed by object name.

data: HashMap<String, DataPolicy>

Data policies keyed by data element name.

Implementations

impl SecurityExtension

pub fn add_label(&mut self, label: impl Into<String>)

Add a security label (monotonic — cannot remove).

Examples found in repository

examples/cmf_capabilities_demo.rs (line 167)

    async fn handle(
        &self,
        _payload: &MessagePayload,
        extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<MessagePayload> {
        // Can see HTTP (has read_headers)
        if let Some(ref http) = extensions.http {
            println!(
                "  [header-injector] HTTP headers visible: {:?}",
                http.request_headers
            );
        }

        // Can NOT see security subject (no read_subject)
        if let Some(ref security) = extensions.security {
            if security.subject.is_some() {
                println!("  [header-injector] WARNING: Subject visible (unexpected!)");
            } else {
                println!("  [header-injector] Security subject: not visible (no read_subject)");
            }
        }

        // COW copy to modify — tokens propagate from the executor
        let mut modified = extensions.cow_copy();

        // Add a label via MonotonicSet (has append_labels)
        if modified.labels_write_token.is_some() {
            modified.security.as_mut().unwrap().add_label("PROCESSED");
            println!("  [header-injector] Added label 'PROCESSED'");
        }

        // Inject a header via Guarded (has write_headers)
        if let Some(ref token) = modified.http_write_token {
            modified
                .http
                .as_mut()
                .unwrap()
                .write(token)
                .set_header("X-Processed-By", "header-injector");
            println!("  [header-injector] Injected header 'X-Processed-By'");
        }

        PluginResult::modify_extensions(modified)
    }
}

// ---------------------------------------------------------------------------
// Plugin: AuditLogger
// Has read_headers, read_security, read_labels capabilities.
// Read-only — just logs what it can see.
// ---------------------------------------------------------------------------

struct AuditLogger {
    cfg: PluginConfig,
}

#[async_trait]
impl Plugin for AuditLogger {
    fn config(&self) -> &PluginConfig {
        &self.cfg
    }
}

impl HookHandler<CmfHook> for AuditLogger {
    async fn handle(
        &self,
        payload: &MessagePayload,
        extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<MessagePayload> {
        let is_result = payload.message.is_tool_result();
        let phase = if is_result { "POST" } else { "PRE" };

        let tool_name = if is_result {
            payload
                .message
                .get_tool_results()
                .first()
                .map(|tr| tr.tool_name.as_str())
                .unwrap_or("unknown")
        } else {
            payload
                .message
                .get_tool_calls()
                .first()
                .map(|tc| tc.name.as_str())
                .unwrap_or("unknown")
        };

        print!("  [audit-logger] AUDIT[{}]: tool='{}' ", phase, tool_name);

        if let Some(ref security) = extensions.security {
            let labels: Vec<&String> = security.labels.iter().collect();
            print!("labels={:?} ", labels);
        }

        if let Some(ref http) = extensions.http {
            if let Some(req_id) = http.get_header("X-Request-ID") {
                print!("request_id='{}' ", req_id);
            }
        }

        if is_result {
            let is_error = payload
                .message
                .get_tool_results()
                .first()
                .map(|tr| tr.is_error)
                .unwrap_or(false);
            print!("error={} ", is_error);
        }

        println!();
        PluginResult::allow()
    }
}

// ---------------------------------------------------------------------------
// Factories
// ---------------------------------------------------------------------------

struct IdentityCheckerFactory;
impl PluginFactory for IdentityCheckerFactory {
    fn create(&self, config: &PluginConfig) -> Result<PluginInstance, Box<PluginError>> {
        let plugin = Arc::new(IdentityChecker {
            cfg: config.clone(),
        });
        Ok(PluginInstance {
            plugin: plugin.clone(),
            handlers: vec![
                (
                    "cmf.tool_pre_invoke",
                    Arc::new(TypedHandlerAdapter::<CmfHook, _>::new(plugin.clone())),
                ),
                (
                    "cmf.tool_post_invoke",
                    Arc::new(TypedHandlerAdapter::<CmfHook, _>::new(plugin)),
                ),
            ],
        })
    }
}

struct HeaderInjectorFactory;
impl PluginFactory for HeaderInjectorFactory {
    fn create(&self, config: &PluginConfig) -> Result<PluginInstance, Box<PluginError>> {
        let plugin = Arc::new(HeaderInjector {
            cfg: config.clone(),
        });
        Ok(PluginInstance {
            plugin: plugin.clone(),
            handlers: vec![(
                "cmf.tool_pre_invoke",
                Arc::new(TypedHandlerAdapter::<CmfHook, _>::new(plugin)),
            )],
        })
    }
}

struct AuditLoggerFactory;
impl PluginFactory for AuditLoggerFactory {
    fn create(&self, config: &PluginConfig) -> Result<PluginInstance, Box<PluginError>> {
        let plugin = Arc::new(AuditLogger {
            cfg: config.clone(),
        });
        Ok(PluginInstance {
            plugin: plugin.clone(),
            handlers: vec![
                (
                    "cmf.tool_pre_invoke",
                    Arc::new(TypedHandlerAdapter::<CmfHook, _>::new(plugin.clone())),
                ),
                (
                    "cmf.tool_post_invoke",
                    Arc::new(TypedHandlerAdapter::<CmfHook, _>::new(plugin)),
                ),
            ],
        })
    }
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

#[tokio::main]
async fn main() {
    println!("=== CMF Capabilities Demo ===\n");

    // Load config from YAML file — capabilities declared per plugin
    let config_path = "crates/cpex-core/examples/cmf_capabilities_demo.yaml";
    println!("--- Loading config from {} ---\n", config_path);
    let yaml = std::fs::read_to_string(config_path)
        .unwrap_or_else(|e| panic!("Failed to read {}: {}", config_path, e));
    let cpex_config = cpex_core::config::parse_config(&yaml).unwrap();

    let mgr = PluginManager::default();
    mgr.register_factory("builtin/identity-checker", Box::new(IdentityCheckerFactory));
    mgr.register_factory("builtin/header-injector", Box::new(HeaderInjectorFactory));
    mgr.register_factory("builtin/audit-logger", Box::new(AuditLoggerFactory));
    mgr.load_config(cpex_config).unwrap();
    mgr.initialize().await.unwrap();

    // --- Build CMF Message ---
    let payload = MessagePayload {
        message: Message {
            schema_version: cpex_core::cmf::constants::SCHEMA_VERSION.into(),
            role: Role::Assistant,
            content: vec![
                ContentPart::Text {
                    text: "Looking up compensation.".into(),
                },
                ContentPart::ToolCall {
                    content: ToolCall {
                        tool_call_id: "tc_001".into(),
                        name: "get_compensation".into(),
                        arguments: [("employee_id".to_string(), serde_json::json!(42))].into(),
                        namespace: None,
                    },
                },
            ],
            channel: None,
        },
    };

    // --- Build Extensions with security, HTTP, meta ---
    let mut security = SecurityExtension::default();
    security.add_label("PII");
    security.add_label("HR_DATA");
    security.classification = Some("confidential".into());
    security.subject = Some(cpex_core::extensions::security::SubjectExtension {
        id: Some("alice".into()),
        subject_type: Some(cpex_core::extensions::security::SubjectType::User),
        roles: ["hr_admin".to_string()].into(),
        permissions: ["read_compensation".to_string()].into(),
        ..Default::default()
    });

    let mut http = HttpExtension::default();
    http.set_header("Authorization", "Bearer eyJ...");
    http.set_header("X-Request-ID", "req-abc-123");

    let ext = Extensions {
        request: Some(Arc::new(RequestExtension {
            environment: Some("production".into()),
            request_id: Some("req-abc-123".into()),
            ..Default::default()
        })),
        security: Some(Arc::new(security)),
        http: Some(Arc::new(http)),
        meta: Some(Arc::new(MetaExtension {
            entity_type: Some("tool".into()),
            entity_name: Some("get_compensation".into()),
            tags: ["pii".to_string(), "hr".to_string()].into(),
            ..Default::default()
        })),
        ..Default::default()
    };

    // --- Pre-invoke: type-safe dispatch via invoke_named ---
    println!("=== Phase 1: cmf.tool_pre_invoke ===\n");

    // invoke_named<CmfHook> gives compile-time payload type checking
    // while routing to the specific "cmf.tool_pre_invoke" hook name
    let (pre_result, bg) = mgr
        .invoke_named::<CmfHook>(
            "cmf.tool_pre_invoke",
            payload,
            ext,
            None, // first hook — no context table
        )
        .await;

    println!();
    if pre_result.continue_processing {
        println!("Pre-invoke result: ALLOWED");
        if let Some(ref modified_ext) = pre_result.modified_extensions {
            if let Some(ref sec) = modified_ext.security {
                let labels: Vec<&String> = sec.labels.iter().collect();
                println!("  Labels after pre-invoke: {:?}", labels);
            }
            if let Some(ref http) = modified_ext.http {
                println!("  Headers after pre-invoke: {:?}", http.request_headers);
            }
        }
    } else {
        println!(
            "Pre-invoke result: DENIED — {}",
            pre_result.violation.as_ref().unwrap().reason
        );
        bg.wait_for_background_tasks().await;
        println!("\n=== Demo complete ===");
        return;
    }
    bg.wait_for_background_tasks().await;

    // --- Simulate tool execution ---
    println!("\n--- Tool 'get_compensation' executes... ---");
    println!("  Result: {{\"salary\": 150000, \"currency\": \"USD\"}}\n");

    // --- Post-invoke: different CMF message with tool result ---
    println!("=== Phase 2: cmf.tool_post_invoke ===\n");

    let post_payload = MessagePayload {
        message: Message {
            schema_version: cpex_core::cmf::constants::SCHEMA_VERSION.into(),
            role: Role::Tool,
            content: vec![ContentPart::ToolResult {
                content: cpex_core::cmf::ToolResult {
                    tool_call_id: "tc_001".into(),
                    tool_name: "get_compensation".into(),
                    content: serde_json::json!({"salary": 150000, "currency": "USD"}),
                    is_error: false,
                },
            }],
            channel: None,
        },
    };

    // Build post-invoke extensions — carry forward any modifications
    // from pre-invoke via the context table
    let post_ext = pre_result.modified_extensions.unwrap_or_else(|| {
        // Rebuild if no modifications
        let mut security = SecurityExtension::default();
        security.add_label("PII");
        Extensions {
            security: Some(Arc::new(security)),
            meta: Some(Arc::new(MetaExtension {
                entity_type: Some("tool".into()),
                entity_name: Some("get_compensation".into()),
                ..Default::default()
            })),
            ..Default::default()
        }
    });

    // Thread the context table from pre-invoke to preserve plugin state
    let (post_result, post_bg) = mgr
        .invoke_named::<CmfHook>(
            "cmf.tool_post_invoke",
            post_payload,
            post_ext,
            Some(pre_result.context_table),
        )
        .await;

    println!();
    if post_result.continue_processing {
        println!("Post-invoke result: ALLOWED");
    } else {
        println!(
            "Post-invoke result: DENIED — {}",
            post_result.violation.as_ref().unwrap().reason
        );
    }

    post_bg.wait_for_background_tasks().await;
    println!("\n=== Demo complete ===");
}

pub fn has_label(&self, label: &str) -> bool

Check if a label exists (case-insensitive).

Examples found in repository

examples/cmf_capabilities_demo.rs (line 100)

    async fn handle(
        &self,
        payload: &MessagePayload,
        extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<MessagePayload> {
        // Determine if this is pre or post invoke based on message content
        let is_result = payload.message.is_tool_result();

        if is_result {
            // POST-INVOKE: verify the tool result came from an authorized call
            let tool_name = payload
                .message
                .get_tool_results()
                .first()
                .map(|tr| tr.tool_name.as_str())
                .unwrap_or("unknown");
            println!(
                "  [identity-checker] POST-INVOKE: verifying result from '{}'",
                tool_name
            );

            if let Some(ref security) = extensions.security {
                if let Some(ref subject) = security.subject {
                    println!(
                        "  [identity-checker] Result authorized for subject: {:?}",
                        subject.id
                    );
                }
            }
            println!("  [identity-checker] POST-INVOKE ALLOWED");
        } else {
            // PRE-INVOKE: check caller identity and roles
            let tool_name = payload
                .message
                .get_tool_calls()
                .first()
                .map(|tc| tc.name.as_str())
                .unwrap_or("unknown");
            println!(
                "  [identity-checker] PRE-INVOKE: checking identity for '{}'",
                tool_name
            );

            if let Some(ref security) = extensions.security {
                let labels: Vec<&String> = security.labels.iter().collect();
                println!("  [identity-checker] Security labels: {:?}", labels);

                if let Some(ref subject) = security.subject {
                    println!(
                        "  [identity-checker] Subject: {:?}, Roles: {:?}",
                        subject.id,
                        subject.roles.iter().collect::<Vec<_>>()
                    );

                    if security.has_label("PII") && !subject.roles.contains("hr_admin") {
                        return PluginResult::deny(PluginViolation::new(
                            "insufficient_role",
                            format!("Tool '{}' requires 'hr_admin' role for PII data", tool_name),
                        ));
                    }
                }
            }

            if extensions.http.is_some() {
                println!("  [identity-checker] WARNING: HTTP visible (unexpected!)");
            } else {
                println!("  [identity-checker] HTTP: not visible (correct — no read_headers)");
            }
            println!("  [identity-checker] PRE-INVOKE ALLOWED");
        }

        PluginResult::allow()
    }

Trait Implementations

impl Clone for SecurityExtension

fn clone(&self) -> SecurityExtension

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SecurityExtension

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SecurityExtension

fn default() -> SecurityExtension

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SecurityExtension

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SecurityExtension

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.