Skip to main content

Module envelope

Module envelope 

Source
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

LayerMechanismPurpose
TransportCURVE/QUIC-TLSEncrypts connection, authenticates immediate peer
ApplicationSigned envelopeE2E 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§

EnvelopeVerifyConfig
Process-wide envelope verification configuration shared by all production verify sites (process_request / RequestLoop, StreamService register).
FederatedToken
Federated token from a foreign issuer.
InMemoryNonceCache
Simple in-memory nonce cache with time-based expiration.
KeyedPqTrustStore
In-memory kid-anchored ML-DSA-65 trust store mapping an Ed25519 signer identity to its trusted ML-DSA-65 verifying key.
RequestEnvelope
Unsigned envelope wrapping an RPC request.
ResponseEnvelope
Signed response envelope for E2E authenticated responses.
ResponseVerifyConfig
Process-wide RESPONSE-envelope verify configuration consulted by clients that did not explicitly set a per-client response policy / PQ store (#277).
SignedEnvelope
Signed envelope wrapping a RequestEnvelope with Ed25519 signature.
Subject
Authorization subject for Casbin policy checks and resource isolation.
TokenClaims
Verified token claims (local issuer).
UnwrapOptions
Options controlling envelope unwrap, verification, and optional decryption.

Enums§

Authorization
Authorization context carried inside a RequestEnvelope.
EnvelopeVerification
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 COSE external_aad schema-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 RequestEnvelope in the COSE external_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 from REQUEST_ENVELOPE_TYPE_ID. The ResponseEnvelope COSE composite (#275) binds this type-id into its external_aad via [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§

NonceCache
Replay protection cache interface.
PqTrustStore
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 EnvelopeContext from 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.