Enum Principal

#[non_exhaustive]
pub enum Principal {
    User {
        uid: PrincipalId,
        attrs: IndexMap<String, Value>,
    },
    Agent {
        uid: PrincipalId,
        parent_uid: Option<PrincipalId>,
        attrs: IndexMap<String, Value>,
    },
}

A principal is either a User (human) or an Agent (AI). Both become Cedar entities of type User or Agent.

Construction

Use Principal::user, Principal::agent, Principal::subagent, or Principal::with_attr — never construct the enum variants directly. The variant fields are public only because serde deserializes into them; treating them as a stable public API is unsupported. #[non_exhaustive] keeps external matches safe.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

User

A human user.

Invariant: parent_uid is meaningless here; Cedar policies should not branch on a User’s parent.

Fields

uid: PrincipalId

attrs: IndexMap<String, Value>

Agent

An AI agent, optionally with a parent (sub-agent pattern).

Fields

uid: PrincipalId

parent_uid: Option<PrincipalId>

attrs: IndexMap<String, Value>

Implementations

impl Principal

pub fn user(uid: impl Into<PrincipalId>) -> Self

Construct a User principal with the given UID.

Examples

use agentguard_core::Principal;
let p = Principal::user("alice");
assert_eq!(p.entity_uid(), "User::\"alice\"");

pub fn agent(uid: impl Into<PrincipalId>) -> Self

Construct an Agent principal with the given UID and no parent.

Examples

use agentguard_core::Principal;
let p = Principal::agent("email-bot");
assert_eq!(p.entity_type(), "Agent");

pub fn subagent( uid: impl Into<PrincipalId>, parent: impl Into<PrincipalId>, ) -> Self

Construct a sub-agent whose parent is another agent.

Examples

use agentguard_core::Principal;
let p = Principal::subagent("summarizer", "research");
assert_eq!(p.entity_uid(), "Agent::\"summarizer\"");

pub fn with_attr(self, k: impl Into<String>, v: impl Into<Value>) -> Self

Add an attribute and return self for chaining.

pub fn entity_type(&self) -> &'static str

Cedar entity type name (User or Agent).

pub fn entity_uid(&self) -> String

👎Deprecated since 0.2.1: Use the Display impl to write into an existing buffer (no allocation).

Full Cedar entity UID like User::"alice".

Prefer the Display impl for formatting into an existing buffer (avoids a String allocation on the hot path). This method is retained for callers that genuinely need an owned String (e.g. serialization to JSON via serde_json::json!).

pub fn id(&self) -> &PrincipalId

The principal’s UID without the type prefix.

Trait Implementations

impl Clone for Principal

fn clone(&self) -> Principal

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Principal

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Principal

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Principal

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

Formats the value using the given formatter.

impl PartialEq for Principal

fn eq(&self, other: &Principal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Principal

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Principal

impl StructuralPartialEq for Principal