Skip to main content

Crate hyprstream_rpc

Crate hyprstream_rpc 

Source
Expand description

RPC infrastructure for hyprstream services.

This crate provides:

  • ToCapnp / FromCapnp traits and derive macros for Cap’n Proto serialization
  • ZMTP framing over UDS/QUIC/iroh transports
  • Service dispatch helpers
  • Ed25519 signed envelopes for request authentication
  • DH key exchange + HMAC for streaming response authentication

§Security Model

All RPC messages are wrapped in signed envelopes:

  • Transport layer: TLS 1.3 (QUIC) or UDS peer credentials (IPC)
  • Application layer: Ed25519 signatures (survives message forwarding)

Streaming responses use HMAC-SHA256 derived from DH shared secrets.

§Feature Flags

  • Default: Ristretto255 for DH key exchange (prime-order group, no cofactor issues)
  • fips: ECDH P-256 for FIPS 140-2 compliance

§Example

ⓘ
use hyprstream_rpc::prelude::*;

#[derive(FromCapnp)]
#[capnp(my_schema_capnp::my_response)]
pub struct MyResponse {
    pub result: String,
}

// Client method becomes a one-liner
async fn get_result(&self) -> Result<MyResponse> {
    self.rpc.call(GetResultRequest).await
}

Re-exports§

pub use capnp::serialize_message;
pub use capnp::FromCapnp;
pub use capnp::ToCapnp;
pub use rpc_client::CallOptions;
pub use rpc_client::PreSealGuard;
pub use rpc_client::RequestBuilder;
pub use rpc_client::RpcClient;
pub use rpc_client::RpcClientImpl;
pub use rpc_client::RpcClientProvider;
pub use transport_traits::PublishSink;
pub use transport_traits::Signer;
pub use transport_traits::Transport;
pub use crypto::generate_signing_keypair;
pub use crypto::signing_key_from_bytes;
pub use crypto::verifying_key_from_bytes;
pub use crypto::DefaultKeyExchange;
pub use crypto::KeyExchange;
pub use crypto::SharedSecret;
pub use stream_info::StreamInfo;
pub use crypto::generate_ephemeral_keypair;
pub use crypto::ristretto_dh;
pub use crypto::RistrettoPublic;
pub use crypto::RistrettoSecret;
pub use envelope::unwrap_envelope;
pub use envelope::unwrap_and_verify;
pub use envelope::Authorization;
pub use envelope::EnvelopeVerification;
pub use envelope::FederatedToken;
pub use envelope::InMemoryNonceCache;
pub use envelope::KeyedPqTrustStore;
pub use envelope::NonceCache;
pub use envelope::PqTrustStore;
pub use envelope::RequestEnvelope;
pub use envelope::ResponseEnvelope;
pub use envelope::SignedEnvelope;
pub use envelope::Subject;
pub use envelope::TokenClaims;
pub use envelope::UnwrapOptions;
pub use envelope::MAX_CLOCK_SKEW_MS;
pub use envelope::MAX_TIMESTAMP_AGE_MS;
pub use error::EnvelopeError;
pub use error::EnvelopeResult;
pub use error::Result;
pub use error::RpcError;
pub use resolver::NetworkDiscoveryResolver;
pub use resolver::Resolver;
pub use resolver::ResolverProfile;
pub use resolver::ServiceQuery;
pub use registry::SocketKind;
pub use service::Continuation;
pub use service::EnvelopeContext;
pub use service::RequestService;
pub use service::ServiceHandle;
pub use service::Spawnable;
pub use streaming::derive_client_stream_keys;
pub use streaming::progress_channel;
pub use streaming::ChannelProgressReporter;
pub use streaming::ProgressUpdate;
pub use streaming::ResponseStream;
pub use streaming::StreamChannel;
pub use streaming::StreamContext;
pub use streaming::StreamPayload;
pub use streaming::StreamPayloadData;
pub use streaming::StreamVerifier;

Modules§

admission
Federation admission gate over DID/key binding (#137, milestone M3).
annotations_capnp
auth
JWT authorization types and utilities.
authorization_witness
Purpose-bound hybrid holder evidence for read-only Policy queries. This is deliberately not a credential, envelope signature, or v16 proof.
browser_provisioning
Accepted-current browser/WebTransport recipient provisioning.
capnp
Cap’n Proto serialization traits and helpers.
cid
CIDv1 + multihash encoder for content-addressed model references (#395).
common_capnp
common_types
crypto
Cryptographic primitives for secure RPC communication.
dial
The dial() factory: the single place transport choice is made.
did_key
Shared did:key (Ed25519) ⇄ raw-key codec.
did_plc
did:plc → DID document resolution — federation intake (#1161, epic #1158 E1).
did_url
DID URL parser + inert dereference plan (#906, at9p epic #880 G1).
did_web
did:web → dialable TransportConfig resolution (#279).
envelope
Request envelope for RPC with Ed25519 signatures and E2E integrity.
error
Error types for the RPC system.
event_subject
Canonical at-record subject + keyed group-scoped routing leaf (EV3, epic #600).
events
Unified EventService publisher/subscriber (epic #600).
events_capnp
federated_identity
Federated identity provider — extends node identity with cross-node trust.
identity
Identity provider abstraction for unified key management.
identity_resolver
Method-dispatched IdentityResolver — the real Did → IdentityKeys binding (#579).
latch
Latched completion / retained terminal state (EV7, epic #600).
metadata
Schema introspection metadata types — used by proc macro codegen on all targets.
moq_authz
Subscribe-time authorization + per-tenant announce scoping for the moq streaming plane (#276).
moq_event
moq-lite event bus plane — replaces the ZMQ XPUB/XSUB ProxyService (#167).
moq_stream
moq-lite streaming plane (M2a of epic #134).
nine_capnp
node_identity
Node identity provider — native key management with HKDF purpose derivation.
notify
Service notification helpers
optional_capnp
paths
Runtime path resolution for system vs user mode
platform
Platform-adaptive concurrency primitives.
prelude
proof
v16 proof-CWT wire support — canonical parser, replay admission, response binding.
registry
Centralized endpoint registry for service discovery.
resolver
Service endpoint resolution abstraction.
rpc_client
Unified RPC client parameterized over Signer and Transport.
sensitive
Wire-compatible bytes whose diagnostic representation never exposes contents.
service
Service-side RPC infrastructure.
service_entry
DID-document transport service-entry codec.
session_pq_overlay
Session-scoped PQ binding overlay: trust-on-first-use continuity for browser and other dynamically-identified clients, with out-of-band promotion.
signer
Signer implementations for Ed25519 envelope signing.
socket
Socket activation helpers
stream_consumer
Cross-target streaming consumer types.
stream_epoch
Identified point-to-point stream epoch cryptography (#554).
stream_info
Target-independent StreamInfo + StreamOpt types.
stream_provenance
Per-host provenance signing/verification for the mesh stream plane (#321).
streaming
Generic streaming infrastructure for authenticated PUB/SUB communication.
streaming_capnp
streaming_types
Code-generated streaming data types (#273): StreamInfo, StreamOpt, and the five QoS axis unions (Ordering/Delivery/Completion/Retention/ OverflowPolicy). Re-exported through stream_info (the canonical hub) so service codegen and call sites keep resolving hyprstream_rpc::stream_info::*.
transport
Transport layer for RPC communication.
transport_traits
Transport and Signer traits for unified RPC communication.
wasm_token_exchange
Browser-side RFC 8693 token-exchange (#1314) for the wasm client. Pure parsing helpers compile on all targets (unit-tested on native); the browser fetch glue is wasm32-only. Browser-side RFC 8693 token-exchange (#1314) for the wasm client.
zmtp_framing
Pure ZMTP 3.1 framing — zero I/O, zero async, wasm32-safe.

Structs§

SigningKey
ed25519 signing key which can be used to produce signatures.
StreamHmacState
Chained HMAC state for stream block authentication, matching wire format.
VerifyingKey
An ed25519 public key.

Functions§

has_systemd

Attribute Macros§

authorize
Attribute macro for method-level authorization with structured scopes.
service_factory
Attribute macro for service factory registration.

Derive Macros§

FromCapnp
Derive macro for deserializing Cap’n Proto to Rust types.
ToCapnp
Derive macro for serializing Rust types to Cap’n Proto.