pub trait RequestService: 'static {
Show 25 methods
// Required methods
fn handle_request<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
ctx: &'life1 EnvelopeContext,
body: &'life2 DecodedRequestBody,
) -> Pin<Box<dyn Future<Output = Result<(Vec<u8>, Option<Continuation>)>> + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait;
fn decode_request_body(
&self,
signed_body: &[u8],
) -> Result<DecodedRequestBody>;
fn name(&self) -> &str;
fn transport(&self) -> &TransportConfig;
fn signing_key(&self) -> SigningKey;
// Provided methods
fn producer_reach_config_handle(&self) -> Option<ProducerReachConfigHandle> { ... }
fn moq_origin_handle(&self) -> Option<MoqStreamOriginHandle> { ... }
fn pq_signing_key(&self) -> Option<MlDsaSigningKey> { ... }
fn verifying_key(&self) -> VerifyingKey { ... }
fn jwt_key_source(&self) -> Option<Arc<dyn JwtKeySource>> { ... }
fn expected_audience(&self) -> Option<&str> { ... }
fn delegated_user_audience(
&self,
_signer_pubkey: &[u8; 32],
_untrusted_aud: Option<&str>,
) -> Option<&str> { ... }
fn accept_delegated_resource_leaf(
&self,
_ctx: &EnvelopeContext,
_body: &DecodedRequestBody,
) -> bool { ... }
fn require_cnf_binding(&self) -> bool { ... }
fn credential_revocation_store(
&self,
) -> Option<&dyn CredentialRevocationStore> { ... }
fn jwt_verify_policy(&self) -> CryptoPolicy { ... }
fn resolve_key_subject(&self, signer_pubkey: &[u8; 32]) -> Option<Subject> { ... }
fn cache_key_binding(
&self,
_verifying_key: VerifyingKey,
_subject: &str,
_jwt: &str,
_expires_at: i64,
) { ... }
fn accept_delegated_bearer(&self, _signer_pubkey: &[u8; 32]) -> bool { ... }
fn accept_deferred_federate_credential(&self) -> bool { ... }
fn admit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_body: &'life2 DecodedRequestBody,
_proof: &'life3 ParsedProof,
) -> Pin<Box<dyn Future<Output = Result<(VerifiedProof, [u8; 32], String, String, ProofReplayKey, u64)>> + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait { ... }
fn commit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_resource: &'life2 str,
_operation: &'life3 str,
_replay_key: &'life4 ProofReplayKey,
_replay_expiry: u64,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait { ... }
fn verify_internal_work_bearer<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_token: &'life2 str,
_protected: &'life3 ProtectedHeader,
) -> Pin<Box<dyn Future<Output = Result<InternalWorkClaims>> + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait { ... }
fn verify_claims<'life0, 'life1, 'async_trait>(
&'life0 self,
ctx: &'life1 mut EnvelopeContext,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait { ... }
fn build_error_payload(&self, request_id: u64, error: &str) -> Vec<u8> ⓘ { ... }
}Expand description
Trait for RPC services.
This is the unified trait for services that:
- Handle requests via
handle_request() - Are automatically spawnable (blanket
impl Spawnable for S: RequestService)
Required Methods§
Sourcefn handle_request<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
ctx: &'life1 EnvelopeContext,
body: &'life2 DecodedRequestBody,
) -> Pin<Box<dyn Future<Output = Result<(Vec<u8>, Option<Continuation>)>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
fn handle_request<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
ctx: &'life1 EnvelopeContext,
body: &'life2 DecodedRequestBody,
) -> Pin<Box<dyn Future<Output = Result<(Vec<u8>, Option<Continuation>)>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Process a request and return a response with optional continuation.
§Arguments
ctx- Verified envelope context with identitybody- The request body decoded exactly once byRequestService::decode_request_body(v16 §5.2). Generated dispatch reads the typed request from [DecodedRequestBody::root] — the same decoded message whose derived leaf fed the generated method policy and the dispatch MAC PEP — never from a second decode of the bytes.
Returns (response_bytes, optional_continuation):
response_bytes: Cap’n Proto encoded response sent as REPcontinuation: Optional future spawned AFTER the REP is sent (used for streaming: ensures client has stream_id before data flows)
Non-streaming services always return None for the continuation.
Sourcefn decode_request_body(&self, signed_body: &[u8]) -> Result<DecodedRequestBody>
fn decode_request_body(&self, signed_body: &[u8]) -> Result<DecodedRequestBody>
Decode the signed request body exactly once (bounded) and derive the full numeric method leaf path (v16 §5.2 step 4).
The returned [DecodedRequestBody] is the one decode for the entire
request lifetime: its leaf path keys the generated method policy and
the dispatch MAC PEP, and its decoded message is what
RequestService::handle_request dispatches from. The leaf comes
from the signed body — never from a transport-specific hint such as
the browser transcript’s method commitment, which does not exist on
other carriers and is not the signed leaf.
This method is required — there is deliberately no default. A
schema-generated service delegates to its generated
decode_<service>_request_body function; a service with no Cap’n
Proto request schema must affirmatively construct
[DecodedRequestBody::opaque], which denies proof-bearing dispatch at
leaf derivation instead of silently passing a policy row it never
resolved.
An unknown discriminant, a malformed body, or a body exceeding the reviewed decode caps is an error — the same denial as an unlisted leaf, never a coarser fallback.
Sourcefn transport(&self) -> &TransportConfig
fn transport(&self) -> &TransportConfig
Transport configuration (endpoint binding).
Sourcefn signing_key(&self) -> SigningKey
fn signing_key(&self) -> SigningKey
Ed25519 signing key for signing responses.
Provided Methods§
Sourcefn producer_reach_config_handle(&self) -> Option<ProducerReachConfigHandle>
fn producer_reach_config_handle(&self) -> Option<ProducerReachConfigHandle>
Mutable reach source filled by the unified service spawner after the service’s QUIC and iroh listeners bind.
Sourcefn moq_origin_handle(&self) -> Option<MoqStreamOriginHandle>
fn moq_origin_handle(&self) -> Option<MoqStreamOriginHandle>
Optional per-service MoQ origin source. The unified spawner installs a scoped origin here when this service has a relay configured.
Sourcefn pq_signing_key(&self) -> Option<MlDsaSigningKey>
fn pq_signing_key(&self) -> Option<MlDsaSigningKey>
ML-DSA-65 signing key for the post-quantum half of the response COSE
composite (#275). Returning None makes process_request fail closed
before dispatch; it never selects an EdDSA-only response. The matching ML-DSA-65 public key
must be anchored in the client’s PQ trust store for Hybrid verification
to succeed (peer attestation).
The default derives the node’s persistent mesh ML-DSA-65 key
deterministically from this service’s Ed25519 Self::signing_key via
crate::node_identity::derive_mesh_mldsa_key (#157). Because the EdDSA
half of the response is signed with that same Ed25519 key (dispatch is
handed service.signing_key()), the kid-anchored binding the client
stores — Ed25519 signer pubkey → ML-DSA vk — is self-consistent, and the
published #mesh-pq DID verification method equals this signing key.
Mirrors the request-side mandatory pinned suite.
Sourcefn verifying_key(&self) -> VerifyingKey
fn verifying_key(&self) -> VerifyingKey
Ed25519 verifying key for envelope signature verification.
Sourcefn jwt_key_source(&self) -> Option<Arc<dyn JwtKeySource>>
fn jwt_key_source(&self) -> Option<Arc<dyn JwtKeySource>>
JWT key source for token verification.
Returns the key source used to verify JWT signatures. Services must
provide this to enable JWT verification. Returns None by default,
which means JWT verification is skipped (anonymous access only).
Most services should return a ClusterKeySource that trusts the
cluster’s CA key. PolicyService may return a FederatedKeySource
for cross-cluster token exchange.
Sourcefn expected_audience(&self) -> Option<&str>
fn expected_audience(&self) -> Option<&str>
Expected audience (resource URL) for JWT validation.
When Some, verify_claims() rejects tokens whose aud claim doesn’t match.
Override this on services that should bind tokens to a specific resource.
Sourcefn delegated_user_audience(
&self,
_signer_pubkey: &[u8; 32],
_untrusted_aud: Option<&str>,
) -> Option<&str>
fn delegated_user_audience( &self, _signer_pubkey: &[u8; 32], _untrusted_aud: Option<&str>, ) -> Option<&str>
Select an exact, configured audience for an already-admitted delegated
user bearer. The unverified claim is only a selector: implementations
must return their own configured string, never a borrowed token value.
Direct and service credentials always use expected_audience instead.
Sourcefn accept_delegated_resource_leaf(
&self,
_ctx: &EnvelopeContext,
_body: &DecodedRequestBody,
) -> bool
fn accept_delegated_resource_leaf( &self, _ctx: &EnvelopeContext, _body: &DecodedRequestBody, ) -> bool
Admit a non-native resource bearer only for a decoded signed request leaf. Default denial preserves every service’s native issuer boundary.
Sourcefn require_cnf_binding(&self) -> bool
fn require_cnf_binding(&self) -> bool
Whether to reject JWTs that lack a cnf key binding (jwk or jkt).
When true, verify_claims() will reject any JWT that does not carry
a cnf confirmation key, ensuring every authenticated request is
cryptographically bound to its envelope signer.
Default is true — override to false only for services that
intentionally accept unbound JWTs (e.g., legacy compatibility).
Sourcefn credential_revocation_store(&self) -> Option<&dyn CredentialRevocationStore>
fn credential_revocation_store(&self) -> Option<&dyn CredentialRevocationStore>
Credential revocation store for access token revocation.
Returns the process-global store published at startup: the durable
authority store in the policy process, or a policy-authority RPC
client store in every other process (checks cross the RPC bus to the
policy service, the one canonical revocation authority). When None
(startup not yet complete or authority initialization failed),
verify_claims() rejects tokens with a jti (fail-closed). Override
only for specialized testing.
Sourcefn jwt_verify_policy(&self) -> CryptoPolicy
fn jwt_verify_policy(&self) -> CryptoPolicy
Fu4/#677: the minimum JWT alg policy enforced in verify_claims.
Under [CryptoPolicy::Hybrid] a classical-only (EdDSA) JWT is rejected
outright, independent of JWKS kid_algs hygiene. The default reads the
process-global envelope verify config (Hybrid in production), so the
per-call policy is test-isolated from sibling tests that mutate the
shared global.
Sourcefn resolve_key_subject(&self, signer_pubkey: &[u8; 32]) -> Option<Subject>
fn resolve_key_subject(&self, signer_pubkey: &[u8; 32]) -> Option<Subject>
Resolve a verified signer key to an authorization subject (#446).
Consulted by verify_claims for an unauthenticated (no-JWT) request: the
envelope cnf (the signer’s Ed25519 pubkey, already verified by the COSE
signature check) is mapped to its authoritative subject so a signed
service-to-service IPC caller resolves as its service:<name> identity
instead of anonymous.
The default routes through the process-global key→subject
resolver, which the trust-store layer
(hyprstream-service, populated fail-closed under #441) installs at
startup. This wires every service — including those whose crate cannot
depend on the trust store (e.g. DiscoveryService) — without each one
re-implementing the lookup.
Fail-closed: an unregistered key resolves to None → anonymous, so a
genuinely anonymous caller stays denied for policy-gated writes. Override
only to bypass or narrow this resolution; never to fabricate identity.
Sourcefn cache_key_binding(
&self,
_verifying_key: VerifyingKey,
_subject: &str,
_jwt: &str,
_expires_at: i64,
)
fn cache_key_binding( &self, _verifying_key: VerifyingKey, _subject: &str, _jwt: &str, _expires_at: i64, )
Cache a verified key→subject binding in the trust store.
Called after successful JWT verification when the JWT’s pub_key matches
the envelope signer. Default implementation is a no-op.
Sourcefn accept_delegated_bearer(&self, _signer_pubkey: &[u8; 32]) -> bool
fn accept_delegated_bearer(&self, _signer_pubkey: &[u8; 32]) -> bool
Accept a relayed bearer from this verified envelope signer. Services enabling this must pin an independently configured controller key.
Sourcefn accept_deferred_federate_credential(&self) -> bool
fn accept_deferred_federate_credential(&self) -> bool
Opt in only when this serving instance has a complete request-local holder-proof, current-primary and durable Policy-use adapter. Default false preserves the generic verifier’s reserved-profile denial.
Sourcefn admit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_body: &'life2 DecodedRequestBody,
_proof: &'life3 ParsedProof,
) -> Pin<Box<dyn Future<Output = Result<(VerifiedProof, [u8; 32], String, String, ProofReplayKey, u64)>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
fn admit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_body: &'life2 DecodedRequestBody,
_proof: &'life3 ParsedProof,
) -> Pin<Box<dyn Future<Output = Result<(VerifiedProof, [u8; 32], String, String, ProofReplayKey, u64)>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Verify the original holder’s proof and bind it to the exact decoded
body/leaf/resource/action before identity publication. This stage must
not consume replay state: generated method-policy and MAC authorization
still run afterward. Durable Policy admission happens in
commit_deferred_federate_request only after those gates pass.
Sourcefn commit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_resource: &'life2 str,
_operation: &'life3 str,
_replay_key: &'life4 ProofReplayKey,
_replay_expiry: u64,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
fn commit_deferred_federate_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_resource: &'life2 str,
_operation: &'life3 str,
_replay_key: &'life4 ProofReplayKey,
_replay_expiry: u64,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
Perform fresh Policy admission and durable replay consumption after the generated method-policy and mandatory MAC gates, immediately before handler dispatch. Implementations must fail closed if the durable admission service is unavailable. The default never admits a request.
Sourcefn verify_internal_work_bearer<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_token: &'life2 str,
_protected: &'life3 ProtectedHeader,
) -> Pin<Box<dyn Future<Output = Result<InternalWorkClaims>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
fn verify_internal_work_bearer<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
_ctx: &'life1 EnvelopeContext,
_token: &'life2 str,
_protected: &'life3 ProtectedHeader,
) -> Pin<Box<dyn Future<Output = Result<InternalWorkClaims>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Verify an iw+jwt internal execution work order presented as the
direct JWT (single-service Model→Inference boundary, user-approved D5).
The generic pipeline rejects this token type at EVERY service by
default; only a service operating a pinned execution boundary overrides
this hook. The override must authenticate the token against the PINNED
controller key and bind it to the exact instance/tenant/model/operation
admitted. On Ok the pipeline installs the original-caller identity
(subject, tenant, claims snapshot) and the
InternalWorkContext
on the context; the work order is never a bearer anywhere else.
Sourcefn verify_claims<'life0, 'life1, 'async_trait>(
&'life0 self,
ctx: &'life1 mut EnvelopeContext,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
fn verify_claims<'life0, 'life1, 'async_trait>(
&'life0 self,
ctx: &'life1 mut EnvelopeContext,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
E2E JWT verification with unified key source.
Called by process_request after envelope signature verification.
Takes &mut EnvelopeContext to store the resolved jwt_subject directly,
which correctly distinguishes local tokens (bare sub) from federated
ones (iss:sub format) using the key source’s local_issuers().
Async because federated key resolution may require an HTTP JWKS fetch.
Prefers jwt_token (opaque token string) over legacy claims field.
When jwt_token is present, the server decodes and verifies it directly.
The legacy claims path is kept for backwards compat with older clients.
Sourcefn build_error_payload(&self, request_id: u64, error: &str) -> Vec<u8> ⓘ
fn build_error_payload(&self, request_id: u64, error: &str) -> Vec<u8> ⓘ
Build a generic error response payload for unexpected errors.
Default implementation returns an empty vec (backwards compat).
Generated services should override with schema-correct error payloads
so clients receive proper Error(ErrorInfo{...}) instead of parse failures.