docs(research): connector, credential and egress layer audit (#13623)

[mrveiss]

Thinking Path

Audit of our connector, credential and egress layer, using an external implementation of the same
problem domain as a comparison lens. The goal was to find real defects and structural gaps, not to
import a design — so every candidate pattern was checked against what we already have before being
proposed, and the most impressive idea in the reference was rejected because it does not fit our
scale.

What Changed

Docs only. No code touched.

• docs/research/connector-credential-egress-audit.md — the audit
• docs/research/_index.md — index entry
• .session/HANDOFF-issue-13623.md — session handoff

Findings (all filed, none implemented)

Umbrella #13623 with children #13624-#13632, plus #13643 filed under #10088 Task 5.

Two live bugs, both in knowledge/connectors/credential_store.py, both silent in production:

• bug(oauth): a refresh response without expires_in permanently disables token refresh — connector auth dies silently #13626 — an OAuth refresh response that omits expires_in (permitted by RFC 6749 §5.1) sets
  the expiry to None, and _access_token_expired(None) returns False, so the credential is
  never refreshed again. Connector auth dies days later with nothing in the logs pointing at the
  refresh that caused it.
• bug(oauth): concurrent get_access_token both refresh — rotating-refresh-token providers lose the valid token #13627 — get_access_token is read → refresh → write with no lock. The code already notes
  that some providers rotate the refresh token per use; a scheduled sync overlapping a
  user-triggered one can strand the grant.

Two fail-open guards (#13628): the ownership check skips rather than denies on a missing
created_by, and rotate() is the only credential read path that omits accessed_by, so the most
privileged operation is the unaudited one.

Egress (#13624, #13625): cross-origin redirects replay the caller's Authorization header; six
connectors with user-configured hosts never touch the SSRF guard. #13625 is not a duplicate of
#13204, which covers browser paths only.

Secrets platform (#13643): integrations/ has no secrets-manager integration at all —
credentials are passed as bare values, so no grant, audit, revocation, or dependency edge applies.

Verification

Docs-only change; no gates apply. Every claim in the document cites a file and line that was read,
and the two live bugs were traced through their call paths before filing.

$ git diff --stat origin/Dev_new_gui...HEAD
 .session/HANDOFF-issue-13623.md                   |  33 ++
 docs/research/_index.md                           |   1 +
 docs/research/connector-credential-egress-audit.md| 306 ++++++++++++++

Model Used

Claude Opus 5 (1M context)