Expand description
Request envelope for RPC with Ed25519 signatures and E2E integrity.
Every RPC request is wrapped in a SignedEnvelope that carries:
- A unique request ID for correlation
- The serialized inner request payload
- Authorization context (local claims, federated JWT, or ID-JAG)
- Ed25519 signature over the entire RequestEnvelope
- Nonce + timestamp (iat) for replay protection
§Two-Layer Security
| Layer | Mechanism | Purpose |
|---|---|---|
| Transport | CURVE/QUIC-TLS | Encrypts connection, authenticates immediate peer |
| Application | Signed envelope | E2E integrity through brokers, authenticates originator |
§Envelope Structure
SignedEnvelope {
envelope: RequestEnvelope {
request_id, payload, iat, nonce,
authorization, delegation_token, wth
},
sig, // Ed25519 signature over canonical(envelope)
cnf, // Ed25519 public key (RFC 7800 confirmation key)
}Structs§
- Envelope
Verify Config - Process-wide envelope verification configuration shared by all production
verify sites (
process_request/RequestLoop,StreamServiceregister). - Federated
Token - Federated token from a foreign issuer.
- InMemory
Nonce Cache - Simple in-memory nonce cache with time-based expiration.
- Keyed
PqTrust Store - In-memory kid-anchored ML-DSA-65 trust store mapping an Ed25519 signer identity to its trusted ML-DSA-65 verifying key.
- Request
Envelope - Unsigned envelope wrapping an RPC request.
- Response
Envelope - Signed response envelope for E2E authenticated responses.
- Response
Verify Config - Process-wide RESPONSE-envelope verify configuration consulted by clients that did not explicitly set a per-client response policy / PQ store (#277).
- Signed
Envelope - Signed envelope wrapping a RequestEnvelope with Ed25519 signature.
- Subject
- Authorization subject for Casbin policy checks and resource isolation.
- Token
Claims - Verified token claims (local issuer).
- Unwrap
Options - Options controlling envelope unwrap, verification, and optional decryption.
Enums§
- Authorization
- Authorization context carried inside a
RequestEnvelope. - Envelope
Verification - How to verify the envelope signer.
Constants§
- ENVELOPE_
SCHEMA_ ID - Cap’n Proto file id of
common.capnp(the envelope schema). Used as the first component of the COSEexternal_aadschema-binding. - MAX_
CLOCK_ SKEW_ MS - Maximum clock skew tolerance (30 seconds into the future).
- MAX_
MEDIATED_ EVIDENCE_ BYTES - Hard wire-size cap for original-holder authorization-query evidence.
- MAX_
SERVICE_ DOMAIN_ BYTES - MAX_
TIMESTAMP_ AGE_ MS - Maximum age for a valid request timestamp (5 minutes).
- REQUEST_
ENVELOPE_ TYPE_ ID - Stable inner-type id for
RequestEnvelopein the COSEexternal_aad. Distinct from any payload schema id; binds the COSE signature to the envelope structure to prevent schema-confusion / cross-protocol replay. - RESPONSE_
ENVELOPE_ TYPE_ ID - Stable inner-type id for
ResponseEnvelope, distinct fromREQUEST_ENVELOPE_TYPE_ID. TheResponseEnvelopeCOSE composite (#275) binds this type-id into itsexternal_aadvia [response_envelope_external_aad], so a response COSE signature can NEVER verify as a request signature (or vice-versa) — the request↔response domain separation is cryptographically enforced, not merely documented.
Traits§
- Nonce
Cache - Replay protection cache interface.
- PqTrust
Store - Resolves the anchored ML-DSA-65 verifying key for an EdDSA signer identity.
Functions§
- apply_
global_ verify_ config - Apply the mandatory process-global policy and trust store to an
UnwrapOptions. - current_
timestamp - Get current Unix timestamp in milliseconds. Used for envelope timestamp validation.
- generate_
nonce - Generate a random 16-byte nonce for replay protection.
- global_
browser_ currentness_ verifier - global_
pq_ store - The installed kid-anchored PQ trust store, if any.
- global_
response_ pq_ store - The installed RESPONSE-side kid-anchored PQ trust store, if any.
- global_
response_ verify_ policy - The enforced RESPONSE-verify policy (consulted when a client did not set one).
- global_
verify_ policy - The enforced verify policy.
- install_
browser_ currentness_ verifier - Install the checkpoint-backed authority used at WebTransport dispatch. First write wins; there is deliberately no test/global fallback.
- install_
response_ verify_ config - Install the process-global RESPONSE verify configuration. First write wins.
- install_
verify_ config - Install the process-global envelope verify configuration. First write wins.
- mandatory_
envelope_ policy - The production policy-selected pinned suite. There is deliberately no environment or wire input: peers either support it fully or admission fails.
- next_
request_ id - Generate a unique request ID
- response_
verify_ config_ installed - Whether a process-global RESPONSE verify configuration has been installed.
- unwrap_
and_ verify - Unwrap and verify a SignedEnvelope from wire bytes.
- unwrap_
envelope - Unwrap, verify, and build an
EnvelopeContextfrom wire bytes. - unwrap_
response_ with - Unwrap and verify a ResponseEnvelope under an explicit kid-anchored PQ trust store + verify policy (#275).
- validate_
service_ domain - Validate the one canonical RPC service/destination identifier.
- verify_
config_ installed - Whether a process-global verify configuration has been installed.
- verify_
mediated_ envelope_ evidence - Decode and authenticate a bounded original request for a mediated policy query. This proves the signed transcript only: callers must separately verify the credential, method/operation binding and query replay admission. It must never be used to install an identity on the mediator’s context.