feat(agentex): run Slack turns as the invoking user, and the flow to link them

[michael-chou359]

What

Part of the event-driven agents work, and the half of it that changes behavior.
#409 added storage for linking an external chat identity to an SGP user; nothing
consumed it. This wires it up and adds the flow that creates the links.

Before this, every Slack-originated turn ran as a single shared bot service account.
The agent acted with one fixed identity regardless of who asked, and its tools could
only ever reach what that bot could reach. After this, when the person who sent the
message has linked their account, the turn runs as them — so their own connected
integrations (Notion, Linear, …) resolve.

Unlinked users are unaffected. No link means the existing bot path, unchanged.

Verified end to end

The credential path is proven against the live dev services, not just mocked:

LIST   /v6/sgp/secrets?scope=user            cookie -> 200   key='notion' scope='user' owner=<the user>
VALUE  /v6/sgp/secrets/values?...&keys=notion cookie -> 200   real OAuth envelope:
                                                              {access_token, refresh_token,
                                                               client_id, expires_at, token_endpoint}
VALUE  (identical request)                gateway bot -> 401   INVALID_API_KEY

So a stored session credential really does read that user's own decrypted secret,
with owner_user_id derived from the caller, and the shared bot cannot read it.

One caveat on that control: the bot is refused at authentication (its key comes from
a different issuer than the vault accepts), not at authorization. It establishes that
the bot can't reach the user's secrets, but not that per-owner scoping is what stops
it. The owner=<the user> in the list response is the evidence for scoping.

The linking flow

The mapping can't be derived — nothing in a webhook says anything about SGP. So it's
established in the one moment where both identities are authenticated at once, with a
server-side nonce tying two requests together.

1.  Slack event arrives
      Slack's HMAC proves the Slack side — only Slack could have signed it.
      We hold a trusted (team_id, user_id) and no idea who that is in SGP.
               │
2.  park it in a nonce → single-use, short TTL          link_nonce_service
      {provider, team_id, external_user_id, display_name, pending_turn}
      The browser receives only an opaque token.
               │
3.  user clicks → GET /integrations/slack/link?nonce=…  integrations.py
      NOT auth-whitelisted (unlike /slack), so the auth middleware runs and
      the user's own browser session supplies the SGP side.
               │
4.  both halves in ONE request → confirmation page naming each identity
               │
5.  POST → store the caller's own session cookie (encrypted) → burn the nonce
               │
6.  every later event: resolve → decrypt → forward      slack_gateway_use_case
      as x-acting-user-cookie; the agent's tools act as that person

Why a nonce rather than ids in the URL. A query string is user-editable. Given
?slack_user=<someone else>, an attacker could click their own link while signed in as
themselves and bind that person's chat identity to their own SGP account — after
which the victim's messages would run as the attacker, using the attacker's
integrations, with the victim's prompts landing in the attacker's account. An opaque
token means nothing in the URL is meaningful, so nothing in it is forgeable.

Why the session cookie, and not a minted API key

Minting was the original design. It cannot work, and only a live request found
that out — all 86 unit tests passed against it first.

identity-service permits one API key per user, and every active user already has
one (auto-named "<email> - API Key"). So POST /api-keys answers
409 "API key already exists for this user" — reproduced with a unique name, so it's
not a name collision, and 409 isn't even a documented response on that endpoint. The
existing key's secret can't be read back, and rotating theirs would silently break
whatever else uses it.

Storing the caller's session cookie is better on its own merits, not just as a
fallback:

• It carries its own expiry. credential_expires_at comes from the JWT's exp
  instead of a TTL we invent. (The API key we'd have minted alongside theirs would
  have sat next to one with expiresOn: null.)
• It's already in the request — no outbound call left to fail. That deletes the
  mint's entire error surface, the IDENTITY_SERVICE_URL config, and the cookie-guard
  constraint that made the mint impossible to test in the first place.
• It touches nothing the user already has.

And it isn't a workaround: delegation_headers.py
already forwards session cookies as x-acting-user-cookie with _identityJwt
allowlisted by default. acting_headers() just had to return a cookie instead of an
api-key; delegation itself is untouched.

The cost, stated plainly: the link now lives and dies with the session. Sign-out or
revocation ends it, surfacing downstream as a rejected credential. The gateway should
treat that as "re-link needed" rather than an error — that belongs with the DM trigger.

Change

Gateway (slack_gateway_use_case.py)

• _turn_identity() resolves (team, user) → link → that user's principal and acting
  headers. Falls back to the bot when there's no usable link.
• Task naming is now per-user for linked users (slack:{thread_ts}:{sgp_user_id}), so
  two people in one thread don't write into a shared task. Unlinked users keep the
  legacy key, so existing threads keep their history.
• slack_user_id / sgp_user_id recorded in task_metadata for attribution.

Link flow (new)

• link_nonce_service.py — create / peek / consume. peek is non-consuming so a
  refresh or a link-prefetching browser doesn't burn the nonce; consume is GETDEL,
  so single-use is enforced by Redis rather than a read-then-delete race. Requires
  Redis and raises rather than degrading.

  At most one live nonce per identity. A nonce is a bearer token, so several live
  ones means several chances for a link to be redeemed by the wrong person — and
  consuming one doesn't invalidate its siblings, so a user who linked successfully
  would still have working tokens pointing at their Slack identity until each expired.
  create() invalidates whatever nonce the identity already held; create_or_reuse()
  re-sends the live link rather than minting a parallel one; claim_send() caps DMs
  about a given link at 2 (IDENTITY_LINK_MAX_DMS), resetting when a genuinely new
  nonce is minted so a new link is never withheld.

  Reuse deliberately does not extend the TTL — otherwise mentioning the agent every
  few minutes keeps one token alive indefinitely. The pending turn is refreshed within
  the remaining window, so linking answers what the user most recently asked.

• integrations.py — the two routes and the confirmation page. Deliberately under
  /integrations, not /slack: the latter is auth-whitelisted because Slack's
  signature is its auth, and a callback there would run unauthenticated, defeating the
  whole mechanism.

• session_jwt.py — reads the exp claim. Does not verify the signature, and must
  never be used as an auth check: the token arrives on an already-authenticated request,
  and verifying would mean holding the signing key, which agentex shouldn't have.

• identity_link_service.py — cached resolution; uncached credential access.

Account id is now required to link

The vault refuses a session credential with no account context (400 "Account ID is required"), and an account the user isn't a member of is a 403 "Identity <id> (user) is not authorized to access". So it has to be their account, captured from their
own principal — not the gateway's configured one, which only works for members of it
and would anyway look in the wrong account for their connections.

Linking without one returns a 400 asking them to pick an account, and
acting_headers() returns None rather than partial headers, because a link stored
without an account would look connected and resolve nothing.

Other details that are easy to get wrong

• acting_headers() is never cached, though resolution is (shorter TTL for negative
  results). Caching a credential is how you end up serving a revoked one.
• Every "can't act as them" case returns None, not a partial identity, so the
  gateway falls back explicitly instead of half-assuming a user.
• The nonce is consumed only after a successful store, so a transient failure leaves
  the link clickable instead of sending the user back to Slack.
• A missing encryption key returns 503 and stores nothing, rather than 500-ing.
• An unknown token expiry becomes a bounded fallback, never "no expiry" — storing an
  unbounded credential is how you end up holding one indefinitely.

What this does NOT do

Nothing sends anyone a link. On an unlinked mention the gateway still runs as the
bot; it doesn't offer to connect. Step 1 has no trigger, so today the flow is only
reachable through scripts/dev_seed_link_nonce.py. The DM trigger —
conversations.open + chat.postMessage, an ephemeral in-channel notice, and replaying
the stashed pending_turn — is the next change. claim_send() is the primitive it will
call; nothing calls it yet.

Also open, and better settled in that PR than here:

• The forwarded-link hole. The confirmation page is currently the only thing
  stopping someone forwarding their own link to another person, who could click
  through and bind the sender's chat identity to their own SGP account. The page names
  both identities, which covers a mis-click but reduces to user vigilance against a
  deliberate attempt. Comparing the Slack account's email against the SGP session's
  email would close it — the storage already has IdentityLinkMethod.EMAIL_MATCH.
• Treating a rejected credential as "re-link needed", now that expiry is real.

So this PR is safe to merge but not yet user-visible.

Testing

• ~100 new unit tests across the routes, link service, nonce service and the
  session-JWT util, plus 11 added to the gateway suite. Full CI green.

• Coverage aims at failure modes rather than the happy path: unauthenticated caller
  stores nothing, expired/stale nonce refused, session cookie absent, session already
  expired, principal with no account, SGP account already linked to a different Slack
  user, unconfigured encryption key reported as 503 rather than 500, and the nonce token
  leaking nothing identifying.

• The JWT util's tests concentrate on malformed input, since anything unreadable must
  return "unknown" so the caller substitutes a bounded fallback — including exp=True,
  which a naive isinstance check accepts as an int and turns into 1970-01-01, i.e. a
  credential that looks permanently expired.

• 14 integration tests against a real Redis. The nonce's unit tests use a
  hand-written fake, so they assert our model of Redis rather than Redis. These cover
  the divergences that matter: the app runs decode_responses=False so real Redis
  returns bytes where the fake returns str (an undecoded pointer read would
  silently mint parallel tokens); GETDEL atomicity under five concurrent consumes;
  KEEPTTL genuinely preserving an expiry while rewriting the payload — which the fake
  can't prove at all, and which the "reuse must not extend the lifetime" guarantee rests
  on; and INCR/EXPIRE/TTL returning what the send cap assumes.

  These depend only on redis_url, not isolated_repositories, so they need no Postgres
  or MongoDB — keeping them at ~3s and runnable where the Mongo image won't boot.
  Verified locally against real Redis, stable across three runs.

Still unverified: the browser click-through itself, which needs this deployed —
there's no route to click until then. Every hop it depends on is individually proven
(cookie → principal → vault → decrypted secret).

Deploy notes

• AGENTEX_CREDENTIAL_ENCRYPTION_KEY must be set, or linking returns 503 (by design —
  it will not store a credential in plaintext). Already present in dev.
• The agentex host must be a sibling subdomain of the SGP host, or the session cookie
  never arrives and step 3 can't resolve anyone.
• No new outbound service dependency, and no migration: feat(agentex): identity-link storage with encrypted credentials at rest #409's credential_ciphertext
  column is credential-agnostic, so only its contents change.

🤖 Generated with Claude Code

Greptile Summary

This PR links Slack identities to authenticated SGP users and delegates linked Slack turns through the user’s stored session credential.

• Adds authenticated Slack-link confirmation routes and Redis-backed, expiring nonces.
• Resolves linked identities and forwards their session and account context for agent turns.
• Scopes linked-user task names by workspace, channel, thread, and SGP user while preserving the legacy key for unlinked users.
• Adds focused unit and Redis integration coverage for linking, delegation, nonce handling, and session expiry parsing.

Confidence Score: 3/5

The PR is not yet safe to merge because the previously reported nonce-redemption race still permits multiple authenticated confirmations to persist before a unique claim is established.

The confirmation route still peeks at the nonce, persists the identity link, and only afterward consumes the nonce without checking whether that request won the claim; overlapping submissions can therefore both mutate the mapping and report success.

Files Needing Attention: agentex/src/api/routes/integrations.py, agentex/src/domain/services/link_nonce_service.py

Important Files Changed

Filename	Overview
agentex/src/api/routes/integrations.py	Adds the authenticated browser confirmation flow that validates principals, stores encrypted session credentials, and consumes link nonces.
agentex/src/domain/services/link_nonce_service.py	Implements Redis-backed creation, reuse, refresh, send limiting, and consumption of short-lived identity-link nonces.
agentex/src/domain/services/identity_link_service.py	Resolves cached identity mappings while retrieving credentials uncached and constructing account-scoped delegation headers.
agentex/src/domain/use_cases/slack_gateway_use_case.py	Runs linked Slack turns under the invoking SGP identity and scopes their task names by workspace, channel, thread, and user.
agentex/src/utils/session_jwt.py	Adds defensive extraction of session-token expiry for bounded credential persistence.

Sequence Diagram

sequenceDiagram
  participant Slack
  participant Gateway
  participant Redis
  participant Browser
  participant LinkRoute
  participant Database
  participant Agent

  Slack->>Gateway: Signed event (team, user, message)
  Gateway->>Redis: Store short-lived link nonce
  Gateway-->>Browser: Opaque link
  Browser->>LinkRoute: GET link with SGP session
  LinkRoute->>Redis: Peek nonce
  LinkRoute-->>Browser: Confirm Slack and SGP identities
  Browser->>LinkRoute: POST confirmation
  LinkRoute->>Database: Store encrypted session link
  LinkRoute->>Redis: Consume nonce
  Slack->>Gateway: Later signed event
  Gateway->>Database: Resolve identity and credential
  Gateway->>Agent: Turn with acting-user cookie

Loading

_{Reviews (6): Last reviewed commit: "docs(agentex): correct delegation commen..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Service API and authentication
• Knowledge Base — Task creation and state management

[github-actions]

✱ Stainless preview builds

This PR will update the agentex-sdk SDKs with the following commit messages.

openapi

feat(api): add slack link endpoints and request body to integrations

python

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

✅ agentex-sdk-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ agentex-sdk-typescript studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

⚠️ agentex-sdk-python studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-27 02:58:06 UTC