feat(AGX1-272): dual-write agent_api_keys to spark-authz behind FGAC flag

[dm36]

Summary

Wires register_resource / deregister_resource into AgentAPIKeysUseCase.create / delete so api_keys get a SpiceDB tuple (with parent_agent edge) on create and have that tuple removed on delete. Companion to the route-migration PR (#252).

scale-agentex is intentionally decoupled from egp-api-backend. The dual-write call is unconditional from this repo. agentex-auth's per-account routing (scaleapi/agentex#353, FGAC_AGENTEX_AUTH_SPARK) decides whether the call lands on Spark AuthZ or falls back to the legacy SGP backend for the caller's account.

Linear ticket: https://linear.app/scale-epd/issue/AGX1-272/fgac-agent-api-key-dual-write-registerderegister-on-createdelete

Cross-repo stack

#	Repo	PR	Purpose	State
1	scaleapi/scaleapi	#144657	sgp-authz 0.6.0 → 0.7.0; parent_resource kwarg	✅ Merged
2	scaleapi/agentex	#354	agentex-auth Port + Spark adapter + HTTP routes (/v1/authz/register, /v1/authz/deregister) + api_key mapping	✅ Merged
2b	scaleapi/agentex	#353	agentex-auth per-account routing via FGAC_AGENTEX_AUTH_SPARK flag	Open (this PR is decoupled from it — works whether #353 lands first or not)
3 (this PR)	scaleapi/scale-agentex	this	scale-agentex use case calling register_resource(parent=agent)	Ready
4	scaleapi/scale-agentex	#252	route-layer FGAC + 404 collapse + two-factor mutations	Stacked on this

Changes

Port + adapter

• src/adapters/authorization/port.py — abstract register_resource(resource, parent=None) and deregister_resource(resource) on AuthorizationGateway.
• src/adapters/authorization/adapter_agentex_authz_proxy.py — POST /v1/authz/register and /v1/authz/deregister to agentex-auth (endpoints exposed by #354).

Service layer

• src/domain/services/authorization_service.py — register_resource / deregister_resource service methods mirror the grant/revoke pattern (principal_context override, _bypass support, parent identity in log line).

Use case

• src/domain/use_cases/agent_api_keys_use_case.py:
  • create calls _register_api_key_in_auth unconditionally; parent=AgentexResource.agent(agent_id) is load-bearing for the SpiceDB cascade.
  • delete (and delete_by_* variants) call _deregister_api_key_from_auth after the Postgres row is gone.
  • Register fails closed (re-raises); deregister is best-effort (logs).
  • The "no creator resolvable" guard (internal-key path with no principal user/service identity) reads from principal_context at call time — no persisted creator columns.

Tests

• tests/integration/services/test_agent_api_key_service_dual_write.py — 6 cases. Mocks the authorization service; asserts the call sequencing inside the use case.
• tests/integration/fixtures/integration_client.py + tests/unit/use_cases/test_agents_api_keys_use_case.py updated for the new constructor signature.

Test plan

• 6 / 6 dual-write integration tests pass locally.
• Parent edge contract pinned: test_create_api_key_calls_register_resource_with_parent asserts parent=AgentexResource.agent(agent.id) is passed on every register call.
• Fail-closed on register failure preserved.
• Best-effort deregister preserved.
• No-creator-resolvable skip path preserved (runtime check, no persistence).
• 4 pre-existing docker-fixture errors in test_agents_api_keys_use_case.py predate this PR (verified via git stash).
• CI: ruff, ruff-format, alembic migration lint.
• End-to-end against a real SpiceDB once exercised in dev via the agentex-auth routing flip.

Diff scope

10 files changed, 55 insertions(+), 368 deletions(-) — net deletion. Earlier iterations had ~370 lines of OSS-coupling that Harvey's review pruned.

Out of scope / follow-ups

• ZedToken plumbing. If a SpiceDB consistency token use case emerges, expose it under a vendor-neutral column name (not spark_authz_zedtoken).
• Audit / backfill for legacy api_keys created before this PR. Tracked separately.
• Other resource types' grant → register_resource swap (task, build, deployment, schedule). Each owns its own follow-up.

Linked: AGX1-272.

Greptile Summary

This PR wires register_resource / deregister_resource into AgentAPIKeysUseCase.create and all three delete variants, so each agent_api_key gets a SpiceDB tuple with a parent_agent edge on create and has that tuple removed on delete. The dual-write is unconditional from scale-agentex; per-account routing (Spark vs legacy SGP) is handled by agentex-auth's FGAC_AGENTEX_AUTH_SPARK flag in the companion PR.

• Port + adapter: register_resource / deregister_resource added to AuthorizationGateway and implemented in AgentexAuthorizationProxy via POST to /v1/authz/register and /v1/authz/deregister, following the same payload pattern as the existing grant/revoke methods.
• Use-case semantics: Create is fail-closed (register before DB write; re-raises on failure) and skips when no creator identity is resolvable on principal_context. Delete (all three variants) is best-effort (deregister after DB delete; logs but does not re-raise on failure).
• Tests: Six new dual-write integration tests cover parent-edge contract, fail-closed register, best-effort deregister, no-creator skip, and delete_by_name; unit fixture updated to supply AsyncMock for both new methods.

Confidence Score: 5/5

Safe to merge; the dual-write is unconditional but correctly layered so that agentex-auth per-account routing controls whether Spark or the legacy backend is actually hit.

The create path is fail-closed (register before DB write, re-raises on failure), the delete paths are best-effort (swallow errors after the Postgres row is gone), and the no-creator-identity guard prevents writing ownerless SpiceDB tuples. Six dedicated integration tests exercise the key contracts and no logic errors were found.

No files require special attention.

Important Files Changed

Filename	Overview
agentex/src/domain/use_cases/agent_api_keys_use_case.py	Wires dual-write into create (fail-closed, before DB write, with parent-agent edge) and all three delete variants (best-effort, after DB delete); creator-identity guard correctly short-circuits when no user/service principal is resolvable.
agentex/src/domain/services/authorization_service.py	Adds register_resource and deregister_resource service methods with _bypass() guard, principal_context override pattern, and structured logging — mirrors the existing grant/revoke service methods faithfully.
agentex/src/adapters/authorization/adapter_agentex_authz_proxy.py	Implements register_resource and deregister_resource via POST to /v1/authz/register and /v1/authz/deregister; consistent with existing grant/revoke payload patterns including model_dump() for resource/parent.
agentex/src/api/schemas/authorization_types.py	Adds api_key to AgentexResourceType enum and corresponding factory methods; follows the exact same pattern as the existing task and agent types.
agentex/tests/integration/services/test_agent_api_key_service_dual_write.py	Six integration tests covering the core dual-write contracts: parent-edge on create, deregister on delete, fail-closed register, best-effort deregister, no-creator skip, and delete-by-name path.

Sequence Diagram

sequenceDiagram
    participant Route as API Route
    participant UC as AgentAPIKeysUseCase
    participant Auth as AuthorizationService
    participant GW as AgentexAuthorizationProxy
    participant DB as AgentAPIKeyRepository
    participant AX as agentex-auth

    Note over Route,AX: create path (fail-closed)
    Route->>UC: create(name, agent_id, api_key)
    UC->>Auth: check principal_context
    alt no creator identity
        UC-->>DB: skip auth, write row anyway
    else creator resolvable
        Auth->>GW: "register_resource(principal, api_key, parent=agent)"
        GW->>AX: POST /v1/authz/register
        alt register fails
            AX-->>UC: raises - DB row NOT written
        else register succeeds
            UC->>DB: create(AgentAPIKeyEntity)
        end
    end

    Note over Route,AX: delete path (best-effort)
    Route->>UC: delete(id)
    UC->>DB: get(id)
    alt ItemDoesNotExist
        UC-->>Route: no-op
    else row exists
        UC->>DB: delete(id)
        UC->>Auth: deregister_resource(api_key)
        Auth->>GW: deregister_resource(principal, api_key)
        GW->>AX: POST /v1/authz/deregister
        alt deregister fails
            UC->>UC: log warning, swallow
        end
    end

Loading

Comments Outside Diff (1)

1. agentex/tests/integration/services/test_agent_api_key_service_dual_write.py, line 703-727 (link)

   Missing test for grant-succeeds-but-DB-create-fails (orphan Spark tuple)

   The suite covers grant failure preventing the DB write, but not the reverse: grant succeeding followed by repo.create raising (e.g., a duplicate key or transient DB error). In that case a Spark tuple exists for an api_key_id that never lands in Postgres. Adding a test for this case would make the documented known-limitation explicit and guard against accidental regression if compensating logic is added later.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: agentex/tests/integration/services/test_agent_api_key_service_dual_write.py
   Line: 703-727
   
   Comment:
   **Missing test for grant-succeeds-but-DB-create-fails (orphan Spark tuple)**
   
   The suite covers `grant` failure preventing the DB write, but not the reverse: `grant` succeeding followed by `repo.create` raising (e.g., a duplicate key or transient DB error). In that case a Spark tuple exists for an `api_key_id` that never lands in Postgres. Adding a test for this case would make the documented known-limitation explicit and guard against accidental regression if compensating logic is added later.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

_{Reviews (8): Last reviewed commit: "refactor(AGX1-272): early-return on dele..." | Re-trigger Greptile}

[harvhan]

Should we follow the egp-api-backend's pattern and add compensating deregister if repo.create fails?

[dm36]

followed asher's approach here with tasks with not compensating deregister if repo.create fails for consistency- i can update tho