Task: Re-verify the four access documents against the tree
Table of Contents
This page documents a task in the Implement the access journeys in ores.web story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
(Describe what user-visible-or-internal change this task produces.)
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Implement the access journeys in ores.web |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-09-30 |
3. Acceptance
- Every gap the four documents record is checked against the current tree, with the command that proves each verdict.
- A gap that has closed is corrected in the document that records it, so a reader does not build work that is already done.
- A gap that is still open names the subject that would close it.
- The open list is short enough to size the group's remaining tasks.
4. Plan
- Read each document's * What is missing and its * Operations and messages, because a gap is claimed in both.
- Check each claim against the tree: the handler's permission check, the
message's fields, the entity model's
:no_wire:flags, the seeded permission codes, the junction table's columns and the generated protocol's subjects. - Correct the documents whose claims the tree contradicts, in place, and record the correction on this task.
- Leave the open gaps as they stand and name the subject that closes each.
5. Measurements
| What | Value | Command | Commit | |
|---|---|---|---|---|
| Gaps the four documents record | 19 | grep -c "^[0-9]" doc/knowledge/journeys/access/journey_*.org (per the three older documents; the fourth was written from the tree) |
669c52eec5 |
|
| Gaps already closed | 2 | grep -n "no_wire" projects/ores.iam/modeling/ores.iam.account.org and grep -n "roles_assign" projects/ores.iam/core/include/ores.iam.core/messaging/authorization_handler.hpp |
669c52eec5 |
|
| Permission codes a handler asks for and no seed defines | 2, iam::roles:write and iam::permissions:write |
grep -rhn "has_permission(req_ctx" projects/ores.iam/core/include/ores.iam.core/messaging/role_handler.hpp projects/ores.iam/core/include/ores.iam.core/messaging/permission_handler.hpp against =grep -n "iam::roles:update\ |
iam::permissions:write" projects/ores.sql/populate/iam/iam_permissions_populate.sql= | 669c52eec5 |
| Subjects that write a role's permissions | 0 | =ls projects/ores.iam/api/include/ores.iam.api/messaging/ | grep -i role_permission= | 669c52eec5 |
6. Notes
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #2446 | [agile] Scaffold the access journeys group and survey its documents |
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
Nineteen gaps across the three documents written on 2026-09-23, plus the seven the role request records. Two have closed and their documents no longer claim them. The rest are confirmed open, each with the subject that would close it.
10.1. Closed
| Gap | Document | The evidence that closed it |
|---|---|---|
iam.v1.roles.assign checks no permission, so any signed-in account could grant any role in its tenant |
Change someone's access | authorization_handler.hpp refuses an assign from a caller without iam::roles:assign, and a revoke without iam::roles:revoke. |
| The account read carries credential material | Change someone's access | password_hash, password_salt, service_password_hash and totp_secret are :no_wire: in ores.iam.account.org, so no read returns them. |
10.2. Open
| Gap | Document | What would close it |
|---|---|---|
| The role reads prove a session only and take an arbitrary account id, so a member can read a colleague's access | Know what I may do | A self-scoped form of each read, or iam::roles:read plus an own-account check. |
A permission is not attributed to the role that grants it: permissions-by-account answers a flat list |
Know what I may do | A response that pairs each code with the role it arrives through. |
| The roles read carries no assignment dates | Know what I may do | The assignment read below. |
No subject returns the account_role row, so assigned_by, assigned_at and the reason cannot be shown |
Change someone's access | iam.v1.roles.assignments-by-account. |
| The grant and the revoke carry no reason | Change someone's access | change_reason_code and change_commentary on both requests. |
| Nothing warns before the last role is revoked | Change someone's access | A screen rule rather than a subject; it belongs to the access screen. |
| No subject adds or removes a permission on a role | Shape the role catalogue | iam.v1.roles.permissions.put and .put_many, with a change reason. |
The role handler asks for iam::roles:write, which no seed defines; the seed defines iam::roles:update |
Shape the role catalogue | Seed the code the handler asks for, or change the handler to the code the seed defines. |
The role_permission link has no audit tail, while account_role has one |
Shape the role catalogue | assigned_by, assigned_at and a reason on the junction, as its sibling carries. |
The permission CRUD asks for iam::permissions:write and :delete, and no seed defines either |
Shape the role catalogue | Seed both, or drop the subjects, because the model says permissions are seeded constants. |
| Five request subjects do not exist | Ask for more access | iam.v1.roles.request, .requests-by-me, .withdraw-request, .requests and .refuse-request. |
| The engine cannot hold a request that waits on a person | Ask for more access | A waiting state and a decision verb in ores.workflow, or an approval step kind. |
| Nothing stops the requester answering their own request | Ask for more access | A guard on the decision. |
| Nothing says which roles may be asked for | Ask for more access | An is_requestable flag on the role row. |
| Nothing tells either person that something happened | Ask for more access | A notification of its own. |
| No query returns a request as a row | Ask for more access | A projection beside the workflow instance read. |
| A request nobody answers waits forever | Ask for more access | A review window, as a setting. |
10.3. What this sizes
The member's own read needs three of the open gaps closed, and the
administrator's grant needs one more: those four are
Close the access reads. The
catalogue needs all four of its own, which is
Let a role's permission bundle be
written plus the two permission-code corrections. The role request needs the
seven it records, which is
Land the role request, and two of
those are ores.workflow's rather than this component's.
10.4. Corrected in the documents
Change someone's access no longer claims either closed gap. Its * Operations and messages states that both writes check their own permission, and its * What is missing drops the credential-material item in favour of a paragraph recording that it closed and why. The correction is recorded rather than deleted, because a reader who finds no gap there would otherwise go looking for one that is not there — the same rule the entry group followed when the registration policy landed.