control_broker.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/inspect/control_admission.hpp>
#include <pulp/inspect/control_artifacts.hpp>
 
#include <memory>
#include <mutex>
#include <span>
#include <string_view>
 
namespace pulp::inspect {
 
struct ControlBrokerConfig {
    ControlIdentityRegistryConfig identities;
    ControlGrantStoreConfig grants;
    ControlAdmissionPolicy admission;
    std::optional<ControlOperationStoreConfig> operation_store;
    std::optional<ControlArtifactStoreConfig> artifact_store;
    ControlOperationStore::WallClock wall_clock = [] { return std::chrono::system_clock::now(); };
    std::function<ControlProcessLiveness(const ControlPeerEvidence&)> process_liveness =
        [](const ControlPeerEvidence&) { return ControlProcessLiveness::Unknown; };

    std::function<void(const ControlClientId&, const ControlRegistrationId&,
                       const ControlGrantId&, std::string_view)> authority_ended;
};
 
struct ControlBrokerLifecycleResult {
    bool identity_removed = false;
    std::size_t grants_revoked = 0;
};

class ControlBroker {
  public:
    using Clock = ControlIdentityRegistry::Clock;

    explicit ControlBroker(
        ControlBrokerConfig config = {}, std::shared_ptr<ControlSecurityAuditLog> audit_log = {},
        Clock clock = [] { return std::chrono::steady_clock::now(); });
    ~ControlBroker();
    ControlBroker(const ControlBroker&) = delete;
    ControlBroker& operator=(const ControlBroker&) = delete;
 
    const ControlBrokerId& broker_id() const;
    bool is_listening() const {
        return false;
    }
 
    ControlBootstrapResult issue_bootstrap(const VerifiedControlPeerIdentity& client_peer);
    ControlClientResult redeem_bootstrap(std::string_view ticket_id,
                                         std::span<const std::uint8_t> secret,
                                         const VerifiedControlPeerIdentity& client_peer,
                                         std::string_view durable_principal = {},
                                         ControlDurableClientLifetime durable_lifetime =
                                             ControlDurableClientLifetime::Broker);
    bool refresh_client(const ControlClientId& client_id,
                        const VerifiedControlPeerIdentity& client_peer);
    ControlBrokerLifecycleResult disconnect_client(const ControlClientId& client_id,
                                                   const VerifiedControlPeerIdentity& client_peer,
                                                   std::string_view decision_id);
 
    ControlRegistrationResult register_instance(const VerifiedControlPeerIdentity& host_peer,
                                                 ControlRegistrationRequest request,
                                                 bool publish = true);
    bool publish_instance(const ControlRegistrationId& registration_id,
                          const VerifiedControlPeerIdentity& host_peer);
    bool heartbeat(const ControlRegistrationId& registration_id,
                   const VerifiedControlPeerIdentity& host_peer);
    ControlBrokerLifecycleResult unregister_instance(const ControlRegistrationId& registration_id,
                                                     const VerifiedControlPeerIdentity& host_peer,
                                                     std::string_view decision_id);
 
    ControlGrantResult issue_grant(const VerifiedControlPeerIdentity& client_peer,
                                   ControlGrantRequest request, ControlConsentDecision consent);
    ControlGrantStatus revoke_grant(const ControlGrantId& grant_id, std::string_view decision_id);
    bool is_granted(const ControlGrantId& grant_id, const ControlClientId& client_id,
                    const ControlRegistrationId& registration_id, InspectorCapability capability);

    ControlAdmissionResult admit_operation(const VerifiedControlPeerIdentity& client_peer,
                                           const ControlRequestEnvelope& request);
    ControlAdmissionResult replay_operation(const VerifiedControlPeerIdentity& client_peer,
                                            const ControlRequestEnvelope& request);
    bool revalidate_operation(const VerifiedControlPeerIdentity& client_peer,
                              const ControlAdmissionPlan& plan);
    bool operation_store_ready() const;
    bool artifact_store_ready() const;
    ControlOperationStoreResult begin_operation(const VerifiedControlPeerIdentity& client_peer,
                                                const ControlAdmissionPlan& plan);
    ControlOperationStoreResult finish_operation(const VerifiedControlPeerIdentity& client_peer,
                                                 const ControlAdmissionPlan& plan,
                                                 ControlReceiptState terminal_state,
                                                 ControlOperationResult result = {});
    ControlOperationStoreResult cancel_operation(const VerifiedControlPeerIdentity& client_peer,
                                                 const ControlClientId& client_id,
                                                 std::string_view request_id,
                                                 std::string_view reason);
    bool operation_cancellation_requested(const VerifiedControlPeerIdentity& client_peer,
                                          const ControlAdmissionPlan& plan) const;
    ControlExecutionCheckpoint execution_checkpoint(const VerifiedControlPeerIdentity& client_peer,
                                                    const ControlAdmissionPlan& plan);
    std::optional<ControlOperationReceipt>
    operation_receipt(const ControlReceiptId& receipt_id) const;

    ControlArtifactStoreResult
    store_operation_artifact(const VerifiedControlPeerIdentity& client_peer,
                             const ControlAdmissionPlan& plan, std::span<const std::uint8_t> bytes,
                             ControlArtifactProperties properties);
    ControlArtifactStoreResult
    store_operation_artifact(const VerifiedControlPeerIdentity& client_peer,
                             const ControlAdmissionPlan& plan, std::span<const std::uint8_t> bytes,
                             std::string content_type, ControlArtifactSensitivity sensitivity,
                             ControlArtifactRedactionState redaction_state,
                             std::chrono::milliseconds lifetime);
    std::size_t artifact_maximum_blob_bytes() const noexcept;

    ControlArtifactReadResult read_artifact(const VerifiedControlPeerIdentity& client_peer,
                                            const ControlClientId& requesting_client_id,
                                            std::string_view artifact_id, std::uint64_t offset,
                                            std::size_t maximum_bytes);
 
    std::optional<ControlClientIdentity> client(const ControlClientId& client_id) const;
    std::optional<ControlRegistration>
    registration(const ControlRegistrationId& registration_id) const;
    std::vector<ControlRegistration> registrations() const;
    std::optional<ControlGrant> grant(const ControlGrantId& grant_id);
 
    void sweep_expired();
 
  private:
    bool authorize_artifact_read_locked(const VerifiedControlPeerIdentity& client_peer,
                                        const ControlClientId& requesting_client_id,
                                        const ControlArtifactMetadata& metadata);
    ControlAdmissionResult admit_verified_operation(const VerifiedControlPeerIdentity& client_peer,
                                                    const ControlAdmissionRequest& request,
                                                    bool allow_new = true);
    bool revalidate_operation_locked(const VerifiedControlPeerIdentity& client_peer,
                                     const ControlAdmissionPlan& plan);
    void audit_denial(std::string_view action, const VerifiedControlPeerIdentity& observed_peer,
                      std::string_view reason, const ControlClientId& client_id = {},
                      const ControlRegistrationId& registration_id = {});
    bool owns_client_peer(const ControlClientId& client_id,
                          const VerifiedControlPeerIdentity& client_peer) const;
    bool owns_registration_peer(const ControlRegistrationId& registration_id,
                                const VerifiedControlPeerIdentity& host_peer) const;
    void request_active_cancellation(const ControlClientId& client_id,
                                     const ControlRegistrationId& registration_id,
                                     const ControlGrantId& grant_id, std::string_view reason);
 
    std::shared_ptr<ControlSecurityAuditLog> audit_log_;
    std::function<ControlProcessLiveness(const ControlPeerEvidence&)> process_liveness_;
    std::function<void(const ControlClientId&, const ControlRegistrationId&,
                       const ControlGrantId&, std::string_view)> authority_ended_;
    mutable std::mutex coordination_mutex_;
    ControlIdentityRegistry identities_;
    ControlGrantStore grants_;
    ControlAdmissionPolicy admission_policy_;
    ControlOperationStore::WallClock wall_clock_;
    std::unique_ptr<ControlOperationStore> operation_store_;
    std::unique_ptr<ControlArtifactStore> artifact_store_;
};
 
} // namespace pulp::inspect