Skip to main content

Crate plexus_auth_core

Crate plexus_auth_core 

Source
Expand description

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; default claim key org_id per UT-S01 D3) and SingleTenantResolver (explicit single-tenant opt-out).
  • TenantId — the public, validated identifier newtype for tenant identity (UT-1): claim values and stored resource tags. Data, not proof — see its docs for the distinction from Tenant.
  • TenantGate — the generalized tenant-isolation predicate layer extracted from plexus-trak’s reference gate (UT-1): reads scoped not-found, writes forbidden, anonymous writes unauthenticated. Backends tag resources via TenantTagged and convert GateDenial into their wire errors.
  • oidc — the OIDC validator (UT-1, UT-S01 D1): discovery → JWKS (cached per AUTH-8) → local RS256 validation of iss/aud/exp/iat → mints the sealed VerifiedUser with the org_id tenant. OidcSessionValidator adapts it to the SessionValidator perimeter.
  • 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".
  • grants (AUTH-2) — Grant (<activation>.<method>, inherent), ScopeRef, GrantSet, Membership, Ceiling, the service traits Memberships / Roles / Resolve, and the Gate whose Gate::check answers a call with a Reach or a Refusal.
  • ScopeRegistry — hub-level roles→scopes source of truth (R-0, reviving AUTHZ-CORE-4 + CORE-6). Roles are named scope-sets with transitive, build-time-cycle-rejected inheritance; Scope gains the grammar-validated try_new and segment-bounded wildcard Scope::matches; RoleName gains try_new. The dispatch gate (R-5) computes effective_scopes(AuthContext.roles) and checks Scope::matches(required).

§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 auth::PRINCIPAL_CLAIM;
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 grants::Ceiling;
pub use grants::CeilingError;
pub use grants::Gate;
pub use grants::Grant;
pub use grants::GrantSet;
pub use grants::Membership;
pub use grants::Memberships;
pub use grants::Reach;
pub use grants::Refusal;
pub use grants::Resolve;
pub use grants::RoleOrGrant;
pub use grants::RoleTable;
pub use grants::RoleTableError;
pub use grants::Roles;
pub use grants::ScopeRef;
pub use grants::ADMIN;
pub use grants::CEILING_KEY;
pub use oidc::Audience;
pub use oidc::AudienceError;
pub use oidc::FetchError;
pub use oidc::FetchedDocument;
pub use oidc::JwksFetcher;
pub use oidc::OidcConfig;
pub use oidc::OidcError;
pub use oidc::OidcSessionValidator;
pub use oidc::OidcValidator;
pub use oidc::VerifiedToken;
pub use principal::Principal;
pub use principal::ServiceIdentity;
pub use scope_registry::Role;
pub use scope_registry::RoleNameError;
pub use scope_registry::ScopeError;
pub use scope_registry::ScopeRegistry;
pub use scope_registry::ScopeRegistryBuilder;
pub use scope_registry::ScopeRegistryError;
pub use tenant::ClaimTenantResolver;
pub use tenant::GateDenial;
pub use tenant::Scoped;
pub use tenant::SingleTenantResolver;
pub use tenant::Tenant;
pub use tenant::TenantBoundary;
pub use tenant::TenantError;
pub use tenant::TenantGate;
pub use tenant::TenantId;
pub use tenant::TenantResolver;
pub use tenant::TenantRole;
pub use tenant::TenantScopedStore;
pub use tenant::TenantTagged;
pub use tenant::Tenanted;
pub use tenant::UnknownRole;
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).
grants
AUTH-2: grants, roles, memberships, ceilings, and the gate. AUTH-2: grants, roles, memberships, ceilings — and the gate that asks them on every call.
identity
Namespaced identity and pluggable authentication (PLX-82).
oidc
OIDC token validation — “the forthcoming verifier” (UT-1, UT-S01 D1).
principal
Principal — sealed authenticated-actor identity.
scope_registry
Role + ScopeRegistry + inheritance — the hub-level roles→scopes source of truth (R-0; revives AUTHZ-CORE-4 + AUTHZ-CORE-6 verbatim).
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.