Module credential 

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

Per AUTHZ-CRED-CORE-1 and AUTHZ-0 principle 6 (“the user’s safety property is unforgeable”), a credential value is unforgeable from activation code. The compiler enforces this: there is no public constructor for Credential<T> reachable from outside plexus-auth-core, no public mutator, no Default, no Deserialize. The only path to producing a Credential<T> is via CredentialMinter::mint, whose constructor is itself pub(crate) — the framework’s dispatch layer (plexus-core / plexus-transport, in a follow-up ticket) is the only caller that can obtain a minter, and activation code receives an immutable reference.

Sealing summary (per AUTHZ-0 §“Crate-level isolation amplifies the seal”)

Protection	Mechanism
No fabrication	Credential::new_sealed is pub(crate)
No backdoor From/Into	Orphan rules forbid foreign-trait impls
No accidental Default	Not derived
No leaky Deserialize	Not derived; serialize-only round-trip
No mutation	Fields private; no &mut accessors
No raw secret on wire	Custom Serialize emits a sentinel by default

Sentinel-emitting serialization (Tier B Q-WIRE-3)

Credential<T>’s Serialize impl emits, by default, a sentinel reference of the shape {"$credential": "<id>"} rather than the inner value. The framework’s dispatch layer (per AUTHZ-CRED-CORE-2) flips a thread-local toggle via an RAII guard for the duration of envelope-building; while the toggle is set, the same Serialize impl additionally captures the value into a dispatch-side sidecar (see with_dispatch_capture — crate-private, reachable only inside plexus-auth-core). When the toggle is unset (the default — any naive serde_json::to_value(&payload) from application code, audit-log writers, or trace formatters), only the sentinel is emitted; the inner value never appears in the produced JSON.

The toggle’s setter is pub(crate). Activation code has no public path to it. The guard’s Drop impl clears the toggle even on panic so a mid-serialization panic cannot leak the value.

See tests/compile_fail/credential_*.rs for the structural enforcement asserts.

Re-exports

pub use crate::capabilities::CookieName;

pub use crate::capabilities::HeaderName;

pub use crate::capabilities::MethodPath;

Structs

CapturedCredential

The shape of a credential captured into the dispatch-side sidecar.

Credential

A sealed credential value. The inner T is constructable only via a CredentialMinter — itself only obtainable as a function parameter injected by the framework into credential-issuing methods.

CredentialFieldMarker

A single registry entry describing one #[credential(...)]-annotated field on a credential-bearing type. The #[derive(plexus_macros::Credentials)] macro emits a per-type free function __plexus_credential_marker_for_<TypeIdent>() -> Vec<CredentialFieldMarker> returning these entries in stable declaration order.

CredentialId

Per-response credential identifier (the <id> in the {"$credential": "<id>"} sentinel). Generated by the framework’s dispatch layer at envelope-build time; opaque to activations.

CredentialIssuer

Identity of the issuing party: the Origin the credential was issued from and the method that issued it. Drives the named-session auto-naming algorithm (AUTHZ-CRED-S01-output §5) and ties the credential to its lineage in audit.

CredentialKindName

Opaque kind name for CredentialKind::Other. The framework’s compatibility logic treats Other-kinded credentials as untagged for the purposes of requires_credential matching (per Tier B Q-FLOW-2).

CredentialMetadata

What this credential is and how to attach it on subsequent calls.

CredentialMinter

The framework-issued service that mints sealed Credential<T> values.

CredentialScheme

Credential attach-time prefix, e.g. "Bearer " (trailing space included). Pinned by AUTHZ-CRED-S01-output §2.

DispatchCaptureGuard

RAII guard that activates dispatch-side capture for the lifetime of the guard. The constructor is pub(crate): activation code cannot create one. The dispatch layer (plexus-core / plexus-transport, via a pub(crate)-exposed helper in this crate) is the only caller.

DispatchSidecar

Sidecar collector populated by the credential Serialize impl while a DispatchCaptureGuard is active. The dispatch layer reads the collected map after serialization completes and emits it as the _credentials envelope key (AUTHZ-CRED-S01-output §3, Q-WIRE-1).

Origin

Backend Origin identifier (typically a URL like ws://localhost:4444). Local stub for the canonical Origin newtype pinned by CLIENTS-S01-output §1. NOTE: the workspace also has an unrelated plexus_core::types::Origin (plugin-id + method, not URL-shaped); the AUTHZ-CRED design uses the URL-shaped Origin from CLIENTS-S01.

ParamName

Parameter name for in-RPC-parameter and first-frame attachment sites.

Scope

Atomic capability identifier, e.g. cone.send_message. Local stub for the canonical Scope newtype pinned by AUTHZ-S01-output §1.

Enums

AttachmentSite

Where the credential is attached on the wire when sent on subsequent calls. The framework’s client-side replay machinery reads this to build the outbound request.

CredentialKind

What kind of credential this is. Tags storage decisions and drives the selection filter (AUTHZ-CRED-CLI-3). Closed for v1 — third crates cannot extend the enum; backends with bespoke schemes use the CredentialKind::Other escape valve.

Traits

CredentialsRegistryDeprecated

Deprecated alias kept while consumers migrate to the new CredentialsRegistryFallback name.

CredentialsRegistryFallback

Fallback path: when T does NOT implement HasCredentialMarkers, the inherent marker_slice doesn’t apply, autoref kicks in, and the reference-typed trait impl below supplies the empty-slice default.

HasCredentialMarkers

Trait that types deriving #[derive(plexus_macros::Credentials)] opt into by providing their static credential-marker slice.

Functions

run_with_credential_capture

Public scoped-callback entry point for dispatch-time credential capture.