feat(checkpoints): FGAC checkpoint routes, enforce via parent task pe…

[jenniechung]

Summary

Enforce Spark AuthZ on the checkpoint routes by delegating to the owning task. Checkpoints have no SpiceDB type of their own — thread_id is the owning task id (LangGraph checkpointer convention; the SDK templates set configurable.thread_id = task.id), so each route checks the parent task directly via DAuthorizedBodyId(task, …, field_name="thread_id"). No register_resource, no dual-write — the authz request only ever carries resource type task.

Operation mapping (matches the task SpiceDB schema):

Route	Operation	Task permission
get-tuple, list	read	viewer + editor + owner
put, put-writes	update	editor + owner
delete-thread	delete	owner

A denied task check collapses to 404 (not 403) so callers cannot probe cross-tenant existence by comparing response codes.

Switches put / put-writes from execute → update: execute maps to no task permission in the schema (it would lock everyone out), whereas task.update = (editor + owner) & internal_tenant_gate lets the editor role write checkpoints without owner.

Changes

• src/utils/authorization_shortcuts.py — DAuthorizedBodyId collapses a denied task check into 404 (AuthorizationError → ItemDoesNotExist); non-task resources keep surfacing 403. Carries a TODO to converge on the canonical check_task_or_collapse_to_404 helper from AGX1-275 / feat(tasks): per-RPC task permission rewire and 404/403 wrap #249.
• src/api/routes/checkpoints.py — put / put-writes: execute → update. (get-tuple / list already read; delete-thread already delete.)
• tests/integration/api/checkpoints/test_checkpoints_authz_api.py (new) — integration tests covering the auth matrix.

Behavior change beyond the ticket

The 404 collapse lives in DAuthorizedBodyId's task branch, so it also applies to the other body-id task routes (message POST/PUT, state create) — those now collapse a denied check to 404 as well. Same cross-tenant-leak rationale, and aligns with the canonical wrap landing in AGX1-275 (#249).

Out of scope

• The agent-API-key path (request.state.agent_identity) still bypasses authz via AuthorizationService._bypass() — same caveat as the message-route migration.
• A dedicated owner-level permission for checkpoint writes is a schema follow-up (AGX1-237); per feat(tasks): per-RPC task permission rewire and 404/403 wrap #249, routine mutations intentionally use task.update.

Coordination

AGX1-275 (#249) introduces the shared check_task_or_collapse_to_404 helper in src/utils/task_authorization.py and the same execute → update swap across checkpoints.py / messages.py / states.py. This PR's inline DAuthorizedBodyId task-wrap (flagged with a TODO) converges on that helper when the two land together — trivial merge regardless of order.

Pre-merge wire dependency: the execute → update swap changes the operation literal hitting agentex-auth. update is already in SGP's AgentexOperation enum on master, so no additional gating is needed for this PR.

Test Plan

• get-tuple — authorized 200 (task/read); denied 404
• list — authorized 200 (task/read); denied 404
• put — authorized 200 (task/update); denied 404
• put-writes — authorized 204 (task/update); denied 404
• delete-thread — authorized 204 (task/delete); denied 404
• Ruff lint + format clean across changed files.
• Regression: tests/integration/api/{messages,states}/, since the shared DAuthorizedBodyId task-wrap changes their write-route deny code from 403 → 404. Both suites pass; no regressions from the DAuthorizedBodyId task-wrap change.

Linear Issue

resolves https://linear.app/scale-epd/issue/AGX1-302, Parent: AGX1-299.

Greptile Summary

This PR enforces fine-grained access control on checkpoint routes by delegating authorization to the owning task (thread_id = task id), collapsing denied checks into 404 to prevent cross-tenant existence probing, and corrects put/put-writes from the broken execute operation to update.

• authorization_shortcuts.py: DAuthorizedBodyId gains a task-specific branch that catches AuthorizationError and re-raises as ItemDoesNotExist (→ 404), matching the existing pattern in DAuthorizedId and DAuthorizedQuery; a TODO links the planned refactor to AGX1-275.
• checkpoints.py: put and put-writes switch from execute → update, allowing editor + owner roles to write checkpoints without locking everyone out.
• test_checkpoints_authz_api.py: New integration test suite verifies authorized (200/204) and denied (404) outcomes for all five routes, including operation-literal assertions for the updated write endpoints.

Confidence Score: 5/5

Safe to merge — the changes are well-scoped, consistently mirror the existing DAuthorizedId/DAuthorizedQuery patterns, and all five checkpoint routes now have full authorized + denied test coverage.

The execute to update fix is a correctness improvement (execute had no mapping in the task SpiceDB schema, locking everyone out), the 404-collapse follows an established pattern already used in two other shortcuts, and the new integration tests validate operation literals and HTTP status codes on all routes including the previously uncovered put-writes and delete-thread denied paths.

No files require special attention.

Important Files Changed

Filename	Overview
agentex/src/utils/authorization_shortcuts.py	Adds 404-collapse for denied task checks in DAuthorizedBodyId, matching the existing pattern in DAuthorizedId and DAuthorizedQuery; non-task paths unchanged.
agentex/src/api/routes/checkpoints.py	Switches put and put-writes from execute to update operation, enabling editor-role writes; all five routes now carry explicit DAuthorizedBodyId(task) guards.
agentex/tests/integration/api/checkpoints/test_checkpoints_authz_api.py	New integration test suite covering authorized and denied paths for all five checkpoint routes; verifies operation literals, resource type, and 404-collapse behavior.

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into jenniechung/AGX..." | Re-trigger Greptile}