Module principal 

The RFC 7141 identity contract: what an auth provider outputs (AuthenticatedIdentity) and what the shared resolver turns it into (the canonical Principal).

Three stages, three vocabularies (Rev 8):

1. A provider verifies ONE credential and emits an AuthenticatedIdentity — provenance, subject, actor kind, verified claims, expiry/revalidation metadata. Providers never emit grants.
2. The shared resolver (in zeroclaw-runtime) maps that identity to a canonical PrincipalId and the currently-configured permission profiles. Claims are mapping inputs, never runtime grants.
3. Dispatch/gateway/storage surfaces consume the resolved Principal plus its separately-resolved crate::grants::ResolvedGrants. Grants are NOT stored on the Principal: they are re-resolved from current policy at the authorization-generation boundary, so a profile or mapping change affects established connections without reconnect.

Structs

AgentAlias

An agent alias a principal may bind at session start. Newtype so it never gets confused with an arbitrary String in grant checks.

AuthenticatedIdentity

What an auth provider outputs after verifying ONE credential: identity and evidence, never grants. Handshake-scoped and server-side only — this type is deliberately not serializable, and its Debug never prints claim values (claims may carry personal data).

Principal

The canonical resolved principal: the single non-secret record every dispatch/audit/isolation surface consumes.

PrincipalId

Canonical, globally-unambiguous principal identifier. The durable ownership key for sessions, private memory, approvals, and audit attribution.

Enums

ActorKind

What kind of actor an identity represents. Human and service identities stay distinct end-to-end: a service principal never inherits interactive browser sessions or private user memory because claims have similar names.

AuthMethod

AuthOutcome

The single result every credential verification returns. Misroute, timeout, or malformed input ⇒ AuthOutcome::Denied, NEVER a silent allow. Once a provider was selected for a credential, its denial is authoritative: there is no fallback to another provider or to broader authority.

DenyReason

Why a credential was rejected. Fail-closed: any ambiguity ⇒ a Denied variant, never a silent allow.

IdentitySubject

The verified subject of an AuthenticatedIdentity. Each variant carries exactly the fields its canonical PrincipalId is composed from, so a provider cannot construct an ambiguous or cross-class identity.