Add granular token directives to MCP-reached GraphQL types

Alex Buijsrequested to merge
631631-mcp-graphql-granular-directives into master

What does this MR do and why?

With a fine-grained PAT, any GraphQL object type without an authorize_granular_token directive resolves to null, because Gitlab::Graphql::Authz::GranularScopeAuthorization denies when no directive is declared. GitLab's MCP server runs GraphQL queries on behalf of the token. Once the token is passed into the MCP GraphQL tools (#631630 (closed)), tools return no data.

For example, the root namespace(fullPath:) field returns Namespace, which has no directive. That breaks get_work_item_types, get_saved_view, list_work_items and get_saved_view_work_items.

I found the affected types by loading every MCP query against the schema and listing each object type it reaches, instead of relying on config/authz/graphql/authorization_todo.txt.

Changes:

  1. Real directives (see the implementation guide):

    • Namespace: read_namespace at the project (via the project namespace's project), group (the group itself) and user boundaries. The read_namespace assignable permission gains the group boundary. It previously allowed only project and user.
    • WorkItemSavedViewType: a new read_work_item_saved_view permission at the project and group boundaries, via the saved view's project or group. It is its own assignable permission (Work item saved view: Read), next to the existing create, update, delete and subscribe permissions. This covers Namespace.savedViews, the saved view mutation payloads and the subscription, so a mutation token also needs this permission to get savedView back in the payload. read_saved_view can't be used because merge request dashboard saved views share it, and it is only assignable at the user boundary.

  2. skip_reason: :parent_authorizes on child and value types that are only reachable through an authorized parent: the nine WorkItemWidgetDefinition* types, CustomField, CustomFieldSelectOption and the four WorkItem*FieldValue types. Their lines are removed from authorization_todo.txt.

  3. Field-level directives on fields that return skipped types directly from a container or the root query, so a token holding only read_project, read_group, read_namespace or read_organization cannot read them. Each directive names the ability the returned type authorizes with:

    • read_work_item_type on Project.workItemTypes, Group.workItemTypes, Namespace.workItemTypes and Organization.workItemTypes. The Project, Group and Organization directives came from !251840 (merged) with read_work_item.
    • read_custom_field on Namespace.customFields, Group.customFields, Group.customField and Query.customField. The last two take the boundary from the custom field's namespace, so a token scoped to one group cannot read another group's field by ID.
    • read_work_item on Namespace.statuses at the project and group boundaries. !251840 (merged) added the group boundary only.
    • read_work_item_saved_view on Subscription.workItemSavedViewUpdated, with the boundary from the saved view's project or group.

    read_work_item_type and read_custom_field are new raw permissions in the existing Work item: Read assignable permission, so tokens with that permission keep access.

  4. Specs: request specs for every directive and boundary, using the shared examples 'authorizing granular token permissions for GraphQL' and '... with a skipped child type'. A new shared example, 'denying a granular token that only authorizes the parent of a field', checks that a token with only the parent permission gets the parent but not the gated field. The existing shared example's negative case removes every scope, so it cannot show that.

Organization.workItemTypes uses the user boundary, because the instance boundary for Work item: Read is admin only. A token with user-level Work item: Read can list the organization's work item types. That is configuration metadata the user can already read, and there is no single group or project to scope to.

Behavior for legacy PATs is unchanged. Granular checks only run for fine-grained tokens (or namespaces that enforce them).

Overlap with other MRs

!251840 (merged) merged first. It added the WorkItemType and WorkItemStatus skips and the directives on Project.workItemTypes, Group.workItemTypes, Organization.workItemTypes, Namespace.statuses and Query.workItemAllowedStatuses. This MR switches the workItemTypes directives to read_work_item_type, adds the project boundary to Namespace.statuses, and updates its spec that asserted Namespace has no directive.

The note, diff, repository tree, wiki and AccessLevel changes were split out into !265425 (merged) to make review easier. The two MRs are independent.

Out of scope

The EE Duo types are covered by !261877 (merged), which has merged. The SecurityScanProfileAttach and vulnerabilitiesSeverityOverride mutations take arrays of IDs, which the boundary extractor can't resolve yet, so they will be handled separately. PendingProjectMember and PendingGroupMember are not reachable from MCP queries, because MemberInterface only resolves to ProjectMember and GroupMember.

References

Screenshots or screen recordings

Not applicable, this MR only changes the backend.

How to set up and validate locally

  1. Create a fine-grained personal access token in the UI (User settings > Personal access tokens > Fine-grained) for a project, with the Namespace: Read and Work item: Read permissions.

  2. Run this query against /api/graphql with the token, for example with curl:

    query { namespace(fullPath: "flightjs/Flight") { id workItemTypes { nodes { name widgetDefinitions { type } } } } }

    On master the response has "namespace": null. With this MR it returns the work item types.

  3. Remove the Work item permission from the token and run the query again. namespace is returned, but workItemTypes is null.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

🤖 Generated with Claude Code

Edited by Alex Buijs

Merge request reports