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 5-PR stack across 3 repos. Merge order: scaleapi/scaleapi#144783 (sgp-authz 0.7.1) ✅ already merged → scaleapi/scaleapi#145000 + scaleapi/scaleapi#145044 + 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/scaleapi	scaleapi/scaleapi#145044	add cancel to SGP's AgentexOperation enum + role map
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 wire dependency

The execute → update swap changes the operation literal that hits agentex-auth's check endpoint. The SGP gateway forwards the literal verbatim, so the SGP permissions backend must resolve both update and cancel against the existing OWNER grant before this deploys:

• update is already in SGP's AgentexOperation enum on master — no work needed.
• cancel is added by scaleapi/scaleapi#145044. This PR is held until that PR ships everywhere.

For Spark-routed accounts the dependency chain is scaleapi/agentex#353 + sgp-authz 0.7.1 (already merged) → ResourceRole.OWNER → Action.CANCEL, all of which are in place upstream of this PR.

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 is the final piece of a four-PR FGAC stack: it rewires per-RPC task operations (MESSAGE_SEND/EVENT_SEND → update, TASK_CANCEL → cancel), extracts a shared check_task_or_collapse_to_404 helper that normalises all task-resource auth denials to 404, and hardens the case _: wildcard in _authorize_rpc_request from a silent pass to a NotImplementedError.

• src/utils/task_authorization.py (new): centralised 403→404 collapse for task resources, consumed by all auth shortcut factories and the RPC authoriser.
• authorization_shortcuts.py: DAuthorizedId, DAuthorizedQuery, DAuthorizedBodyId, and DAuthorizedName all route task-resource checks through the collapse helper; the name-route fix is security-relevant since task names are globally unique and a raw 403 leaks cross-tenant existence.
• agents.py: per-RPC operation literals tightened (update/cancel); the MESSAGE_SEND+task_name block restructured as try/except/else to prevent a denied-update from silently falling through to create-check (privilege escalation guard).

Confidence Score: 4/5

The logic is sound and well-tested, but deployment safety depends on a wire-contract check the author explicitly marks as a required pre-merge gate — confirming that the SGP/Spark schema resolves the new update and cancel operation literals against the owner grant that every in-flight agent currently holds.

The rewire from execute to update/cancel is the right call for the FGAC schema, and the try/else restructure correctly closes the denied-update-as-create privilege escalation hole. The collapse helper, dep-factory changes, and test suite are all clean. The one open item — confirming that update and cancel resolve against owner in the live SGP permissions backend before deploy — is called out by the author as a required pre-merge gate but has no recorded outcome in the PR. Every MESSAGE_SEND, EVENT_SEND, and TASK_CANCEL RPC for currently running agents would silently surface as 404 if the schema doesn't already include those operations.

agentex/src/api/routes/agents.py — specifically the execute→update/cancel operation swap and its interaction with the live SGP permissions schema.

Important Files Changed

Filename	Overview
agentex/src/utils/task_authorization.py	New helper that collapses any AuthorizationError on a task resource to ItemDoesNotExist (404); well-documented trade-off, TODO linked to AGX1-290.
agentex/src/api/routes/agents.py	Per-RPC operation literals rewired (execute→update/cancel); try/else restructure correctly prevents denied-update from falling through to create-check; NotImplementedError for unknown methods is intentional defense-in-depth. Wire-contract (execute→update/cancel resolves against existing owner grants) is the open pre-merge gate flagged by the author.
agentex/src/utils/authorization_shortcuts.py	All four dep factories consistently route task-resource checks through the collapse helper; DAuthorizedName now correctly prevents the name-probe cross-tenant leak.
agentex/src/api/routes/checkpoints.py	execute→update for put_checkpoint and put_writes; straightforward swap, matches messages.py pattern.
agentex/src/api/routes/messages.py	execute→update for all four message mutation endpoints; consistent with the FGAC schema intent (editor+owner can update).
agentex/src/api/schemas/authorization_types.py	Adds cancel to AuthorizedOperationType StrEnum; wire format pinned by test.
agentex/tests/unit/api/test_tasks_authz.py	Good coverage: per-RPC routing, 404 collapse, body-id and name-route wraps, wire-format enum pins, and the unwired-method fail-closed case.

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

[harvhan]

nit: make this typed