Skip to main content

RequestService

Trait RequestService 

Source
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<Pin<Box<dyn Future<Output = ()>>>>), Error>> + 'async_trait>> where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait; fn decode_request_body( &self, signed_body: &[u8], ) -> Result<DecodedRequestBody, Error>; fn name(&self) -> &str; fn transport(&self) -> &TransportConfig; fn signing_key(&self) -> SigningKey; // Provided methods fn producer_reach_config_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, ProducerReachConfig>>> { ... } fn moq_origin_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, Option<MoqStreamOrigin>>>> { ... } fn pq_signing_key(&self) -> Option<SigningKey<MlDsa65>> { ... } 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), Error>> + 'async_trait>> where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: '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<(), Error>> + 'async_trait>> where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, Self: '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, Error>> + 'async_trait>> where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait { ... } fn verify_claims<'life0, 'life1, 'async_trait>( &'life0 self, ctx: &'life1 mut EnvelopeContext, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>> where 'life0: 'async_trait, 'life1: 'async_trait, Self: '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:

  1. Handle requests via handle_request()
  2. Are automatically spawnable (blanket impl Spawnable for S: RequestService)

Required Methods§

Source

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<Pin<Box<dyn Future<Output = ()>>>>), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Process a request and return a response with optional continuation.

§Arguments
  • ctx - Verified envelope context with identity
  • body - The request body decoded exactly once by RequestService::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 REP
  • continuation: 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.

Source

fn decode_request_body( &self, signed_body: &[u8], ) -> Result<DecodedRequestBody, Error>

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.

Source

fn name(&self) -> &str

Service name (for logging and registry).

Source

fn transport(&self) -> &TransportConfig

Transport configuration (endpoint binding).

Source

fn signing_key(&self) -> SigningKey

Ed25519 signing key for signing responses.

Provided Methods§

Source

fn producer_reach_config_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, ProducerReachConfig>>>

Mutable reach source filled by the unified service spawner after the service’s QUIC and iroh listeners bind.

Source

fn moq_origin_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, Option<MoqStreamOrigin>>>>

Optional per-service MoQ origin source. The unified spawner installs a scoped origin here when this service has a relay configured.

Source

fn pq_signing_key(&self) -> Option<SigningKey<MlDsa65>>

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.

Source

fn verifying_key(&self) -> VerifyingKey

Ed25519 verifying key for envelope signature verification.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: '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.

Source

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<(), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, Self: '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.

Source

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, Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: '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.

Source

fn verify_claims<'life0, 'life1, 'async_trait>( &'life0 self, ctx: &'life1 mut EnvelopeContext, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: '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.

Source

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.

Implementations on Foreign Types§

Source§

impl RequestService for WorkerService

Source§

fn decode_request_body( &self, signed_body: &[u8], ) -> Result<DecodedRequestBody, Error>

Source§

fn producer_reach_config_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, ProducerReachConfig>>>

Source§

fn moq_origin_handle( &self, ) -> Option<Arc<RwLock<RawRwLock, Option<MoqStreamOrigin>>>>

Source§

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<Pin<Box<dyn Future<Output = ()>>>>), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, WorkerService: 'async_trait,

Source§

fn name(&self) -> &str

Source§

fn transport(&self) -> &TransportConfig

Source§

fn signing_key(&self) -> SigningKey

Source§

fn expected_audience(&self) -> Option<&str>

Source§

fn jwt_key_source(&self) -> Option<Arc<dyn JwtKeySource>>

Source§

impl RequestService for WorkflowService

Source§

fn accept_delegated_bearer(&self, signer_pubkey: &[u8; 32]) -> bool

Accept delegated-bearer requests by consulting the live MCP relay authorizer (#989 review). verify_claims calls this before policy; the default false rejects all relayed caller tokens. We delegate to the injected authorizer (which checks current MCP-scope authorization) — fail-closed when no authorizer is set.

Source§

fn decode_request_body( &self, signed_body: &[u8], ) -> Result<DecodedRequestBody, Error>

Source§

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<Pin<Box<dyn Future<Output = ()>>>>), Error>> + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, WorkflowService: 'async_trait,

Source§

fn name(&self) -> &str

Source§

fn transport(&self) -> &TransportConfig

Source§

fn signing_key(&self) -> SigningKey

Source§

fn expected_audience(&self) -> Option<&str>

Source§

fn jwt_key_source(&self) -> Option<Arc<dyn JwtKeySource>>

Implementors§