feat(AGX1-244): enforce parent-agent authz on event routes

[dm36]

Linear

AGX1-244

Summary

Enforces SpiceDB authorization on the event routes. Per the ticket, events are view-only, are not a SpiceDB resource (no schema, no dual-write), and delegate authorization to the parent agent (not the parent task — that's the structural difference from the sibling messages PR #255).

Permission model:

• GET /events/{event_id} -> agent.read on the parent agent
• GET /events?task_id=...&agent_id=... -> task.read + agent.read (existing on this endpoint; unchanged here)

Changes

• authorization_types.py: split event out of TaskChildResourceType (where it was misplaced) and introduce a new AgentChildResourceType enum containing event. State stays under TaskChildResourceType.
• authorization_shortcuts.py:
  • Add _get_parent_agent_id(...) mirroring _get_parent_task_id(...). Resolves event_id -> agent_id via the event repository (the EventEntity carries agent_id directly, so no two-hop event -> task -> agent).
  • DAuthorizedId / DAuthorizedQuery now branch on AgentChildResourceType and check AgentexResource.agent(...).
  • Both child-resource branches now collapse AuthorizationError -> ItemDoesNotExist (404) so a denied check is indistinguishable from a non-existent resource (no 403/404 oracle for cross-tenant probing). This is the same shape Harvey introduced in feat(AGX1-277): enforce parent-task authz on GET /messages/{message_id} #255 for TaskChildResourceType.
  • _get_parent_task_id signature simplified: it no longer takes event_repository since events are no longer task-children.
• routes/events.py: GET /events/{event_id} now uses DAuthorizedId(AgentChildResourceType.event, read). The list endpoint was already authz-protected per query param and is unchanged.
• Tests: new tests/integration/api/events/test_events_authz_api.py mirroring Harvey's test_messages_authz_api.py:
  • Authorized GET /events/{event_id} -> 200; asserts exactly one /v1/authz/check on agent (not task) with operation read.
  • Denied GET -> 404 (no-leak guarantee).
  • Nonexistent event_id -> 404, with explicit assertion that no /v1/authz/check fires (404 came from the repo, not from a denied check).
  • Authorized list -> 200; asserts two checks, one on task and one on agent, both read.

Behavior change beyond the ticket

The ticket calls for permissioning on get / list. The list endpoint already had per-query-param authz on task_id and agent_id — left as-is. The event -> task mapping that lived in TaskChildResourceType was an existing miswiring (events would have inherited from the task, not the agent); this PR corrects it as part of the deliverable.

Out of scope

• No SpiceDB schema for event (ticket: events are not a SpiceDB resource).
• No register_resource / dual-write for events.
• agent_identity bypass via AuthorizationService._bypass() is unchanged — agent-API-key callers still bypass per the AGX1-305 carve-out.

Coordination

• feat(AGX1-277): enforce parent-task authz on GET /messages/{message_id} #255 (harvhan/AGX1-277) — sibling PR, touches the same authorization_shortcuts.py (adds message to TaskChildResourceType, introduces the 404-collapse pattern). This PR independently re-implements that 404-collapse for both the task-child and the new agent-child paths. A textual conflict in authorization_shortcuts.py is expected on whichever of these merges second; resolution is mechanical (merge the registries and keep both isinstance branches).
• feat(AGX1-275): per-RPC task permission rewire and 404/403 wrap #249 — same expected conflict surface as feat(AGX1-277): enforce parent-task authz on GET /messages/{message_id} #255 calls out.
• Depends on the parent agent being registered as a Spark resource for the upstream cascade (AGX1-235 / AGX1-242). Route-layer enforcement here is correct regardless; if the agent isn't registered yet, that's a data-layer concern, not a bug in this PR.

Note on ticket wording

The ticket says "view permission on the parent agent." The wire-level operation in AuthorizedOperationType is read (which is what the agentex_agent SpiceDB schema calls it). "View" in the ticket maps to read here, matching how state / checkpoint / message authz is wired.

Test plan

• Static: imports resolve, pytest collects all 33 tests in the touched directories with no errors.
• uv run pytest agentex/tests/integration/api/events/ -q — not run locally (Docker daemon unavailable in this sandbox; testcontainers can't start Postgres). Will validate in CI.
• Regression: uv run pytest agentex/tests/integration/api/messages/ and .../states/ — same, deferred to CI.

Greptile Summary

Enforces SpiceDB authorization on GET /events/{event_id} by delegating to the parent agent (agent.read) rather than the parent task, correcting a pre-existing misclassification of events under TaskChildResourceType. The list endpoint's existing per-query-param checks are left unchanged.

• TaskChildResourceType.event is removed; events are now authorized via a new standalone helper check_agent_or_collapse_to_404 that collapses AuthorizationError to 404 to prevent cross-tenant existence probing.
• authorization_shortcuts.py gains the same 404-collapse for the TaskChildResourceType branch in both DAuthorizedId and DAuthorizedQuery, and drops the now-unnecessary event_repository parameter from _get_parent_task_id.
• A new integration test suite (test_events_authz_api.py) covers authorized GET (asserts exactly one agent.read check), denied GET (404), nonexistent event (404 with no authz call), authorized list (two checks), and denied-agent list (403).

Confidence Score: 5/5

Safe to merge; the authz logic is straightforward, the no-leak guarantee is preserved, and the new tests cover all four meaningful cases.

The route correctly fetches the event before checking authorization (necessary to resolve agent_id), both denial paths collapse to 404, and the test suite explicitly verifies the no-authz-call-on-404 invariant. The only finding is a missing type annotation on the authorization parameter in the new helper.

No files require special attention beyond the minor typing gap in agent_authorization.py.

Important Files Changed

Filename	Overview
agentex/src/utils/agent_authorization.py	New helper that checks agent authorization and collapses AuthorizationError to 404; correctly mirrors the task equivalent, but the authorization parameter is untyped.
agentex/src/api/routes/events.py	Switches GET /events/{event_id} from DAuthorizedId(TaskChildResourceType.event) to a two-step fetch-then-check pattern; the list endpoint is unchanged.
agentex/src/api/schemas/authorization_types.py	Removes misplaced event value from TaskChildResourceType; only state remains.
agentex/src/utils/authorization_shortcuts.py	Removes event_repository from _get_parent_task_id and adds AuthorizationError→ItemDoesNotExist collapse to both DAuthorizedId and DAuthorizedQuery for TaskChildResourceType; the else (direct resource) branch is intentionally left as 403.
agentex/tests/integration/api/events/test_events_authz_api.py	New integration test suite covering authorized GET, denied GET (404), nonexistent event (404 with no authz call), authorized list (two checks), and denied-agent list (403); all assertions match the actual implementation behavior.

Sequence Diagram

sequenceDiagram
    participant Client
    participant EventsRoute
    participant EventUseCase
    participant DB as Event DB
    participant AuthzHelper as check_agent_or_collapse_to_404
    participant SpiceDB

    Client->>EventsRoute: "GET /events/{event_id}"
    EventsRoute->>EventUseCase: get(event_id)
    EventUseCase->>DB: "SELECT WHERE id=event_id"
    alt event not found
        DB-->>EventUseCase: not found
        EventUseCase-->>EventsRoute: ItemDoesNotExist
        EventsRoute-->>Client: 404
    else event found
        DB-->>EventUseCase: EventEntity (carries agent_id)
        EventUseCase-->>EventsRoute: EventEntity
        EventsRoute->>AuthzHelper: check_agent_or_collapse_to_404(auth, agent_id, read)
        AuthzHelper->>SpiceDB: "POST /v1/authz/check {type:agent, selector:agent_id, op:read}"
        alt denied
            SpiceDB-->>AuthzHelper: AuthorizationError
            AuthzHelper-->>EventsRoute: ItemDoesNotExist (collapsed)
            EventsRoute-->>Client: 404
        else allowed
            SpiceDB-->>AuthzHelper: allowed
            AuthzHelper-->>EventsRoute: ok
            EventsRoute-->>Client: 200 Event
        end
    end

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
agentex/src/utils/agent_authorization.py:9-13
Missing type annotation on the `authorization` parameter. Every other helper in this module hierarchy (e.g. `authorization_shortcuts.py`) types the service as `DAuthorizationService` when receiving it as a dependency, or `AuthorizationService` when the resolved object is passed directly. Here the resolved `AuthorizationService` instance is passed in, so the parameter type should be `AuthorizationService`. Without it, static type checkers get no help and `authorization.check(...)` is unchecked.

```suggestion
async def check_agent_or_collapse_to_404(
    authorization: "AuthorizationService",
    agent_id: str,
    operation: AuthorizedOperationType,
) -> None:
```

_{Reviews (5): Last reviewed commit: "refactor(AGX1-244): re-add task-child 40..." | Re-trigger Greptile}

[asherfink]

need to be consistent here w/ my PR (#249) and @harvhan's (#255)

i think the version here is error-prone. in this case, this else is the path every direct-resource DAuthorizedId takes, not just events. Wrapping it in except AuthorizationError -> ItemDoesNotExist flips 403 to 404 for every direct-resource route in the service

#249 keeps else as 403 and only collapses to 404 for tasks/task-children (elif resource_type == AgentexResourceType.task). #255 leaves else as 403 too.

[harvhan]

+1

[asherfink]

simillar comment as above

[asherfink]

looks good overall but want to clarify the comment / make consistent with other PRs here before stamping!

[harvhan]

+1