ores.iam.authorization_messages

/**
 * @brief One resource of the permission catalogue and what an account holds of it.
 *
 * The unit of a page. A screen draws a resource as a row with its actions as
 * columns, so a page holds whole rows and never half of one. =actions= are the
 * actions the catalogue defines for the resource, =held= the ones the account's
 * roles grant, and =roles= the roles that grant any of them, so a screen can
 * say why without reading the roles again.
 */

/**
 * @brief One area (a component) in which an account holds something, and how
 * many of its resources they hold.
 *
 * The areas a screen offers to choose from. An area the account holds nothing
 * in is not listed, so there is nothing to choose that would show an empty page.
 */

/**
 * @brief One page of what an account's roles let it do, by resource.
 *
 * The caller needs iam::roles:read, as reading the account's roles does. The
 * page is the server's: =offset= and =limit= bound the rows, =area= narrows
 * them to one component, and =search= to a resource or component name. An empty
 * =area= means the first area the account holds something in, so a page is
 * always of one area.
 */

/**
 * @brief One page of what the caller's own roles let them do, by resource.
 *
 * The session names the account, so the request names none and the read needs
 * no permission: it is a self read on the allow-list of Authorised reads. The
 * paging fields are those of iam.v1.ops.list_account_permissions.
 */

/**
 * @brief One page of the permission catalogue against what one role grants.
 *
 * It serves the role editor, which must offer every permission to tick, not
 * only the ones the role holds, so =include_unheld= asks for the rows the role
 * does not grant too. The paging fields are those of
 * iam.v1.ops.list_account_permissions. The caller needs iam::roles:read.
 */

/**
 * @brief One role as the roles list draws it.
 *
 * The permissions are counted, not listed: the list says how much a role lets
 * people do, and the role's own page pages what it lets them do. A service
 * role's count is zero, because it is not given to people and is not changed
 * from a screen.
 */

/**
 * @brief One page of the tenant's roles.
 *
 * =search= matches a role's name or description, =area= keeps the roles that
 * grant something in that area, and =include_service= brings in the platform's
 * own service roles, which are left out otherwise. A =role_id= names one role
 * and ignores the rest, so the role's own page reads its header the same way.
 * The caller needs iam::roles:read.
 */

/**
 * @brief One person who holds a role, as the role's page draws them.
 *
 * Carries what a screen needs to name and show the person and say who gave the
 * role, so the page makes no second read per person. The picture is the
 * identifier of the account's image, empty when it has none.
 */

/**
 * @brief One page of the people who hold a role, by name.
 *
 * The caller needs iam::roles:read, as reading who holds a role does. The page
 * is the server's: =offset= and =limit= bound the rows and =total_count= says
 * how many people hold the role.
 */

/**
 * @brief One role an account holds, with the permissions it grants and the
 * record of its assignment.
 *
 * The element both access reads answer with, so the member's screen and the
 * administrator's render one type. The permissions are attributed to the
 * role rather than flattened into one list, and the tail is the junction
 * row's own record of who granted the role, when and why.
 */

/**
 * @brief Replaces the permissions a role bundles.
 *
 * The codes are the whole bundle the role should carry, not an increment: a
 * code the role bundles and this request omits is removed, and a code both
 * name stays. The write answers with the bundle as stored, so the caller
 * reads back what it wrote rather than assuming the two agree.
 *
 * The change reason and commentary are the junction row's own record of who
 * changed the bundle, when and why; the actor is stamped from the request.
 */