feat(AGX1-275): per-RPC task permission rewire and 404/403 wrap

[asherfink]

Related work

Parent epic: AGX1-264 — per-task FGAC. Follow-ups bundled in AGX1-291.

This change is part of a 4-PR stack across 3 repos. Merge order: scaleapi/scaleapi#144783 (release sgp-authz 0.7.1) ✅ already merged → scaleapi/scaleapi#145000 → scaleapi/agentex#353 → #246 → this PR.

Repo	PR	Purpose
scaleapi/scaleapi	scaleapi/scaleapi#144783 ✅ merged	sgp-authz 0.7.1 — Action.CANCEL
scaleapi/scaleapi	scaleapi/scaleapi#145000	register FGAC_AGENTEX_AUTH_SPARK flag
scaleapi/agentex	scaleapi/agentex#353	agentex-auth per-account routing + cancel op
scaleapi/scale-agentex	#246	task creator audit columns + FGAC dual-write + flag
scaleapi/scale-agentex	this PR	per-RPC operation rewire + 404/403 wrap

Last in the stack — this is the route-side change that actually exercises the permissions written by #246.

Summary

• Routes each task-resource RPC to the correct AuthorizedOperationType instead of using execute everywhere: MESSAGE_SEND / EVENT_SEND → update, TASK_CANCEL → cancel, TASK_CREATE stays create.
• Broadens the execute → update swap across messages.py, checkpoints.py, and states.py so the editor role can send messages and update checkpoints/state without needing owner. The task SpiceDB schema defines permission update = (editor + owner) & internal_tenant_gate, so leaving these on execute (owner-only) would lock editors out of routine mutations.
• Collapses every task-resource denial into 404 (via ItemDoesNotExist) across all surfaces — path id, query id, body id, and name routes — so callers can no longer distinguish "task present in another tenant" from "task absent" by comparing 403 vs 404.
• Extracts the collapse helper to src/utils/task_authorization.py, reused from both the FastAPI dep factories and the RPC authorize hook.
• Unknown AgentRPCMethod values now raise NotImplementedError rather than falling through authz-free — defense-in-depth so a new RPC must be explicitly wired before it can dispatch.

What changed

• src/utils/task_authorization.py (new): check_task_or_collapse_to_404(authorization, task_id, operation) — the shared wrap.
• src/utils/authorization_shortcuts.py: DAuthorizedId / DAuthorizedQuery / DAuthorizedBodyId route task checks through the wrap; their inner deps no longer take a task_repository (parameter was unused). DAuthorizedName now applies the wrap when resource_type == AgentexResourceType.task — previously the name surface leaked 403 vs 404 because tasks.name is globally unique, so a probe checked the whole system rather than a single tenant.
• src/api/routes/agents.py _authorize_rpc_request: each task-resource branch routes through the wrap. The MESSAGE_SEND block with task_name is restructured to a try/else shape so a denied-update on an existing task surfaces as 404 (it must NOT fall through to the create-fallback except — that would silently promote a denied-update into a create check, which is a privilege escalation footgun). The unknown-method case (case _:) now raises NotImplementedError.
• src/api/routes/messages.py / checkpoints.py / states.py: execute → update for routine mutations.
• TASK_CREATE and the wildcard task("*") checks intentionally untouched.

AGX1-275 list deliverable — already covered

The AGX1-275 list-filtering deliverable (only return tasks the caller can read) is already met by existing infrastructure that this PR does not change:

• DAuthorizedResourceIds(AgentexResourceType.task) at src/utils/authorization_shortcuts.py:130 resolves the per-principal accessible task id set.
• It is wired into the list route at src/api/routes/tasks.py:82, which intersects user filters with the accessible set before hitting the repository.

No additional code is needed here — the list surface is already authorized end-to-end.

Pre-merge verification

The execute → update swap changes the operation literal that hits agentex-auth's check endpoint. The SGP gateway forwards the literal verbatim — this needs confirmation that the SGP permissions backend resolves update (and cancel) against the same owner row everyone hitting these routes today already has. Otherwise every running agent's RPCs break at deploy time.

Two acceptable forms before merge:

• Direct: read the SGP permissions schema and document file + line here.
• Indirect: one-off integration test against the real SGP adapter that issues a task update check on an account whose only grant is owner. The wire-contract test already pins the literal; this would pin the resolution.

If SGP's task permission map doesn't include update / cancel, this PR needs to either land behind a flag (keep execute for SGP-routed accounts) or backfill the schema first.

Tests

• tests/unit/api/test_tasks_authz.py — 17 tests pass:
  • 8 TestPerRpcOperationRouting tests (incl. MESSAGE_SEND create-fallback preserved through the restructure).
  • 2 TestCheckTaskOrCollapseTo404 tests (allow + denied-collapses-to-404).
  • 3 TestDAuthorizedBodyIdTaskWrap tests.
  • 3 TestDAuthorizedNameTaskWrap tests (denied-task → 404, allow returns name, agent path unaffected).
  • Wire-contract test pins cancel → "cancel" (mirrors agentex-auth's).
• Ruff + ruff-format clean (pre-commit hooks).

Out of scope / follow-ups (tracked in AGX1-291)

• /agents/name/{agent_name} has the same leak shape — agent FGAC is outside AGX1-264.
• Restoring the 403/404 split for same-tenant calls once tasks carry tenant/account_id scope at the data layer (AGX1-290).

Greptile Summary

This PR completes the per-task FGAC rewire for scale-agentex: it routes each task RPC to the correct AuthorizedOperationType (update for MESSAGE_SEND/EVENT_SEND, cancel for TASK_CANCEL), collapses all auth denials on task resources to 404 via a shared check_task_or_collapse_to_404 helper, and adds a NotImplementedError failsafe for unrecognized RPC methods.

• task_authorization.py (new): check_task_or_collapse_to_404 centralises the deny-to-404 collapse across all task-resource surfaces (DAuthorizedId, DAuthorizedQuery, DAuthorizedBodyId, DAuthorizedName, and the RPC authorize hook); the docstring explains the UX trade-off and links the follow-up ticket.
• agents.py: MESSAGE_SEND with task_name is restructured to a try/else shape so a denied update on an existing task surfaces as 404 and cannot fall through to the create-permission check — preventing a privilege-escalation path.
• messages.py / checkpoints.py: execute → update so holders of the editor role can send messages and update checkpoints without owner.

Confidence Score: 4/5

The auth logic changes are internally consistent and well-tested, but the operation-literal switch from execute to update/cancel is only safe to deploy if SGP's task permission schema already grants those operations to the owner role that all in-flight agents hold today — this has not been documented in the PR.

The execute → update/cancel rewire changes what literal the SGP gateway forwards to the permissions backend on every MESSAGE_SEND, EVENT_SEND, and TASK_CANCEL call. If the SGP task schema does not map update and cancel to the owner grant, every active agent's RPCs will silently collapse to 404 at deploy time. The PR description identifies this as a required pre-merge gate but does not record verification of either the schema-doc reference or the one-off integration test it asks for.

agentex/src/api/routes/agents.py — the per-RPC operation routing is the most deployment-sensitive change; the wire contract between the new update/cancel literals and the SGP permissions schema needs to be confirmed before merge.

Important Files Changed

Filename	Overview
agentex/src/utils/task_authorization.py	New helper: collapses AuthorizationError → ItemDoesNotExist (404) for all task-resource checks; well-documented with rationale and follow-up ticket reference.
agentex/src/api/routes/agents.py	Per-RPC operation routing rewired (execute → update/cancel); try/else shape for MESSAGE_SEND+task_name correctly blocks denied-update from falling through to create check; case _: now raises NotImplementedError instead of silently passing.
agentex/src/utils/authorization_shortcuts.py	DAuthorizedId/Query/BodyId/Name all route task-resource checks through the collapse wrap; elif branch for AgentexResourceType.task is correctly placed; DTaskRepository import retained for DAuthorizedName's registry.
agentex/src/api/routes/messages.py	execute → update for all four message mutation endpoints; straightforward change.
agentex/src/api/routes/checkpoints.py	execute → update for put_checkpoint and put_writes; import block reordering (alphabetical) is the only other change.
agentex/src/api/schemas/authorization_types.py	Adds cancel to AuthorizedOperationType StrEnum; wire-contract test locks the literal value "cancel".
agentex/tests/unit/api/test_tasks_authz.py	17 new unit tests covering per-RPC routing, 404-collapse, DAuthorizedBodyId/DAuthorizedName task-wrapping, wire-format contract; try/else create-fallback path is explicitly tested.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[RPC Request] --> B{AgentRPCMethod?}
    B -->|TASK_CREATE| C[check task/* create]
    B -->|MESSAGE_SEND / EVENT_SEND| D{task_id or task_name?}
    B -->|TASK_CANCEL| E{task_id or task_name?}
    B -->|unknown| F[raise NotImplementedError → 500]

    D -->|task_id| G[check_task_or_collapse_to_404\noperation=update]
    D -->|task_name — try get_task| H{task exists?}
    H -->|ItemDoesNotExist| I[check task/* create]
    H -->|exists — else branch| J[check_task_or_collapse_to_404\noperation=update]

    E -->|task_id| K[check_task_or_collapse_to_404\noperation=cancel]
    E -->|task_name| L[get_task then\ncheck_task_or_collapse_to_404\noperation=cancel]

    G --> M{AuthorizationError?}
    J --> M
    K --> M
    L --> M
    M -->|yes| N[raise ItemDoesNotExist → 404]
    M -->|no| O[dispatch RPC]

Loading

_{Reviews (2): Last reviewed commit: "feat(AGX1-275): per-RPC task permission ..." | Re-trigger Greptile}