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 the three delete methods, so every agent_api_key gets a SpiceDB tuple (with a parent_agent edge) on creation and has it removed on deletion. The dual-write is unconditional in this repo; per-account routing to Spark AuthZ vs. the legacy SGP backend is delegated to agentex-auth.

• Port + adapter: AuthorizationGateway gains abstract register_resource / deregister_resource; AgentexAuthorizationProxy implements them via POST to /v1/authz/register and /v1/authz/deregister.
• Service layer: AuthorizationService.register_resource and deregister_resource mirror the existing grant/revoke pattern — _bypass() guard, principal_context override, structured log line.
• Use case: create calls _register_api_key_in_auth (fail-closed, before the Postgres write) with parent=AgentexResource.agent(agent_id). All three delete paths call _deregister_api_key_from_auth (best-effort, after the DB delete) using the entity ID retrieved by a pre-fetch. A no-creator guard skips registration when neither user_id nor service_account_id is resolvable on the principal.

Confidence Score: 5/5

Safe to merge. The dual-write is unconditional and well-guarded: register fails closed (Postgres row never written on Spark failure), deregister is best-effort (delete completes regardless), and the no-creator guard prevents registration without an owner identity.

The create path correctly sequences auth registration before the DB write and re-raises on failure. The delete paths pre-fetch the entity ID, complete the DB delete, then attempt deregistration with swallowed errors. Bypass semantics and principal-context plumbing are consistent with the existing grant/revoke pattern.

No files require special attention. The integration test file has a minor coverage gap for delete_by_agent_name_and_key_name, but the code itself is correct.

Important Files Changed

Filename	Overview
agentex/src/domain/use_cases/agent_api_keys_use_case.py	Adds _register_api_key_in_auth (fail-closed, pre-DB) and _deregister_api_key_from_auth (best-effort, post-DB) helpers; all three delete methods updated to pre-fetch the entity ID and call deregister. Logic is sound; no blocking issues.
agentex/src/domain/services/authorization_service.py	Adds register_resource and deregister_resource service methods following the established grant/revoke pattern; bypass and principal-override semantics are consistent with existing methods.
agentex/src/adapters/authorization/adapter_agentex_authz_proxy.py	Adds register_resource (POST /v1/authz/register) and deregister_resource (POST /v1/authz/deregister) to the proxy adapter; payload serialization mirrors the existing grant/revoke pattern.
agentex/src/adapters/authorization/port.py	Adds abstract register_resource and deregister_resource to AuthorizationGateway; docstrings clearly explain the SpiceDB cascade contract.
agentex/tests/integration/services/test_agent_api_key_service_dual_write.py	Six new integration tests covering the dual-write sequencing (register-before-create, fail-closed on register failure, best-effort deregister, no-creator skip, delete-by-name deregister). Missing coverage for the delete_by_agent_name_and_key_name path.
agentex/tests/unit/use_cases/test_agents_api_keys_use_case.py	Updated fixture to inject a properly mocked authorization_service (with AsyncMock for both register_resource and deregister_resource), matching the integration client setup.
agentex/tests/integration/fixtures/integration_client.py	Adds a noop_authorization_service mock with all required AsyncMock methods and passes it to AgentAPIKeysUseCase; consistent with the unit test fixture pattern.

Sequence Diagram

sequenceDiagram
    participant C as Caller
    participant UC as AgentAPIKeysUseCase
    participant AS as AuthorizationService
    participant GW as AgentexAuthorizationProxy
    participant DB as Postgres
    participant AX as agentex-auth

    Note over UC,AX: create()
    C->>UC: create(name, agent_id, api_key_type, api_key)
    UC->>DB: agent_repo.get(agent_id)
    DB-->>UC: AgentEntity
    UC->>UC: _register_api_key_in_auth(api_key_id, agent_id)
    UC->>AS: "register_resource(resource=api_key, parent=agent)"
    AS->>GW: register_resource(principal, resource, parent)
    GW->>AX: POST /v1/authz/register
    AX-->>GW: 200 OK
    GW-->>AS: None
    AS-->>UC: None
    UC->>DB: agent_api_key_repo.create(entity)
    DB-->>UC: AgentAPIKeyEntity
    UC-->>C: AgentAPIKeyEntity

    Note over UC,AX: delete() / delete_by_*()
    C->>UC: "delete(id) / delete_by_*(...)"
    UC->>DB: agent_api_key_repo.get(id)
    DB-->>UC: "AgentAPIKeyEntity (or ItemDoesNotExist -> return)"
    UC->>DB: agent_api_key_repo.delete(id)
    DB-->>UC: None
    UC->>UC: _deregister_api_key_from_auth(api_key_id)
    UC->>AS: "deregister_resource(resource=api_key)"
    AS->>GW: deregister_resource(principal, resource)
    GW->>AX: POST /v1/authz/deregister
    AX-->>GW: 200 OK (failure: logged, ignored)
    GW-->>AS: None
    AS-->>UC: None
    UC-->>C: None

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.

   

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/tests/integration/services/test_agent_api_key_service_dual_write.py:260-291
**`delete_by_agent_name_and_key_name` dual-write path has no test**

`delete_by_agent_id_and_key_name` has `test_delete_by_agent_id_and_key_name_revokes_existing`, but the parallel method `delete_by_agent_name_and_key_name` — which follows the same pre-fetch → delete → deregister pattern — has no coverage in this suite. If a regression breaks the `get_by_agent_name_and_key_name` lookup or the conditional deregister there, it would go undetected. A mirrored test (analogous to the existing one but using agent name instead of agent ID) would close the gap.

_{Reviews (9): Last reviewed commit: "Merge branch 'main' into dhruv/agx1-272-..." | 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