feat(connections): register Superhuman Mail as a launch-gated provider

[CrysisDeu]

Problem / Motivation

Reconnecting a Superhuman Mail MCP server fails at the OAuth consent banner once its token expires:

superhuman-mail authentication failed: URL contained credential or exfiltration pattern

The banner gate exempts OAuth entropy (state, PKCE) only at an exact (host, path) in the builtin _OAUTH_AUTHORIZATION_ENDPOINTS, and Superhuman's MCP authorization server was not in it. PR #5967 (@mndoci) proposed adding the allowlist entry alone; the First Principles lane blocked it because the builtin set is defined as derived from the Connections registry, and Superhuman was not a registry provider.

What this does

Takes the registry route the review pointed at, so the allowlist entry becomes derived rather than an exception:

• Registers Superhuman Mail as a Connections provider (src/kiro_crew/connections/registry.json): mcp_url https://mcp.mail.superhuman.com/mcp, issuer https://mcp.auth.mail.superhuman.com, DCR + PKCE S256 — all taken from the provider's live RFC 9728 / RFC 8414 metadata and confirmed by the L0 probe (l0_probe reports ok: true for superhuman).
• Adds the MCP authorization server to the builtin allowlist (("mcp.auth.mail.superhuman.com", "/oauth2/authorize")), carrying over the corpus sample and the four gate tests from feat(security): allowlist Superhuman MCP OAuth authorization endpoint #5967 (co-authored).
• Launch-gated (launch_gate_passed: false, same posture as GitHub): the provider is in the registry and reconnect works today for a hand-configured server, but the Connect card stays hidden. The revoke_verified_note states plainly that no Business-plan account was available to verify the revoke surface.
• Pins the derivation rule with a new registry test: every provider's issuer host must have a builtin allowlist entry, gated or not — the invariant the review was defending, now mechanical.

Un-gating checklist (follow-up, needs a Superhuman Business/Enterprise account)

1. Log in, find the surface that lists MCP client grants, set revoke_page_url (+ revoke_manual_path if it is a settings modal) and refresh revoke_verified_on / revoke_verified_note.
2. Walk the consent flow once (L2) and confirm list_labels is advertised by tools/list.
3. Flip launch_gate_passed to true, move superhuman out of LAUNCH_GATED in the registry test, and add a brand mark in website/src/pages/connections/ProviderLogo.tsx + a value_prop_superhuman catalog string (both currently fall back to the lettered tile / generic blurb, so nothing is required while gated).

Relationship to #5967

Supersedes the allowlist-only change in #5967 by landing the same entry as a registry-derived one. Once this merges, #5967 can be closed as superseded (its author is credited via Co-authored-by), or rebased if the maintainer prefers to keep it as the vehicle.

Testing

Targeted local runs on test/test_connections_registry.py, test/test_mcp_oauth_banner.py, test/test_connections_tool_aliases.py, test/test_connections_l0_probe.py (581 passed) and a live python -m kiro_crew.connections.l0_probe run (all 8 providers ok). Full gates are left to CI per the maintainer's request.

No UI change: the new provider is launch-gated and never rendered.

no linked issue: originates from PR #5967's review outcome (First Principles BLOCK asking for a registry-derived entry), not from a filed issue.

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of 1470d711fc3b07af7f3d21069cabf7b439c3b4d3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Registry-derived allowlist entry plus a mechanical invariant test is exactly the shape the #5967 review asked for; gating hides the unverified UI surface.

Suggestions

• The new invariant test matches on issuer host only, while the exemption is granted per exact (host, path) — a future provider whose allowlist path is wrong passes the test yet still fails reconnect. Recording the advertised authorization_endpoint in l0_expectations would let the test pin the full pair.

[DESIGN-REVIEWED] 1470d71

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed 1470d711fc3b07af7f3d21069cabf7b439c3b4d3 — this comment is updated in place on each push.

Review details

No findings.

The lone candidate is self-admittedly ungrounded: its (a) is the hypothetical "if Superhuman's real authorize path is not exactly /oauth2/authorize" — a fact it cannot verify and which does not "occur in practice" on any code path here. Even granting the hypothetical, the outcome is fail-closed (a reconnect that errors out, not a security weakening), and the provider is launch_gate_passed:false so it is off the Connect grid. The suggested remedy is a comment/corroboration change, not a defect in the changed lines. The added allowlist entry is an exact (host, path) pair; the diff's own tests confirm it neither suffix-matches a look-alike host nor waives fixed-credential signatures. Nothing survives falsification.

[OPUS-REVIEWED] 1470d71

Verdict parsed from the review's SHA-scoped output markers for commit 1470d711fc3b07af7f3d21069cabf7b439c3b4d3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1470d711fc3b07af7f3d21069cabf7b439c3b4d3: <one-sentence reason>

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 1470d711fc3b07af7f3d21069cabf7b439c3b4d3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1470d71

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1470d711fc3b07af7f3d21069cabf7b439c3b4d3: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 1470d711fc3b07af7f3d21069cabf7b439c3b4d3 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

The reconnect defect gets a registry-derived fix plus a mechanical test that turns this defect class from point patches into an enforced invariant.

What this change ships

Intent: make an expired Superhuman Mail MCP token reconnectable through the OAuth consent banner — a FIX, delivered via the registry route its predecessor #5967 was blocked for skipping.

1. Superhuman consent URLs now pass the banner gate; reconnect works — justified (quoted defect, exact-match pair, fail-closed design preserved)
2. Superhuman Mail becomes a Connections provider, hidden from the Connect grid — justified: security.py:10691 documents "Every entry added to the Connections registry needs its MCP authorization server here too", and the MCP allowlist section is defined as registry-derived
3. Launch gate reuses the existing launch_gate_passed/get_visible_providers mechanism (GitHub precedent) — justified, no new mechanism
4. New test pins registry-issuer ⊆ allowlist for all 8 providers — justified; grepped _OAUTH_AUTHORIZATION_ENDPOINTS across test/: no prior test relates the registry to the allowlist (0 duplicates), and all 8 current issuer hosts pass, so no unfixed siblings remain
5. Gated-set test generalized from hardcoded "github" to LAUNCH_GATED — rides along, but required by item 2
6. revoke_verified_on stamped 2026-09-03 with an explicitly UNVERIFIED note — declared; the field is schema-required (registry.py:371), and the gate stays closed until it's real

The zero option for item 2 (allowlist entry alone) is exactly what the recorded #5967 review rejected and what the code comment forbids — not relitigated. The operator oauth_endpoints.json extension is a different, per-install mechanism documented for non-launch providers, not a second spelling.

[FIRST-PRINCIPLES-REVIEWED] 1470d71

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• PR #7621 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #7621: MERGE_DISCUSSION. A merged change occupies PR #7621's corpus insertion point, so the PR is no longer auto-mergeable; the security.py half still applies cleanly. Files: test/oauth_url_corpus.py, src/kiro_crew/security.py.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.