pub struct Claims {Show 27 fields
pub iss: String,
pub sub: String,
pub tenant: Option<String>,
pub exp: i64,
pub iat: i64,
pub jti: Option<String>,
pub sid: Option<String>,
pub hs_session_authority_generation: Option<String>,
pub hs_profile: Option<String>,
pub hs_signer_suite_v1: Option<String>,
pub hs_signer_pq_key_v1: Option<String>,
pub hs_signer_inventory_v1: Option<String>,
pub hs_source_issuer_v1: Option<String>,
pub hs_source_subject_v1: Option<String>,
pub hs_tui_profile: Option<String>,
pub hs_tui_signer_pq_key_v1: Option<String>,
pub hs_tui_source_issuer_v1: Option<String>,
pub hs_tui_source_subject_v1: Option<String>,
pub workload_session_id: Option<String>,
pub aud: Option<String>,
pub client_id: Option<String>,
pub scope: Option<String>,
pub cnf: Option<Cnf>,
pub token: Option<String>,
pub clearance: Option<CredentialClearance>,
pub act: Option<ActClaim>,
pub cap: Option<String>,
}Expand description
JWT claims for authentication.
Casbin remains the server-side policy authority. OAuth access tokens also carry the grant’s scope ceiling so a verifier can enforce the intersection of subject policy and the authority delegated by that specific grant.
Fields§
§iss: StringIssuer URL — the hyprstream node that minted this token. Matches the OAuth issuer URL (e.g. “https://cloud-a.example.com”). Required for federation: receiving nodes use this to fetch JWKS. Defaults to empty string for backward compat (treated as local-only).
sub: String§tenant: Option<String>Verified tenant/Casbin domain assigned by the token authority.
This value is consumed only after JWT signature verification. Missing, empty, or wildcard tenants cannot be used as authorization domains.
exp: i64§iat: i64§jti: Option<String>RFC 7519 JWT ID — unique token identifier for revocation.
sid: Option<String>Registered OIDC session ID (sid) — groups an interactive session
whose access-token rotations share one revocable session. Absent on
standalone service credentials (no session lifecycle).
Signed generation for profiles that use server-side session authority.
Stateless Federate proof credentials use hs_signer_inventory_v1
instead. This is JWT-only; envelope claims cannot assert this state.
hs_profile: Option<String>Exact opt-in Federate PoP/COSE subprofile. This is not authority on its own; the reserved host path must verify the signed issuer and holder.
hs_signer_suite_v1: Option<String>Federate-only top-level commitment to the ordered hybrid signer suite.
Unlike generic v16 cnf.hs_signer_suite, this is not a second RFC 7800
confirmation method: cnf.jwk remains the sole confirmation key.
hs_signer_pq_key_v1: Option<String>The public ML-DSA-65 half of the COSE proof key pair. It is safe to carry in the issuer-signed credential and lets a verifier validate the holder proof without resolving a session row just to recover a key.
hs_signer_inventory_v1: Option<String>Digest of the issuer’s trusted signer inventory at login. This expires stale proof credentials after an inventory change without a session DB.
hs_source_issuer_v1: Option<String>Signed login provenance. sub remains the canonical ATProto DID;
these claims retain the upstream OIDC identity used to establish it.
hs_source_subject_v1: Option<String>§hs_tui_profile: Option<String>TUI-consumer Federate profile (W1.3), deliberately namespaced
hs_tui_* and DISTINCT from every www federate-session-v1
suite/inventory marker above. A credential of the TUI client class
must NOT enter the deferred federate-session dispatch branch, so
none of these claims may ever appear in
Claims::has_federate_profile_marker: the TUI credential
authenticates through normal JWT verification with cnf.jwk holder
binding instead. The exact profile string pins the class.
hs_tui_signer_pq_key_v1: Option<String>The public ML-DSA-65 half of the TUI holder’s COSE proof key pair
(TUI-namespaced analogue of hs_signer_pq_key_v1).
hs_tui_source_issuer_v1: Option<String>Signed login provenance for the TUI class (TUI-namespaced analogue
of hs_source_issuer_v1/hs_source_subject_v1).
hs_tui_source_subject_v1: Option<String>§workload_session_id: Option<String>Workload credential family session ID (workload_session_id) — a
distinct namespace from OIDC sid (v16 §3.3). Present only on
credentials of an enrolled workload family (e.g. a service-JWT
renewal chain); a standalone service credential omits it.
aud: Option<String>RFC 8707 audience claim for resource indicator binding.
client_id: Option<String>RFC 9068 §2.2.1 client_id — the OAuth client the access token was
issued to. REQUIRED (non-empty) on locally issued at+jwt credentials
(v16 credential profile; JWT-only, no CWT mapping). Distinct from aud
(the RFC 8707 resource indicator) and from sub (the resource owner).
Absent on non-at+jwt credentials (e.g. wit+jwt service tokens) and
on the in-process empty-issuer provenance path.
scope: Option<String>OAuth 2.0 granted scope set, serialized as a space-delimited string.
This is optional because non-OAuth service tokens do not originate from
an OAuth grant. Consumers that derive authority from OAuth scopes MUST
use Self::has_scope and fail closed when this claim is absent.
cnf: Option<Cnf>RFC 8705 / WIMSE proof-of-possession confirmation claim.
Binds the Ed25519 signing key to the JWT-attested identity via a standard
JWK object (cnf.jwk). For service tokens (WIT), derived by the CA from
the root key. For user tokens, set during OAuth flow from the verified
Ed25519 challenge-response.
token: Option<String>Original JWT token for end-to-end verification. When present, downstream services MUST verify this token independently rather than trusting the envelope claims alone.
SECURITY:
#[serde(skip)]prevents recursive JWT-in-JWT embedding and JSON exposure.- This field is ONLY populated via Cap’n Proto (
ToCapnp/FromCapnp). - Custom Debug impl redacts this field as
[REDACTED]. - Do NOT change to
skip_serializing_if— that would leak the token in JSON.
clearance: Option<CredentialClearance>MAC clearance (S8/#574, design §3, §11). The authority-asserted
clearance the issuing node grants this subject: a SecurityLabel
carrying level + compartments. This is the authority-asserted
half of the S1 subject context; the issuing node signs the JWT, so the
clearance cannot be self-asserted by the subject.
Assurance is NOT carried here. Per the S1/#548 contract, the
assurance axis of a subject’s context is derived from the verified key
material, never trusted from a claim. The MAC PDP clamps the
clearance’s assurance DOWN to what the verified crypto supports (see
crate::auth::mac::SecurityContext::from_clearance). So an Ed25519-only
identity carrying a PqHybrid clearance floors to Classical at
enforcement time — the claim cannot grant assurance the key does not back.
None ⇒ unlabeled subject ⇒ the MAC monitor denies (no default
clearance; the S1 fail-closed rule). Carried on the hybrid-signed
envelope/JWT so it is itself PQ-forgery-resistant.
act: Option<ActClaim>Delegation actor (RFC 8693 §4.1 act, #680/#681). Present iff this is
a delegated (on-behalf-of) token: Self::sub is the delegator (source of
authority), act the actor that signs the downstream envelope. Drives the
two-principal MAC derivation (#681): clearance = meet(sub, act), assurance
from the verified signer (the actor). See ActClaim. JWT-carried only
(mirrors Self::clearance); reconstructed None on the Cap’n Proto path.
cap: Option<String>Attenuated capability subset (ZSP, Fu1/#677, TODO(#572-scope-claim)).
The least-authority capability the minted token actually encodes, in
ability@resource form. ZSP mints the subset that covers the request,
never the whole grant — this claim puts that subset on the wire so the
downstream PEP (S2) enforces the minted authority (and a refresh can only
re-grant this subset, never widen). Distinct from Casbin scopes (which are
NOT in JWTs): this is the MAC/UCAN capability the S6 exchange authorized.
None ⇒ not a grant-minted token (ordinary auth token). JWT-carried only
(mirrors Self::clearance/Self::act); reconstructed None on the
Cap’n Proto path.
Implementations§
Source§impl Claims
impl Claims
Sourcepub fn with_actor(self, actor: Option<ActClaim>) -> Self
pub fn with_actor(self, actor: Option<ActClaim>) -> Self
Attach a delegation actor (RFC 8693 act).
Sourcepub fn terminal_actor(&self) -> Option<&str>
pub fn terminal_actor(&self) -> Option<&str>
The terminal (deepest) actor subject in the delegation chain, if any.
Set a session-authority generation in its one canonical encoding. This does not make a token eligible for dispatch; profile, proof, replay and Policy checks remain mandatory.
Parse the signed generation without accepting padding, alternate alphabets, truncation, or a wire-provided state locator.
Sourcepub fn with_federate_signer_inventory(self, inventory: [u8; 32]) -> Self
pub fn with_federate_signer_inventory(self, inventory: [u8; 32]) -> Self
Set the trusted signer-inventory digest for the stateless Federate proof profile. This binds a short-lived credential to the host’s current verifier inventory without naming a database or session row.
Sourcepub fn federate_signer_inventory(&self) -> Result<Option<[u8; 32]>>
pub fn federate_signer_inventory(&self) -> Result<Option<[u8; 32]>>
Parse the signed Federate signer-inventory digest in its sole canonical base64url encoding. Callers decide whether the all-zero value is valid for their configured inventory.
Sourcepub fn is_reserved_federate_staging_credential(&self) -> bool
pub fn is_reserved_federate_staging_credential(&self) -> bool
Recognize the fixed host/client even when one profile marker was removed by a faulty issuer or token transformation.
pub fn is_reserved_federate_credential(&self, configured_host: &str) -> bool
Sourcepub fn has_federate_profile_marker(&self) -> bool
pub fn has_federate_profile_marker(&self) -> bool
Any signed Federate-only marker takes the deferred, fail-closed path; stripping one marker cannot reinterpret the remaining token as generic.
The TUI-consumer markers (hs_tui_*, W1.3) are deliberately NOT in
this set: a TUI-class credential authenticates through normal JWT
verification (with cnf.jwk holder binding), never through the
deferred federate-session dispatch branch. A TUI credential carrying
any www marker below still trips this check and is rejected in that
branch (it is not the reserved staging class); a www credential
carrying any TUI marker is rejected by the www proof consumer.
Sourcepub fn has_federate_tui_profile_marker(&self) -> bool
pub fn has_federate_tui_profile_marker(&self) -> bool
Any signed TUI-consumer marker. Used by the TUI profile consumer to reject www-class credentials that smuggle TUI markers (mixed-marker defense) and to require the complete TUI marker set.
Sourcepub fn has_complete_federate_tui_profile(&self) -> bool
pub fn has_complete_federate_tui_profile(&self) -> bool
The COMPLETE TUI-consumer marker set. The mint stamps all four unconditionally, so a classified credential with any marker missing is never legitimate.
Sourcepub fn is_federate_tui_class(&self, local_issuers: &[&str]) -> bool
pub fn is_federate_tui_class(&self, local_issuers: &[&str]) -> bool
Whether this credential is of the Federate TUI client class (W1.3): it carries any TUI marker, OR it names the deployment-configured TUI client id at a local issuer — the authority-owned, marker-independent class pin, mirroring the www reserved (iss, client_id) predicate so a class-shaped credential with every marker stripped still cannot fall through to generic handling.
Sourcepub fn with_federate_tui_markers(
self,
pq_key_b64url: String,
source_issuer: String,
source_subject: String,
) -> Self
pub fn with_federate_tui_markers( self, pq_key_b64url: String, source_issuer: String, source_subject: String, ) -> Self
Stamp the TUI-consumer Federate profile marker set. Every claim is
TUI-namespaced and disjoint from the www federate-session-v1
suite/inventory markers, so the credential never enters the deferred
federate dispatch branch; the marker alone is never authority.
Sourcepub fn with_federate_signer_suite(self, thumbprint_b64url: String) -> Self
pub fn with_federate_signer_suite(self, thumbprint_b64url: String) -> Self
Stamp the exact Federate profile and its ordered hybrid-suite digest. This marker alone is never authority; the reserved path also verifies the signed source binding, holder proof, replay admission and live Policy.
Sourcepub fn with_workload_session_id(self, id: impl Into<String>) -> Self
pub fn with_workload_session_id(self, id: impl Into<String>) -> Self
Set the workload credential family session ID
(workload_session_id claim) — enrolled workload families only.
Sourcepub fn session_key(&self) -> Result<Option<SessionKey>, SessionClaimError>
pub fn session_key(&self) -> Result<Option<SessionKey>, SessionClaimError>
The credential’s session binding under exact-one parsing (v16 §3.3):
a credential carries AT MOST ONE session identifier, in a disjoint
namespace — OIDC sid (interactive) or workload_session_id
(enrolled workload family). Both-present is ambiguous and rejects;
a present-but-empty identifier is malformed and rejects. Neither is
Ok(None) (standalone credential, no session).
Every authorization and cache-insertion path MUST use this parser —
never an sid.or_else(workload_session_id) chain, which would let an
active OIDC session mask a revoked or unknown workload session.
Sourcepub fn with_issuer(self, issuer: String) -> Self
pub fn with_issuer(self, issuer: String) -> Self
Set the issuer URL (RFC 7519 iss claim).
Should be the OAuth issuer URL of the hyprstream node that issued this token.
Sourcepub fn with_tenant(self, tenant: String) -> Self
pub fn with_tenant(self, tenant: String) -> Self
Set the authority-asserted tenant used as the Casbin request domain.
Sourcepub fn with_audience(self, audience: Option<String>) -> Self
pub fn with_audience(self, audience: Option<String>) -> Self
Create new claims with an audience (RFC 8707 resource indicator).
Sourcepub fn with_client_id(self, client_id: impl Into<String>) -> Self
pub fn with_client_id(self, client_id: impl Into<String>) -> Self
Set the RFC 9068 §2.2.1 client_id claim (the OAuth client the access
token was issued to). An empty/whitespace value is treated as absent so
a caller cannot satisfy the profile’s non-empty requirement with a blank.
Sourcepub fn with_scope(self, scope: Option<String>) -> Self
pub fn with_scope(self, scope: Option<String>) -> Self
Set the OAuth 2.0 granted scope claim.
Sourcepub fn granted_scopes(&self) -> impl Iterator<Item = &str>
pub fn granted_scopes(&self) -> impl Iterator<Item = &str>
Iterate over the exact scopes granted to this token.
An absent claim yields an empty iterator, keeping scope-based consumers fail closed for legacy and non-OAuth tokens.
Sourcepub fn has_scope(&self, required: &str) -> bool
pub fn has_scope(&self, required: &str) -> bool
Return whether this token’s signed grant contains required exactly.
Sourcepub fn with_token(self, token: String) -> Self
pub fn with_token(self, token: String) -> Self
Attach original JWT token for e2e verification by downstream services.
Sourcepub fn with_cnf_jwk(self, key_bytes: &[u8; 32]) -> Self
pub fn with_cnf_jwk(self, key_bytes: &[u8; 32]) -> Self
Set the RFC 8705 cnf.jwk confirmation claim (WIMSE WIT key binding).
key_bytes is the raw 32-byte Ed25519 public key. Produces a standard
OKP JWK object with kty: "OKP", crv: "Ed25519", x: <base64url>.
Sourcepub fn with_cnf_hs_signer_suite(self, thumbprint_b64url: String) -> Self
pub fn with_cnf_hs_signer_suite(self, thumbprint_b64url: String) -> Self
Set the v16 cnf.hs_signer_suite confirmation (frozen WS-A profile
§1.1/§5): the base64url signer-suite content thumbprint. Merged into any
existing cnf so a legacy jwk/jkt binding is preserved alongside it.
Compute thumbprint_b64url from crate::auth::signer_suite_thumbprint.
Sourcepub fn with_cnf_jkt(self, key_bytes: &[u8; 32]) -> Self
pub fn with_cnf_jkt(self, key_bytes: &[u8; 32]) -> Self
Set the RFC 9449 cnf.jkt confirmation claim (DPoP JWK thumbprint).
key_bytes is the raw 32-byte Ed25519 public key. The thumbprint is
computed per RFC 7638: SHA-256 of the lexicographic canonical JWK JSON,
base64url-encoded.
Sourcepub fn with_cnf_jkt_thumbprint(self, jkt: String) -> Self
pub fn with_cnf_jkt_thumbprint(self, jkt: String) -> Self
Set the RFC 9449 cnf.jkt from a PRE-COMPUTED thumbprint string (e.g. a
verified DPoP proof’s jkt). Merged into any existing cnf.
Sourcepub fn with_clearance(self, clearance: SecurityLabel) -> Self
pub fn with_clearance(self, clearance: SecurityLabel) -> Self
Set the MAC clearance claim (S8/#574). The authority-asserted clearance the issuing node grants this subject (level + compartments). The resulting JWT carries this under its (hybrid) signature, so it is itself PQ-forgery-resistant; the assurance axis is NOT carried here — it is derived from the verified key material at enforcement time.
Sourcepub fn with_credential_clearance(self, clearance: CredentialClearance) -> Self
pub fn with_credential_clearance(self, clearance: CredentialClearance) -> Self
Set the MAC clearance claim from its two-axis wire projection directly.
Used when FORWARDING an already-projected clearance (e.g. re-stamping a
verified source credential’s clearance onto a derived ticket) — the
value is copied through unchanged. Prefer Self::with_clearance when
starting from a full SecurityLabel.
Sourcepub fn with_cap(self, cap: String) -> Self
pub fn with_cap(self, cap: String) -> Self
Set the attenuated capability subset (cap, ZSP Fu1/#677) the minted
token encodes, in ability@resource form. See Self::cap.
Sourcepub fn cnf_key_bytes(&self) -> Option<[u8; 32]>
pub fn cnf_key_bytes(&self) -> Option<[u8; 32]>
Extract the raw 32-byte Ed25519 public key from cnf.jwk.x, if present.
Sourcepub fn verify_token(
&self,
verifying_key: &VerifyingKey,
expected_aud: Option<&str>,
) -> Result<Option<Claims>, JwtError>
pub fn verify_token( &self, verifying_key: &VerifyingKey, expected_aud: Option<&str>, ) -> Result<Option<Claims>, JwtError>
Independently verify the embedded JWT token.
Returns the verified claims if the token is present and valid. Returns None if no token is embedded. Returns Err if token is present but verification fails (MUST reject request).
Note: jwt::decode() validates both signature and exp (via is_expired()).
Sourcepub fn is_expired(&self) -> bool
pub fn is_expired(&self) -> bool
Check if token is expired (with 5-second leeway for clock skew).
Sourcepub fn is_local_to(&self, local_issuers: &[&str]) -> bool
pub fn is_local_to(&self, local_issuers: &[&str]) -> bool
True if this token was issued by a local node.
Delegates to is_local_iss using this token’s iss field.
Sourcepub fn strip_federated_clearance(&mut self, local_issuers: &[&str])
pub fn strip_federated_clearance(&mut self, local_issuers: &[&str])
Strip the authority-asserted MAC clearance when this token’s issuer is
NOT a local issuer (Fu5/#677).
clearance is authority-asserted: the issuing node signs the JWT, so a
local issuer (this node, or a configured local cluster issuer) is trusted
to grant MAC clearance. An external OIDC issuer trusted for identity
is NOT thereby trusted to assert MAC clearance on this node — honoring it
would let any trusted-for-identity federated IdP mint MAC clearance.
Federated-path decode therefore drops the claim before the MAC PDP can
read it (crate::auth::mac::SubjectContextClaims::credential_clearance
returns None ⇒ unlabeled ⇒ deny). Local-issuer tokens are unaffected.
Sourcepub fn strip_federated_tenant(&mut self, local_issuers: &[&str])
pub fn strip_federated_tenant(&mut self, local_issuers: &[&str])
Strip the authority-asserted tenant when this token’s issuer is not local.
A federated issuer trusted for identity is not trusted to select a local Casbin tenant domain. Clearing the claim makes downstream domain resolution fail closed, while preserving tenant bindings minted by local issuers.
Sourcepub fn subject(&self, local_issuers: &[&str]) -> Subject
pub fn subject(&self, local_issuers: &[&str]) -> Subject
Derive the Casbin authorization subject from these claims.
Local tokens (issued by this node) produce bare subjects ("alice")
matching existing Casbin rules. Federated tokens produce namespaced
subjects ("https://other.node:alice") to prevent cross-node spoofing.
UNAUTHENTICATED_DID_SENTINEL is credential absence, not a principal.
Even a verified token carrying it therefore resolves to the
unauthenticated floor and can never authenticate as the sentinel.
Trait Implementations§
Source§impl<'de> Deserialize<'de> for Claims
impl<'de> Deserialize<'de> for Claims
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Source§impl SubjectContextClaims for Claims
impl SubjectContextClaims for Claims
Source§fn credential_clearance(&self) -> Option<CredentialClearance>
fn credential_clearance(&self) -> Option<CredentialClearance>
None ⇒
unlabeled subject ⇒ the monitor MUST deny (no default clearance).Source§fn security_context(
&self,
key_material: VerifiedKeyMaterial,
) -> Option<SecurityContext>
fn security_context( &self, key_material: VerifiedKeyMaterial, ) -> Option<SecurityContext>
None (→ deny) if the subject carries no
clearance. Implementors normally only need to provide
credential_clearance.Auto Trait Implementations§
impl Freeze for Claims
impl RefUnwindSafe for Claims
impl Send for Claims
impl Sync for Claims
impl Unpin for Claims
impl UnsafeUnpin for Claims
impl UnwindSafe for Claims
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more