[WIP] feat(seer): Gate agent writes behind short-lived capability tokens

[gricha]

WIP / prototype. Feature-flagged off (organizations:seer-agent-token-flow), no-op for non-agent traffic. Builds on the merged RFC 6750 scope work (#118612).

Why

The Seer agent acts against the Sentry API on a user's behalf. We want its writes explicitly approved by that user, without handing the agent the user's full authority. Sentry issues the agent a short-lived, scope-bound capability token — read-only by default, with write scopes added only after the user approves them — and enforcement rides Sentry's ordinary token-scope path.

Flow

1. Mint — POST /organizations/{org}/agent/token/ returns a short-lived JWT (sntryag_…) scoped to caller_readonly ∪ approved_grants, intersected with what the caller holds. Only ever de-escalates.
2. Use — the agent sends it as Authorization: Bearer; AgentTokenAuthentication verifies it and feeds the scopes through the normal access path.
3. Deny — an under-scoped write is denied by the shared scope gate with the standard 403 + WWW-Authenticate: insufficient_scope, scope="…" (from feat(api): Advertise required scopes on token-scope 403s (RFC 6750) #118612). Nothing agent-specific in the permission layer.
4. Approve — Seer reads the missing scopes from that header (it already knows org + session), and surfaces an approval link. The user approves via POST /agent/approve/ {sessionId, scopes}; the endpoint caps scopes at the approver's own access and persists a SeerAgentWriteGrant. Re-mint then includes the scope.

Security of approval

The approve endpoint creates the grant for the authenticated approving user (never identity from the link), capped at that user's own scopes server-side, bound to (org, user, session). So a forged link is inert: it can only get a user to consent to their own agent, can't escalate beyond their scopes, and a wrong sessionId matches no real agent session. Consent is a CSRF-protected POST on Sentry's origin — the link only points there.

What's here

• seer/agent_token.py — JWT mint/verify, scope de-escalation, grant creation.
• AgentTokenAuthentication (prefix-routed sntryag_, after OrgAuthTokenAuthentication).
• Mint + approve endpoints; SeerAgentWriteGrant model + migration 0024.
• Cross-org binding guard in determine_access (a token minted for one org is never honored against another).

No permission-layer override and no challenge tokens — the agent just gets the same insufficient_scope 403 as any under-scoped token.

Tests

tests/sentry/seer/ — auth/verify, scope de-escalation, end-to-end mint→read-ok→write-denied (asserts the insufficient_scope header, nothing persisted), and approve (scope capping, idempotency, self-approval blocked).

[github-actions]

🚨 Warning: This pull request contains Frontend and Backend changes!

It's discouraged to make changes to Sentry's Frontend and Backend in a single pull request. The Frontend and Backend are not atomically deployed. If the changes are interdependent of each other, they must be separated into two pull requests and be made forward or backwards compatible, such that the Backend or Frontend can be safely deployed independently.

Have questions? Please ask in the #discuss-dev-infra channel.

[github-actions]

This PR has a migration; here is the generated SQL for src/sentry/seer/migrations/0024_add_agent_write_grant.py

for 0024_add_agent_write_grant in seer

--
-- Create model SeerAgentWriteGrant
--
CREATE TABLE "seer_agentwritegrant" ("id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, "date_updated" timestamp with time zone NOT NULL, "date_added" timestamp with time zone NOT NULL, "user_id" bigint NOT NULL, "agent_session_id" varchar(128) NOT NULL, "scope_list" text[] NOT NULL, "expires_at" timestamp with time zone NOT NULL, "organization_id" bigint NOT NULL);
--
-- Create constraint seer_agentwritegrant_unique_session on model seeragentwritegrant
--
CREATE UNIQUE INDEX CONCURRENTLY "seer_agentwritegrant_unique_session" ON "seer_agentwritegrant" ("organization_id", "user_id", "agent_session_id");
ALTER TABLE "seer_agentwritegrant" ADD CONSTRAINT "seer_agentwritegrant_unique_session" UNIQUE USING INDEX "seer_agentwritegrant_unique_session";
ALTER TABLE "seer_agentwritegrant" ADD CONSTRAINT "seer_agentwritegrant_organization_id_fef7e9ff_fk_sentry_or" FOREIGN KEY ("organization_id") REFERENCES "sentry_organization" ("id") DEFERRABLE INITIALLY DEFERRED NOT VALID;
ALTER TABLE "seer_agentwritegrant" VALIDATE CONSTRAINT "seer_agentwritegrant_organization_id_fef7e9ff_fk_sentry_or";
CREATE INDEX CONCURRENTLY "seer_agentwritegrant_user_id_f7f8d1c5" ON "seer_agentwritegrant" ("user_id");
CREATE INDEX CONCURRENTLY "seer_agentwritegrant_organization_id_fef7e9ff" ON "seer_agentwritegrant" ("organization_id");

[sentry-warden]

update_or_create on SeerAgentWriteGrant without a database unique constraint causes MultipleObjectsReturned on concurrent approvals

In sentry/seer/agent_token.py::grant_from_challenge_claims, update_or_create relies on (organization_id, user_id, agent_session_id, scope_list) to deduplicate grants, but no unique_together or UniqueConstraint exists in the model or migration — only a non-unique index. Concurrent approval requests (e.g., a user double-clicking) will both pass the SELECT phase, both INSERT new rows, and a subsequent update_or_create on the same lookup will find multiple rows and raise an unhandled MultipleObjectsReturned, surfacing as a 500.

Evidence

• grant_from_challenge_claims calls SeerAgentWriteGrant.objects.update_or_create(organization_id=…, user_id=…, agent_session_id=…, scope_list=…, defaults={…}) (agent_token.py line 297).
• Migration 0024_add_agent_write_grant.py creates seer_agentwritegrant with only a non-unique Index on (organization, user_id, agent_session_id) — no unique_together or UniqueConstraint on any combination of fields.
• Without a DB-level unique constraint, Django's update_or_create cannot atomically prevent two concurrent INSERTs; both callers will succeed in inserting separate rows.
• On the next call, Django's internal get() inside update_or_create finds multiple matching rows and raises MultipleObjectsReturned, which is unhandled and propagates as an HTTP 500.
• Adding constraints = [models.UniqueConstraint(fields=['organization', 'user_id', 'agent_session_id', 'scope_list'], name='…')] (and a corresponding migration) and catching IntegrityError with a fallback to update() would fix this.

_{Identified by Warden sentry-backend-bugs}

[sentry]

Sentry Snapshot Testing

Name	Added	Removed	Changed	Renamed	Unchanged	Skipped	Status
sentry-frontend sentry-frontend	0	0	0	0	451	0	✅ Unchanged

⚙️ sentry-frontend Snapshot Settings