feat(resolve): add opt-in pre-fetch field authorization mode

[jensneuse]

What

Adds an opt-in mode that authorizes fields protected by @requiresScopes / @authenticated in a single up-front batch, before any subgraph fetch, instead of filtering them out of the response after the fetch.

Motivation (Monday.com, migrating Apollo Router → Cosmo Router): today these directives are enforced post-fetch while walking returned data, which means (1) unauthorized selections still trigger subgraph fetches, and (2) when a protected field resolves to an empty list / no objects, no UNAUTHORIZED_FIELD_OR_TYPE error is emitted. This mode matches Apollo-style pre-execution behavior.

Refs ENG-9828. The Cosmo Router wiring lands in a follow-up PR referencing these primitives.

How

• New BatchAuthorizer interface + AuthorizationDecision (explicit allow/deny value type), separate from Authorizer (non-breaking).
• Context.SetPreFetchFieldAuthorizer(BatchAuthorizer) — presence enables the mode (no boolean flag).
• Plan-time coordinate collection via Plan.CollectAuthorizationCoordinates() (stored on GraphQLResponseInfo; no-op when the operation selects no protected fields).
• One batch call in ResolveGraphQLResponse (and subscription paths) seeds the resolvable decision cache; the loader and resolvable become pure readers. Enforcement stays per-operation-type: queries prune (partial allowed), mutations & subscriptions whole-fetch reject.
• Empty/null-parent emission pass closes the no-error-on-empty-list gap for all operation types.
• Authorization code extracted into resolvable_authorization.go (100% unit-test coverage).

Backward compatibility

Default off — with no preFetchFieldAuthorizer set, behavior is byte-for-byte unchanged. No existing test or golden file was modified.

Testing

• Full v2 suite green, -race green, golangci-lint (v2.10.1) clean, gofmt/vet clean.
• New focused tests for the mode (query prune, partial siblings, nested empty-list index-less path, batch-called-once, interface/runtime-typename, nullable & non-null mutation → single error) plus 100%-coverage unit tests for the extracted authorization functions.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2a45a456-c48b-4d22-810c-baf34a2c1589

📥 Commits

Reviewing files that changed from the base of the PR and between fa89c63 and 66ef719.

📒 Files selected for processing (1)

• v2/pkg/engine/resolve/resolvable.go

🚧 Files skipped from review as they are similar to previous changes (1)

• v2/pkg/engine/resolve/resolvable.go

---

📝 Walkthrough

Walkthrough

Adds opt-in pre-fetch field authorization across plan processing, resolver execution, and loader fetch decisions. It also collects protected field coordinates during postprocessing, emits authorization errors for unreached data, and expands test coverage for the new flow.

Changes

Pre-fetch field authorization

Layer / File(s)	Summary
BatchAuthorizer contract and Context wiring v2/pkg/engine/resolve/context.go	Adds AuthorizationDecision, BatchAuthorizer, preFetchFieldAuthorizer, SetPreFetchFieldAuthorizer, and clears the field on Free.
Plan-time authorization coordinate collection v2/pkg/engine/resolve/response.go, v2/pkg/engine/postprocess/collect_authorization_coordinates*.go, v2/pkg/engine/postprocess/postprocess.go, v2/pkg/engine/datasourcetesting/datasourcetesting.go, v2/pkg/engine/datasource/graphql_datasource/graphql_datasource_federation_test.go	Adds GraphQLResponseInfo.AuthorizationCoordinates/AuthorizationCoordinate, the collection processor and disable option, wiring into processor execution, and updated federation/default-processor expectations.
FieldAuthorization decision cache v2/pkg/engine/resolve/field_authorization.go	Adds FieldAuthorization with pre-fetch seeding, cached decisions, and decision-id helpers.
Resolver pre-fetch authorization batching v2/pkg/engine/resolve/resolve.go	Wires pre-fetch authorization through response, defer, arena, and subscription execution paths, including subscription pre-checks and update handling.
Loader fetch enforcement from cache v2/pkg/engine/resolve/loader.go	Adds cached authorization-based fetch skipping for pre-fetch mode.
Resolvable authorization decisions and unreached-field errors v2/pkg/engine/resolve/resolvable.go	Switches to per-request authorization state, adds unreached-data traversal, and emits authorization errors for synthetic null/empty paths.
Prefetch authorization tests v2/pkg/engine/resolve/authorization_prefetch_test.go, v2/pkg/engine/postprocess/collect_authorization_coordinates_test.go	Adds tests for coordinate collection, batch prefetch authorization, loader skipping, subscription authorization, and null-propagation behavior.
Resolvable authorization tests v2/pkg/engine/resolve/resolvable_authorization_test.go	Adds tests for field authorization, decision caching, unreached-data emission, end-to-end resolution, and helper behavior.

Estimated code review effort: 4 (Complex) | ~75 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: an opt-in pre-fetch field authorization mode in resolve.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the opt-in pre-fetch authorization work.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ENG-9828-router-add-pre-fetch-scope-authorization

---

_{Comment @coderabbitai help to get the list of available commands.}

[jensneuse]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

v2/pkg/engine/resolve/context.go (1)

195-204: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Carry the contract invariants from PLAN.md into the GoDoc.

PLAN.md §3.2 specifies important invariants for this new public interface — decisions must be index-aligned with coordinates, contain exactly one entry per coordinate, and be a pure function of (coordinate, request scopes) with no subgraph input/data — but none of that made it into the shipped comments. Since BatchAuthorizer is meant to be implemented by external code (e.g. a future router CosmoAuthorizer), documenting these constraints directly on the interface/struct reduces the risk of a misaligned or impure implementation causing silent authorization mismatches.

📝 Proposed doc enrichment

-// AuthorizationDecision is an explicit allow/deny decision for a single field coordinate.
+// AuthorizationDecision is an explicit allow/deny decision for a single field coordinate.
 type AuthorizationDecision struct {
-	Allowed bool
-	Reason  string
+	// Allowed reports whether the coordinate is authorized for the request.
+	Allowed bool
+	// Reason optionally explains a denial. Only meaningful when Allowed is false.
+	Reason string
 }

-// BatchAuthorizer authorizes field coordinates in one call before execution.
+// BatchAuthorizer authorizes a set of field coordinates in a single call, before execution.
+// decisions must be index-aligned with coordinates and contain exactly one decision per
+// coordinate. Decisions must be a pure function of the coordinate and the request context
+// (e.g. token scopes); no subgraph input or response data is provided, by design.
 type BatchAuthorizer interface {
 	AuthorizeFields(ctx *Context, coordinates []GraphCoordinate) (decisions []AuthorizationDecision, err error)
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@v2/pkg/engine/resolve/context.go` around lines 195 - 204, Update the GoDoc on
AuthorizationDecision and BatchAuthorizer to include the PLAN.md §3.2 contract
invariants: AuthorizeFields must return exactly one decision per input
coordinate, in the same order/index alignment as coordinates, and each decision
must be derived only from the coordinate and request scopes with no subgraph
input or execution data. Add this guidance directly on the AuthorizationDecision
struct and BatchAuthorizer.AuthorizeFields method so external implementers like
CosmoAuthorizer can follow the required behavior.

v2/pkg/engine/plan/plan.go (1)

14-22: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider an optional interface instead of extending the public Plan interface.

Adding CollectAuthorizationCoordinates() to Plan forces every external implementer of this exported interface to add the method, which is a breaking API change for library consumers with custom Plan implementations. A type-assertion at the single call site in planner.go (if c, ok := plan.(interface{ CollectAuthorizationCoordinates() }); ok { c.CollectAuthorizationCoordinates() }) would achieve the same behavior without widening the required interface surface.

♻️ Optional interface pattern

 type Plan interface {
 	PlanKind() Kind
 	SetFlushInterval(interval int64)
 	GetCostCalculator() *CostCalculator
 	SetCostCalculator(calc *CostCalculator)
-	// CollectAuthorizationCoordinates populates the plan's response with the field coordinates that
-	// require an authorization decision, so pre-fetch field authorization can resolve them up front.
-	CollectAuthorizationCoordinates()
 }
+
+// authorizationCoordinateCollector is implemented by plans that can populate
+// pre-fetch authorization coordinates.
+type authorizationCoordinateCollector interface {
+	CollectAuthorizationCoordinates()
+}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@v2/pkg/engine/plan/plan.go` around lines 14 - 22, Remove
CollectAuthorizationCoordinates() from the exported Plan interface and switch
the planner call site to an optional interface type assertion. Keep the behavior
in planner.go by checking whether the concrete plan implements a local interface
with CollectAuthorizationCoordinates() before invoking it, so existing external
Plan implementations are not forced to change. Use the Plan interface and the
planner.go call site as the main symbols to update.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@v2/pkg/engine/resolve/authorization.go`:
- Around line 66-82: The coordinate collection in
collectNodeAuthorizationCoordinates only seeds authorization for the first
source in field.Info.Source.IDs, so merged protected fields with multiple
resolving sources are missed. Update the Object branch to iterate over every ID
in field.Info.Source.IDs and call addAuthorizationCoordinate for each one, while
keeping the existing GraphCoordinate built from field.Info.ExactParentTypeName
and field.Info.Name.

In `@v2/pkg/engine/resolve/resolvable_authorization.go`:
- Around line 81-83: The authorizationDecisionID helper builds cache keys by
concatenating dataSourceID, coordinate.TypeName, and coordinate.FieldName
without separators, which can make different coordinates hash the same input.
Update authorizationDecisionID to include unambiguous delimiters or another
structured encoding before calling xxhash.Sum64String, so each unique
GraphCoordinate/dataSourceID tuple maps to a distinct cache key.

In `@v2/pkg/engine/resolve/resolve.go`:
- Around line 416-420: Scope the inbound single-flight to the authorization
policy used by authorizeFieldsPreFetch in resolve.go, because GetOrCreate
currently dedupes only by request ID, variables hash, and header hash and
followers can reuse a response authorized under a different policy. Update the
keying or inflight selection in the resolve flow around
r.inboundRequestSingleFlight.GetOrCreate and the authorizeFieldsPreFetch call so
requests with different auth policies do not share the same inflight result.

---

Nitpick comments:
In `@v2/pkg/engine/plan/plan.go`:
- Around line 14-22: Remove CollectAuthorizationCoordinates() from the exported
Plan interface and switch the planner call site to an optional interface type
assertion. Keep the behavior in planner.go by checking whether the concrete plan
implements a local interface with CollectAuthorizationCoordinates() before
invoking it, so existing external Plan implementations are not forced to change.
Use the Plan interface and the planner.go call site as the main symbols to
update.

In `@v2/pkg/engine/resolve/context.go`:
- Around line 195-204: Update the GoDoc on AuthorizationDecision and
BatchAuthorizer to include the PLAN.md §3.2 contract invariants: AuthorizeFields
must return exactly one decision per input coordinate, in the same order/index
alignment as coordinates, and each decision must be derived only from the
coordinate and request scopes with no subgraph input or execution data. Add this
guidance directly on the AuthorizationDecision struct and
BatchAuthorizer.AuthorizeFields method so external implementers like
CosmoAuthorizer can follow the required behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a90344dc-91b5-4258-9109-133f460b334e

📥 Commits

Reviewing files that changed from the base of the PR and between def8796 and ee22d6b.

📒 Files selected for processing (13)

• PLAN.md
• v2/pkg/engine/datasourcetesting/datasourcetesting.go
• v2/pkg/engine/plan/plan.go
• v2/pkg/engine/plan/planner.go
• v2/pkg/engine/resolve/authorization.go
• v2/pkg/engine/resolve/authorization_prefetch_test.go
• v2/pkg/engine/resolve/context.go
• v2/pkg/engine/resolve/loader.go
• v2/pkg/engine/resolve/resolvable.go
• v2/pkg/engine/resolve/resolvable_authorization.go
• v2/pkg/engine/resolve/resolvable_authorization_test.go
• v2/pkg/engine/resolve/resolve.go
• v2/pkg/engine/resolve/response.go

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@v2/pkg/engine/resolve/resolve.go`:
- Around line 524-529: The subscription root authorization check in resolveField
currently treats any decision count other than exactly one as allowed, so update
the preFetchFieldAuthorizer.AuthorizeFields handling to fail closed when the
batch size is wrong. In the resolveField path, mirror the pre-fetch query
validation by checking that decisions has exactly one entry before inspecting
decisions[0].Allowed, and return an error if the authorizer returns zero or
multiple decisions instead of proceeding.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3d55b9f7-bef6-4ada-936b-68a7d765662b

📥 Commits

Reviewing files that changed from the base of the PR and between b36e296 and 3f9f28e.

📒 Files selected for processing (2)

• v2/pkg/engine/resolve/authorization_prefetch_test.go
• v2/pkg/engine/resolve/resolve.go

🚧 Files skipped from review as they are similar to previous changes (1)

• v2/pkg/engine/resolve/authorization_prefetch_test.go