dispatch.h File Reference

UDIF application-layer dispatcher and per-message handler signatures. More...

#include "udif.h"
#include "entity.h"
#include "message.h"
#include "tunnel.h"

Go to the source code of this file.

Typedefs
typedef udif_errors(*	udif_handler_fn) (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Function-pointer type for a UDIF message handler.

Functions
UDIF_EXPORT_API udif_errors	udif_dispatch (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Dispatch a decoded UDIF message to the appropriate handler.
UDIF_EXPORT_API bool	udif_dispatch_is_permitted (udif_roles role, udif_message_type msgtype)
	Check whether a role is permitted to receive a message type.
UDIF_EXPORT_API udif_errors	udif_handle_cert_enroll_req (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle an inbound CSR from a subordinate.
UDIF_EXPORT_API udif_errors	udif_handle_cert_enroll_resp (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle an inbound signed certificate from a parent.
UDIF_EXPORT_API udif_errors	udif_handle_cert_revoke (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a revocation notice from a parent.
UDIF_EXPORT_API udif_errors	udif_handle_cert_suspend (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a suspension notice from a parent.
UDIF_EXPORT_API udif_errors	udif_handle_cert_resume (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a resumption notice from a parent.
UDIF_EXPORT_API udif_errors	udif_handle_cap_grant (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a parent-issued capability grant.
UDIF_EXPORT_API udif_errors	udif_handle_cap_revoke (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a capability revocation notice.
UDIF_EXPORT_API udif_errors	udif_handle_query_req (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a predicate query from a subordinate or peer.
UDIF_EXPORT_API udif_errors	udif_handle_query_resp (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a predicate query response from a controller.
UDIF_EXPORT_API udif_errors	udif_handle_object_create (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle an object creation request from a UA.
UDIF_EXPORT_API udif_errors	udif_handle_object_transfer_req (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle the sender-signed transfer request.
UDIF_EXPORT_API udif_errors	udif_handle_object_transfer_confirm (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle the receiver-signed transfer confirmation.
UDIF_EXPORT_API udif_errors	udif_handle_registry_commit (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a registry root commit notification.
UDIF_EXPORT_API udif_errors	udif_handle_anchor_push (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle an inbound anchor record from a child controller.
UDIF_EXPORT_API udif_errors	udif_handle_anchor_ack (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle an anchor acknowledgement from a parent.
UDIF_EXPORT_API udif_errors	udif_handle_treaty_propose (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a treaty proposal from a peer BC.
UDIF_EXPORT_API udif_errors	udif_handle_treaty_cosign (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a treaty co-signature from the peer BC.
UDIF_EXPORT_API udif_errors	udif_handle_treaty_revoke (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a treaty revocation.
UDIF_EXPORT_API udif_errors	udif_handle_treaty_query_fwd (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a forwarded cross-domain query from a peer BC.
UDIF_EXPORT_API udif_errors	udif_handle_treaty_query_resp (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a cross-domain query response from a peer BC.
UDIF_EXPORT_API udif_errors	udif_handle_error_report (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Handle a non-fatal error report from a peer.

Detailed Description

UDIF application-layer dispatcher and per-message handler signatures.

The dispatcher is the single ingress point for decoded UDIF messages. It enforces role-based admissibility against the running entity's udif_roles value (a UA will not honor udif_msg_cert_enroll_req, a GC will not honor udif_msg_anchor_push, and so on), then invokes the handler registered for the message type. Handlers are pure functions of (entity state, tunnel, decoded message, current time) and emit zero, one, or more response messages by calling udif_tunnel_send directly on the supplied tunnel.

Correlation is carried inside each message's canonical payload (query id, certificate serial, treaty id, object serial) rather than at the framing layer. The dispatcher does not track outstanding requests.

Handlers return a tri-state outcome via udif_errors:

• udif_error_none on success
• a fatal code (udif_error_auth_failure, udif_error_invalid_sequence, udif_error_mac_invalid) causes the dispatcher's caller to close the tunnel
• a non-fatal code (udif_error_not_authorized, udif_error_object_not_found, udif_error_invalid_request) causes the dispatcher to emit a udif_msg_error_report on the tunnel and leave it open

Typedef Documentation

udif_handler_fn

typedef udif_errors(* udif_handler_fn) (udif_entity_context *ctx, udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)

Function-pointer type for a UDIF message handler.

Parameters

ctx	The entity context
tun	The tunnel on which the message arrived. Handlers send replies by calling udif_tunnel_send on this tunnel or another tunnel resolved via udif_entity_find_tunnel.
msg	[const] The decoded inbound message. Payload is owned by the dispatcher and must not be freed by the handler.
nowsecs	The current UTC seconds, passed to udif_tunnel_send for timer updates and embedded in outbound payload timestamps.

Returns

Returns udif_error_none on success, a fatal error code to signal the caller to close the tunnel, or a non-fatal error code which the dispatcher will surface as udif_msg_error_report.

Function Documentation

udif_dispatch()

UDIF_EXPORT_API udif_errors udif_dispatch	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Dispatch a decoded UDIF message to the appropriate handler.

Steps performed:

1. If msg->msgtype is udif_msg_keepalive, returns immediately (timer updates are already handled by udif_tunnel_on_receive).
2. Looks up (ctx->role, msg->msgtype) in the role-allowance table. Returns udif_error_not_authorized if the combination is rejected.
3. For peer-authenticated control messages, validates the tunnel peer certificate with recursive chain verification and active status checks before invoking the message handler.
4. Invokes the handler registered for msg->msgtype.
5. If the handler returns a non-fatal error, emits a udif_msg_error_report on the tunnel. If it returns a fatal error, returns the error to the caller so the main loop can close the tunnel.

Parameters

ctx	The entity context
tun	The tunnel the message arrived on
msg	[const] The decoded message
nowsecs	The current UTC seconds

Returns

Returns udif_error_none on success, or a fatal transport-class error.

udif_dispatch_is_permitted()

UDIF_EXPORT_API bool udif_dispatch_is_permitted	(	udif_roles	role,
		udif_message_type	msgtype )

Check whether a role is permitted to receive a message type.

Exposed for testing and for pre-send checks in operator CLIs.

Parameters

role	The entity role
msgtype	The message type code

Returns

Returns true if permitted, false if rejected by the role-allowance table.

udif_handle_anchor_ack()

UDIF_EXPORT_API udif_errors udif_handle_anchor_ack	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle an anchor acknowledgement from a parent.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC).

Records successful upstream commit of the referenced anchor sequence. Failure to receive an acknowledgement within the profile's cadence window is surfaced to the operator as a health warning.

udif_handle_anchor_push()

UDIF_EXPORT_API udif_errors udif_handle_anchor_push	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle an inbound anchor record from a child controller.

Permitted for: udif_role_ubc (BC), udif_role_root.

Verifies the child's signature via udif_anchor_verify, enforces strictly increasing anchor sequence via udif_anchor_validate_sequence, commits the anchor digest to the local membership log, and sends udif_msg_anchor_ack back on tun.

udif_handle_cap_grant()

UDIF_EXPORT_API udif_errors udif_handle_cap_grant	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a parent-issued capability grant.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Verifies the capability digest and KMAC tag with the configured capability verification key, installs the token in the runtime capability store, and logs the grant event.

udif_handle_cap_revoke()

UDIF_EXPORT_API udif_errors udif_handle_cap_revoke	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a capability revocation notice.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Marks the referenced capability digest as revoked in the runtime capability store and logs the revocation event.

udif_handle_cert_enroll_req()

UDIF_EXPORT_API udif_errors udif_handle_cert_enroll_req	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle an inbound CSR from a subordinate.

Permitted for: udif_role_root, udif_role_ubc (BC), udif_role_ugc (GC).

Validates the CSR signature and requested capability scope, signs the certificate via udif_certificate_generate, commits the issuance event to the membership log, and sends udif_msg_cert_enroll_resp back on tun.

udif_handle_cert_enroll_resp()

UDIF_EXPORT_API udif_errors udif_handle_cert_enroll_resp	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle an inbound signed certificate from a parent.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Verifies the parent's signature via udif_certificate_verify, installs the certificate locally as selfcert, and commits the receipt event to the local membership log (if the role keeps one).

udif_handle_cert_resume()

UDIF_EXPORT_API udif_errors udif_handle_cert_resume	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a resumption notice from a parent.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Clears a prior suspension, logs the event, and permits traffic to resume.

udif_handle_cert_revoke()

UDIF_EXPORT_API udif_errors udif_handle_cert_revoke	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a revocation notice from a parent.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Installs the revocation locally; on BC and GC, cascades to subordinates by closing their tunnels and rejecting future traffic from them.

udif_handle_cert_suspend()

UDIF_EXPORT_API udif_errors udif_handle_cert_suspend	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a suspension notice from a parent.

Permitted for: udif_role_ubc (BC), udif_role_ugc (GC), udif_role_client (UA).

Marks the subject suspended locally; blocks outbound requests until a resume notice is received.

udif_handle_error_report()

UDIF_EXPORT_API udif_errors udif_handle_error_report	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a non-fatal error report from a peer.

Permitted for: all roles.

Surfaces the error to the operator CLI and updates telemetry counters. Does not reply.

udif_handle_object_create()

UDIF_EXPORT_API udif_errors udif_handle_object_create	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle an object creation request from a UA.

Permitted for: udif_role_ugc (GC).

Validates the UA's signature via udif_object_verify and its capability, commits the object to storage, updates the UA's registry root via udif_registry_add_object, appends a creation event to the transaction log, and returns a signed commit acknowledgement.

udif_handle_object_transfer_confirm()

UDIF_EXPORT_API udif_errors udif_handle_object_transfer_confirm	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle the receiver-signed transfer confirmation.

Permitted for: udif_role_ugc (GC).

Validates both UA signatures via udif_transfer_verify (sender on the original request, receiver on the confirmation), applies the ownership change, commits the transfer event to the transaction log, updates both UAs' registries, and sends signed commit acknowledgements to both parties.

udif_handle_object_transfer_req()

UDIF_EXPORT_API udif_errors udif_handle_object_transfer_req	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle the sender-signed transfer request.

Permitted for: udif_role_ugc (GC).

Validates the sender UA's signature and ownership, records the pending transfer, and forwards the request to the receiver UA's tunnel (if connected) for counter-signature. If the receiver is in a different group under the same BC, the GC routes via the BC.

udif_handle_query_req()

UDIF_EXPORT_API udif_errors udif_handle_query_req	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a predicate query from a subordinate or peer.

Permitted for: udif_role_ugc (GC), udif_role_ubc (BC).

Verifies the querying entity's signature and capability via udif_query_validate_authorization, evaluates the predicate against the local ledger and registry state, emits udif_msg_query_resp with the appropriate verdict and optional Merkle proof, and logs the exchange to the membership log.

For cross-domain queries, the handler validates the treaty scope and forwards via udif_msg_treaty_query_fwd on the appropriate treaty tunnel resolved through udif_entity_find_tunnel.

udif_handle_query_resp()

UDIF_EXPORT_API udif_errors udif_handle_query_resp	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a predicate query response from a controller.

Permitted for: udif_role_client (UA), udif_role_ugc (GC) when forwarding on behalf of a UA, udif_role_ubc (BC) for cross-domain.

Verifies the responder's signature via udif_query_verify_response, matches the response to a pending request via the queryid embedded in the payload, and surfaces the verdict to the local application layer or operator CLI.

udif_handle_registry_commit()

UDIF_EXPORT_API udif_errors udif_handle_registry_commit	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a registry root commit notification.

Permitted for: udif_role_ugc (GC) receiving from UA, udif_role_ubc (BC) receiving from GC.

Records the updated registry root and binds it into the local membership log for inclusion in the next anchor record.

udif_handle_treaty_cosign()

UDIF_EXPORT_API udif_errors udif_handle_treaty_cosign	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a treaty co-signature from the peer BC.

Permitted for: udif_role_ubc (BC).

Validates both signatures via udif_treaty_verify, commits the final treaty to the local membership log, and activates the treaty for cross-domain queries.

udif_handle_treaty_propose()

UDIF_EXPORT_API udif_errors udif_handle_treaty_propose	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a treaty proposal from a peer BC.

Permitted for: udif_role_ubc (BC).

Validates the proposing BC's signature via udif_treaty_verify (single-side, since Domain B has not signed yet), presents the terms to the operator (or applies an automatic policy), and either returns udif_msg_treaty_cosign or a udif_msg_error_report with a decline code.

udif_handle_treaty_query_fwd()

UDIF_EXPORT_API udif_errors udif_handle_treaty_query_fwd	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a forwarded cross-domain query from a peer BC.

Permitted for: udif_role_ubc (BC).

Validates that the treaty is active via udif_treaty_is_active and that the query's predicate family is in the treaty scope bitmap via udif_treaty_allows_scope. Evaluates the predicate locally (or routes it to the appropriate GC), logs the forwarded query, and replies with udif_msg_treaty_query_resp on the same treaty tunnel.

udif_handle_treaty_query_resp()

UDIF_EXPORT_API udif_errors udif_handle_treaty_query_resp	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a cross-domain query response from a peer BC.

Permitted for: udif_role_ubc (BC).

Validates the peer BC's signature, logs the response, and relays the verdict back to the originating GC (and ultimately the UA that issued the cross-domain query).

udif_handle_treaty_revoke()

UDIF_EXPORT_API udif_errors udif_handle_treaty_revoke	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Handle a treaty revocation.

Permitted for: udif_role_ubc (BC).

Validates the revoking BC's signature, marks the treaty revoked, closes the associated treaty tunnel, and logs the revocation.