Skip to main content

RequestEnvelope

Struct RequestEnvelope 

Source
pub struct RequestEnvelope {
Show 13 fields pub request_id: u64, pub payload: Vec<u8>, pub iat: i64, pub nonce: [u8; 16], pub authorization: Authorization, pub delegation_token: Option<String>, pub wth: Option<[u8; 32]>, pub client_dh_public: Option<[u8; 32]>, pub client_kem_public: Option<RecipientPublic>, pub response_kem_recipient: Option<RecipientPublic>, pub service_domain: Option<String>, pub proof_cwt: Option<Vec<u8>>, pub authorization_witness: Option<SensitiveBytes>,
}
Expand description

Unsigned envelope wrapping an RPC request.

This struct contains all request metadata and is signed by SignedEnvelope. The entire serialized RequestEnvelope is covered by the signature.

§Replay Protection

Legacy: nonce + iat nonce-cache replay. Superseded by v16 proof CWT cti-based replay admission (§4.5). Retained for dual-read wire compat; the proof-CWT path is fail-closed when present.

Fields§

§request_id: u64

DEPRECATED: replaced by proof CWT cti. Retained for wire compat.

§payload: Vec<u8>

Serialized inner request (e.g., RegistryRequest, InferenceRequest)

§iat: i64

Unix timestamp in milliseconds for expiration check

§nonce: [u8; 16]

DEPRECATED: replaced by proof CWT cti replay admission.

§authorization: Authorization

Authorization context

§delegation_token: Option<String>

Delegation token relayed by a trusted service (e.g., OAI, MCP adapter).

Reserved. Serialized in the envelope and covered by the signature, but not yet consumed server-side. Intended for bearer delegation flows where a gateway service forwards a user’s JWT on their behalf. Server-side extraction will be added when the delegation trust model is finalized.

§wth: Option<[u8; 32]>

DEPRECATED: replaced by proof CWT credential_hash (-70001).

§client_dh_public: Option<[u8; 32]>

Client’s ephemeral DH public key for stream key derivation. Present on streaming requests; the server uses this with its own ephemeral keypair to derive the shared secret for HMAC chain keys.

§client_kem_public: Option<RecipientPublic>

Fresh, suite-complete HyKEM recipient for identified stream setup.

This is authenticated inside the request envelope and is distinct from both the legacy classical DH field and the one-shot unary-response recipient. The server must bind it into an [IdentifiedStreamBinding] before deriving or releasing stream epoch keys.

§response_kem_recipient: Option<RecipientPublic>

Fresh per-call hybrid-KEM recipient for the unary response. This is distinct from both legacy client_dh_public and stream-plane clientKemPublic, and is carried only inside a sealed network request.

§service_domain: Option<String>

Canonical destination service. On untrusted carriers this is required, carried only in the signed+sealed request, and checked by dispatch.

§proof_cwt: Option<Vec<u8>>

v16 proof CWT (application/vnd.hyprstream.proof+cwt). When present, carries the canonical request body, credential hash, response binding, and one 128-bit request_id replacing requestId+nonce. Servers verify this in the dispatch pipeline; the legacy nonce-based replay cache is the fallback during dual-read migration.

§authorization_witness: Option<SensitiveBytes>

Read-only mediated-authorization proof, never a dispatch credential.

Implementations§

Source§

impl RequestEnvelope

Source

pub fn new(payload: Vec<u8>) -> Self

Create a new request envelope with fresh request ID, nonce, and timestamp.

Source

pub fn with_authorization(self, auth: Authorization) -> Self

Set authorization context.

Source

pub fn with_jwt_token(self, token: String) -> Self

Set opaque JWT token as IdJag authorization.

Source

pub fn with_delegation_token(self, token: String) -> Self

Set delegation token for relay by a trusted service.

Source

pub fn with_wth_of(self, jwt: &str) -> Self

Bind this proof to a specific WIT by storing SHA-256(jwt). Call this on cached-identity requests where jwtToken is omitted.

Source

pub fn with_client_dh_public(self, key: [u8; 32]) -> Self

Set the client’s ephemeral DH public key for stream key derivation.

Source

pub fn with_client_kem_public( self, recipient: RecipientPublic, ) -> EnvelopeResult<Self>

Set the identified stream’s ephemeral, pinned-suite HyKEM recipient.

Source

pub fn with_response_kem_recipient(self, recipient: RecipientPublic) -> Self

Set the one-shot HyKEM recipient for the corresponding unary response.

Source

pub fn with_service_domain( self, service_domain: impl Into<String>, ) -> Result<Self>

Bind the request to one canonical destination service.

Source

pub fn with_proof_cwt(self, proof_cwt: Vec<u8>) -> Self

Attach a v16 proof CWT to this envelope.

Source

pub fn anonymous(payload: Vec<u8>) -> Self

Create an envelope for an anonymous request.

Source

pub fn jwt_token(&self) -> Option<&str>

Extract the JWT string from authorization, if it’s an IdJag.

Source

pub fn to_bytes(&self) -> Vec<u8> ⓘ

Serialize this envelope to canonical Cap’n Proto bytes for signing.

SECURITY: This method MUST produce deterministic output for cryptographic signatures to work correctly. We use Cap’n Proto’s canonical form as specified in the encoding spec: https://capnproto.org/encoding.html#canonicalization

Canonical form guarantees:

  • Same logical data → identical bytes (always)
  • Preorder encoding (deterministic pointer ordering)
  • Single segment (no segment boundary ambiguity)
  • Truncated trailing zeros (no padding differences)
  • No packing (binary format is deterministic)
  • No segment table framing (redundant for signing)

These bytes are what gets signed in a SignedEnvelope.

Trait Implementations§

Source§

impl Clone for RequestEnvelope

Source§

fn clone(&self) -> RequestEnvelope

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for RequestEnvelope

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl FromCapnp for RequestEnvelope

Source§

type Reader<'a> = Reader<'a>

The Cap’n Proto reader type for this struct.
Source§

fn read_from(reader: Self::Reader<'_>) -> Result<Self>

Read this struct’s fields from the reader.
Source§

impl ToCapnp for RequestEnvelope

Source§

type Builder<'a> = Builder<'a>

The Cap’n Proto builder type for this struct.
Source§

fn write_to(&self, builder: &mut Self::Builder<'_>)

Write this struct’s fields to the builder.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,

Source§

impl<T> TerminalState for T
where T: Clone + Send + Sync,