Expand description
RPC infrastructure for hyprstream services.
This crate provides:
ToCapnp/FromCapnptraits 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 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→ dialableTransportConfigresolution (#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 realDid → IdentityKeysbinding (#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 throughstream_info(the canonical hub) so service codegen and call sites keep resolvinghyprstream_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
fetchglue iswasm32-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§
- Signing
Key - ed25519 signing key which can be used to produce signatures.
- Stream
Hmac State - Chained HMAC state for stream block authentication, matching wire format.
- Verifying
Key - An ed25519 public key.
Functions§
Attribute Macros§
- authorize
- Attribute macro for method-level authorization with structured scopes.
- service_
factory - Attribute macro for service factory registration.