## Summary A GraphQL type with `authorize_granular_token skip_reason: :parent_authorizes` has no fine-grained token check of its own. It relies on whatever permission the parent checked, and that permission differs from parent to parent. https://gitlab.com/gitlab-org/gitlab/-/work_items/636258 describes the problem. This issue proposes that each of these types names the token permission it needs. Every field that returns the type checks that permission at runtime, on the parent's group or project, before the resolver runs. `gitlab:permissions:validate` makes sure every path to the type is covered. ## Problem For example, `WorkItemType` skips its check. A token needs `read_issue` to reach it through `Issue.workItemType` and `read_work_item` through `WorkItem.workItemType`. Adding a field, or changing a parent's permission, silently changes what tokens need, and validation still passes. As of 2026-11-02 there are 248 skipped types. 94 of them are returned directly by fields on types that check the token, and 27 are returned by more than one field. For 9 of those, the token permission depends on the field. ## Proposal ### 1. Declare the permission on the type `authorize_granular_token` gets a `parent_authorizes:` argument that takes a permission: ```ruby authorize_granular_token parent_authorizes: :read_work_item_type ``` The type still skips its own per-object check, as it does today. Fields that return the type read the permission from it. Types that don't declare one keep `skip_reason: :parent_authorizes` until they are migrated. ### 2. Check it at the field `BaseField#granular_token_authorized?` passes today when the field has no directive of its own. With this change, when the returned type declares a permission and the parent type has a real token check, the field checks the declared permission on the parent's boundary, before the resolver runs. - The boundary comes from the parent type's own directives, with the permission replaced. `GranularScopeAuthorization` gets a `permissions:` override for this. Parents with several boundaries then find their group or project the same way their own type check does. - The parent type comes from `ctx[:current_object]`, not `field.owner`. Fields defined on an interface have an owner without a token check, while the concrete type has one. - A field with its own directive keeps using it. Validation checks that it includes the declared permission. - Mutation results are not checked, as today. The mutation's own directive covers them. - Nested types, whose parent is itself `parent_authorizes`, have no boundary to check against at runtime. Validation covers them (check 4). - Results are cached per request by permission and boundary, so a list in one project costs one extra check. ### 3. Choose the permission The rules in [Assignable permissions](https://docs.gitlab.com/development/permissions/granular_access/assignable_permissions/) decide where the raw permission goes: - Most types hold data that anyone who can read the parent already sees, such as metadata, value objects and wrappers. Their permission goes into the parent's assignable permission. No token gains or loses access. - Some types hold data that needs more than the parent's read permission, for example a higher role, a license, or data from other projects. Their permission gets its own assignable permission. Fine-grained tokens are generally available, so a type that gets its own assignable permission must not break existing tokens. A data migration with `rename_granular_scope_permission` adds the new assignable permission to every token that holds the parent's. Existing tokens keep their access, and new tokens have to ask for it. The declared permission must also be a policy ability on the boundary. On public projects and groups, `Authz::BoundaryPolicy` grants a token any permission an anonymous user has, so the ability has to match the data. ### 4. Validation checks All checks run in `gitlab:permissions:validate`. Existing gaps go into `config/authz/graphql/authorization_todo.txt`, so validation passes on the first day and catches anything new. 1. Every `parent_authorizes` type returned by a field on a token-checked type declares a permission. 1. The declared permission is assignable on every boundary type it is checked on, and is a policy ability there. All possible types of an interface or union declare the same permission, because the field cannot know the concrete type before the resolver runs. 1. A field directive on a field that returns a declared type includes the declared permission. 1. Every path into a nested type includes the permission it declares. This reuses the path walker from https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266839, which keeps one permission set per path, continues through skipped and connection types, ignores mutation payloads and handles cycles. 1. Root `Query` and `Subscription` fields that return these types have their own directive, and mutations that return them have a real token check. 1. A type whose permission has its own assignable permission is not returned by a non-null field. A denied check on a non-null field would null the parent. ## Rollout 1. Add field directives with the right permission to the fields with known gaps, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/638052. This needs none of the new mechanism. 1. One MR with the `parent_authorizes:` argument, the runtime check and the validation checks, with the todo file seeded from the current schema. They ship together, because check 4 assumes that direct fields are checked at runtime. A query-count spec on a list across several projects guards the cost of the field check. This replaces https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266839. 1. Move field directives onto their types where the parent's boundary is the right one, and remove the directives that only repeat the derived check. 1. Owning teams clear the todo file, starting with the 9 types whose permission depends on the field. ## Out of scope - Types without a token check deny fine-grained tokens only after their resolver has run. - A list field's count is calculated before the items are checked. ## History The first version of this issue proposed a `parent_permissions:` list on the type, checked only by `gitlab:permissions:validate` (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266839). It compared permission names and changed nothing at runtime, so it recorded the existing permissions, including the ones that are too broad. A type with a single parent always passed. The MR is on hold, and its path walker becomes check 4. The design comes from Ian Anderson's proposal and the discussion in #g_sscs_authorization_engineering. Which permission each type declares is discussed in https://gitlab.com/gitlab-org/gitlab/-/work_items/638052.