Crate plexus_auth_core 

Sealed-type primitives for the Plexus auth framework.

This crate exists to host the Plexus authentication primitives — AuthContext, VerifiedUser, Principal, and the forthcoming Credential<T>, Tenanted<S>, ForwardDerivation — behind a crate boundary that no consuming crate can bypass. The crate boundary, plus Rust’s orphan rules, plus crate-private constructors, escalate the sealed-type defense from procedural (visibility within plexus-core) to structural (visibility across crates).

See plans/AUTHZ/AUTHZ-0.md §“Crate-level isolation amplifies the seal” for the full rationale.

Public surface

• AuthContext — the runtime auth value carried with every method invocation. The shape and current public API are preserved verbatim from plexus-core’s plexus::auth module to keep this migration mechanical; tightening the seal on AuthContext::new and field visibility is tracked as follow-up work (see plans/AUTHZ/AUTHZ-CORE-CRATE-1-RUN-NOTES.md).
• SessionValidator — the trait perimeter validators implement.
• VerifiedUser — sealed proof that an IdP-signed token was verified.
• Principal — sealed authenticated-actor identity (user, service, anon).
• BackendAuthCapabilities — capability-advertisement payload served at _info so generic clients can discover supported auth mechanisms (AUTHZ-CORE-3). Composed of AuthMechanism variants (Bearer, Cookie, Oidc, Anonymous) and the strong-typed primitives MethodPath, IssuerUrl, ClientId, CookieName, HeaderName.
• Tenant — sealed unit of data isolation (AUTHZ-0 layer 4). The constructor is crate-private; the only path to a Tenant value is through the framework’s TenantResolver.
• TenantResolver — derives a Tenant from a verified AuthContext. Reference impls: ClaimTenantResolver (the 80% case) and SingleTenantResolver (explicit single-tenant opt-out).
• Credential — sealed framework-level credential primitive. The only path to a Credential<T> value is through CredentialMinter::mint, itself reachable only by accepting a framework-injected reference. The custom Serialize impl emits a sentinel {"$credential": "<id>"} by default; the dispatch layer routes the inner value to a sidecar via an RAII guard while it builds the wire envelope (Tier B Q-WIRE-3).
• CredentialMinter — the injected service that mints credentials.
• CredentialMetadata — typed contract describing what the credential is and how to attach it on subsequent calls (kind, attach site, scheme, scopes, expiry, refresh/revoke hints, issuer, sensitivity).
• AuditRecord — the audit primitive consumed by AUTHZ default-deny dispatch (AUTHZ-CORE-5) and AUTHLANG-3’s forwarding-policy path. Carries the principal chain, decision, reason, latency, and correlation ID for one scope check. AuditSink is the framework’s persistence trait; TracingAuditSink is the default impl emitting tracing::info! events under target = "plexus::audit".

Sealing protections (per AUTHZ-0)

VerifiedUser and Principal are introduced here with the strict seal the AUTHZ-0 doc calls for:

1. No fabrication. Constructors are pub(crate) and callable only from inside plexus-auth-core. The trybuild test tests/compile_fail/seal_*.rs asserts this.
2. No backdoor From/Into. Orphan rules forbid implementing foreign traits for foreign types from a third crate; only this crate can add such impls.
3. No accidental Default. Explicitly NOT derived.
4. No leaky Deserialize. Not derived for these types; raw JSON cannot fabricate a sealed value.
5. No mutation. Fields are private; no setters; even with a sealed value in hand, no caller can mutate it.

AuthContext retains its current public constructors (new, anonymous) and pub fields for now, to preserve the public API that callers across the workspace depend on. The crate boundary still gives AuthContext the orphan-rule protection (no foreign From/Into from third crates) and a single audit point for the type. Tightening the AuthContext seal to match VerifiedUser/Principal is the next step in the auth track and lands as a follow-up ticket.

Re-exports

pub use audit::AuditDecision;

pub use audit::AuditDenyReason;

pub use audit::AuditRecord;

pub use audit::AuditRecordKind;

pub use audit::AuditSink;

pub use audit::ForwardPolicyApplied;

pub use audit::RoleName;

pub use audit::ScopeCheck;

pub use audit::SensitiveField;

pub use audit::SessionId;

pub use audit::TracingAuditSink;

pub use audit::UserId;

pub use auth::AuthContext;

pub use auth::SessionValidator;

pub use capabilities::AuthMechanism;

pub use capabilities::BackendAuthCapabilities;

pub use capabilities::BackendAuthCapabilitiesError;

pub use capabilities::ClientId;

pub use capabilities::ClientIdError;

pub use capabilities::CookieName;

pub use capabilities::CookieNameError;

pub use capabilities::HeaderName;

pub use capabilities::HeaderNameError;

pub use capabilities::IssuerUrl;

pub use capabilities::IssuerUrlError;

pub use capabilities::MethodPath;

pub use capabilities::MethodPathError;

pub use credential::CredentialsRegistry;Deprecated

pub use credential::AttachmentSite;

pub use credential::CapturedCredential;

pub use credential::Credential;

pub use credential::CredentialFieldMarker;

pub use credential::CredentialId;

pub use credential::CredentialIssuer;

pub use credential::CredentialKind;

pub use credential::CredentialKindName;

pub use credential::CredentialMetadata;

pub use credential::CredentialMinter;

pub use credential::CredentialScheme;

pub use credential::CredentialsRegistryFallback;

pub use credential::DispatchSidecar;

pub use credential::HasCredentialMarkers;

pub use credential::Origin;

pub use credential::ParamName;

pub use credential::Scope;

pub use forward::Anonymous;

pub use forward::CallSite;

pub use forward::ForwardDerivation;

pub use forward::ForwardPolicy;

pub use forward::ForwardPolicyName;

pub use forward::IdentityOnly;

pub use forward::PassThrough;

pub use forward::ANONYMOUS_NAME;

pub use forward::IDENTITY_ONLY_NAME;

pub use forward::PASS_THROUGH_NAME;

pub use principal::Principal;

pub use principal::ServiceIdentity;

pub use tenant::ClaimTenantResolver;

pub use tenant::Scoped;

pub use tenant::SingleTenantResolver;

pub use tenant::Tenant;

pub use tenant::TenantBoundary;

pub use tenant::TenantError;

pub use tenant::TenantResolver;

pub use tenant::TenantScopedStore;

pub use tenant::Tenanted;

pub use verified_user::VerifiedUser;

Modules

audit

AuditRecord, AuditSink, and the default TracingAuditSink — the audit primitive per AUTHZ-PRIVACY-1.

auth

AuthContext and SessionValidator — relocated from plexus-core.

capabilities

Capability advertisement primitives — what a backend tells a client about its authentication surface, served at _info.

credential

Credential<T>, CredentialMinter, and CredentialMetadata — sealed framework-level credential primitive.

forward

Forwarding-policy primitives — CallSite, ForwardDerivation, ForwardPolicyName, the ForwardPolicy trait, and the v1 named impls (IdentityOnly, PassThrough, Anonymous).

principal

Principal — sealed authenticated-actor identity.

tenant

Tenant primitives — AUTHZ-0 layer 4 (data isolation).

verified_user

VerifiedUser — sealed proof that an IdP-signed token was verified.

Constants

VERSION

Crate version, populated at compile time from CARGO_PKG_VERSION.