core.cxxm

Go to the documentation of this file.

/// SPDX-License-Identifier: Apache-2.0
/// @file zxfoundation/dgp/cap.zcomponent/core.cxxm
/// @brief Capability management — acquire, release, derive, and validate
///        capability tokens for the DGP kernel's authorization model.
 
export module zxfoundation.dgp.cap.core;
import zxfoundation.dgp.cap.types;
import zxfoundation.base.types;
import zxfoundation.scoms.kobject.base;
import zxfoundation.dgp.domain.types;
import zxfoundation.dgp.gate.types;
import zxfoundation.dgp.portal.types;
import zxfoundation.memory.objects.core;
import lib.error;
import std;
 
export {
 
namespace zxfoundation::dgp::cap {
 
    /// @brief Acquire a private capability derived from an owned capability.
    /// @param[in]  source   Capability owned by @p owner_domain.
    /// @param[in]  rights   Rights to retain from @p source.
    /// @param[in]  owner_domain Domain receiving the new capability.
    /// @return  cap_token on success, kernel_error on failure.
    [[nodiscard]] auto cap_acquire(
        cap_token  source,
        cap_rights rights,
        u32        owner_domain
    ) noexcept -> std::expected<cap_token, lib::kernel_error>;
 
    /// @brief Issue a capability from nucleus-owned object authority.
    /// @param[in] type Resource type.
    /// @param[in] obj_id SCOMS object ID.
    /// @param[in] rights Rights granted to the recipient.
    /// @param[in] owner_domain Domain receiving the capability.
    [[nodiscard]] auto cap_issue(
        cap_type type, u16 obj_id, cap_rights rights, u32 owner_domain
    ) noexcept -> std::expected<cap_token, lib::kernel_error>;
 
    /// @brief Duplicate a capability for a new owner from kernel policy code.
    /// @param[in] source Existing capability.
    /// @param[in] rights Rights to retain.
    /// @param[in] owner_domain Domain receiving the capability.
    [[nodiscard]] auto cap_duplicate(
        cap_token source, cap_rights rights, u32 owner_domain
    ) noexcept -> std::expected<cap_token, lib::kernel_error>;
 
    /// @brief Duplicate a capability after checking its current owner.
    [[nodiscard]] auto cap_duplicate_for(
        cap_token source, cap_rights rights, u32 source_domain,
        u32 owner_domain
    ) noexcept -> std::expected<cap_token, lib::kernel_error>;
 
    /// @brief Release a previously acquired capability.
    /// @param[in]  token  The capability token to release.
    /// @return  Success, or kernel_error if the token is invalid.
    /// @note  Decrements the underlying object's reference count.
    [[nodiscard]] auto cap_release(cap_token token) noexcept
        -> std::expected<void, lib::kernel_error>;
 
    /// @brief Validate a capability token and return the underlying object.
    /// @tparam     T      Expected kobject type (domain, gate_desc, etc.).
    /// @param[in]  token  The capability token to validate.
    /// @param[in]  needed Rights required for the intended operation.
    /// @return  Pointer to the validated object, or kernel_error.
    template <typename T>
    [[nodiscard]] auto cap_validate(cap_token token, cap_rights needed) noexcept
        -> std::expected<T*, lib::kernel_error>;
 
    /// @brief Validate a capability token without a concrete type parameter
    /// @note  Unlike cap_validate<T>, this does not return the object pointer —
    ///        it only returns success/failure.
    [[nodiscard]] auto cap_validate_generic(
        cap_token   token,
        cap_rights  needed
    ) noexcept -> std::expected<void, lib::kernel_error>;
 
    /// @brief Validate a capability against its owning domain.
    /// @param[in] token Capability supplied by the caller.
    /// @param[in] needed Rights required by the operation.
    /// @param[in] owner_domain Domain making the call.
    [[nodiscard]] auto cap_validate_generic_for(
        cap_token token, cap_rights needed, u32 owner_domain
    ) noexcept -> std::expected<void, lib::kernel_error>;
 
    /// @brief Resolve a validated capability to its SCOMS object.
    /// @param[in] token Capability supplied by a caller.
    /// @param[in] needed Rights required by the operation.
    /// @return Referenced SCOMS object, or an authorization error.
    [[nodiscard]] auto cap_resolve(
        cap_token token, cap_rights needed
    ) noexcept -> std::expected<scoms::kobject::bobject*, lib::kernel_error>;
 
    /// @brief Revoke a capability token administratively.
    /// @param[in] token   Capability token marking the object to revoke.
    /// @return Success, or kernel_error if the token is null or the object
    ///         vanished before we could bump its generation.
    [[nodiscard]] auto cap_revoke(cap_token token) noexcept
        -> std::expected<void, lib::kernel_error>;
 
    /// @brief Revoke every capability owned by or targeting a domain.
    /// @param[in] domain_id Domain entering teardown.
    /// @return Number of revoked capability slots, or an error.
    [[nodiscard]] auto cap_revoke_for_domain(
        u32 domain_id
    ) noexcept -> std::expected<u32, lib::kernel_error>;
 
    /// @brief Revoke all slots referring to a SCOMS object.
    /// @param[in] target Object being destroyed.
    /// @return Number of revoked slots, or an error.
    [[nodiscard]] auto cap_revoke_target(
        scoms::kobject::bobject& target
    ) noexcept -> std::expected<u32, lib::kernel_error>;
 
    /// @brief Callback signature for looking up a kobject by object ID.
    /// @param[in] obj_id  Object ID (u16 from capability token).
    /// @return Pointer to the kobject, or nullptr if not found.
    using lookup_fn = auto (*)(u16 obj_id) noexcept -> scoms::kobject::bobject*;
 
    /// @brief Register a lookup callback for a resource type.
    /// @param[in] type  The resource type to associate with the callback.
    /// @param[in] fn    The callback.
    /// @return Success, or kernel_error if the type is out of range.
    [[nodiscard]] auto register_lookup(
        cap_type   type,
        lookup_fn  fn
    ) noexcept -> std::expected<void, lib::kernel_error>;
 
    template <>
    [[nodiscard]] auto cap_validate<zxfoundation::dgp::domain::domain>(
        cap_token token, cap_rights needed
    ) noexcept -> std::expected<zxfoundation::dgp::domain::domain*, lib::kernel_error>;
 
    template <>
    [[nodiscard]] auto cap_validate<zxfoundation::dgp::gate::gate_desc>(
        cap_token token, cap_rights needed
    ) noexcept -> std::expected<zxfoundation::dgp::gate::gate_desc*, lib::kernel_error>;
 
    template <>
    [[nodiscard]] auto cap_validate<zxfoundation::dgp::portal::portal_desc>(
        cap_token token, cap_rights needed
    ) noexcept -> std::expected<zxfoundation::dgp::portal::portal_desc*, lib::kernel_error>;
 
    template <>
    [[nodiscard]] auto cap_validate<zxfoundation::memory::objects::memory_object>(
        cap_token token, cap_rights needed
    ) noexcept -> std::expected<zxfoundation::memory::objects::memory_object*, lib::kernel_error>;
 
} // namespace zxfoundation::dgp::cap
 
} // end export