Record the #1006 OAuth pack: connector status table, catalog audit appendix, and an operator runbook for hosted connectors - #1496
Closed
KristianYe wants to merge 1 commit into
Closed
KristianYe wants to merge 1 commit into
KristianYe wants to merge 1 commit into
Conversation
…pendix, and an operator runbook for hosted connectors docs/MCP-CATALOG-STATUS.md is the record #986 asked for: the live-run table for the twelve hosted connectors exercised against real vendor accounts (add, consent, tools, tool calls from chat and scheduled tasks, refresh, sign-out, seats and sharing, with the fleet PR each one needed), the fleet changes the pack produced, the audit findings with their disposition, and a per-entry appendix from re-probing all 231 official OAuth/tenant/open entries with fleet's own discovery on the current code and catalog. docs/HOSTED-CONNECTORS-RUNBOOK.md is what an operator needs before and after Connect: how the callback URL is derived and which vendors refuse plain http, what the encryption key protects, the three shapes of Connect, the measured per-vendor prerequisites (GitHub, Google Workspace, Slack, Notion, Linear, Azure DevOps, Stripe, Grafana Cloud, Uptime Robot, Plaid, Intercom, Square, Smartlead), how chat and scheduled runs mount connections, seats and sharing, and how to read fleet.log and the Add/sign-in errors. Both pages are indexed in docs/README.md. Live results are separated from discovery-only probes throughout, and the vendors that were deliberately skipped (Square, Smartlead, the Plaid/Intercom fallback) are named as such. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
4 tasks
bradflaugher
added a commit
that referenced
this pull request
Sep 14, 2026
…Auth pack record (supersedes #1495, #1496, #1499) (#1501) ## What changed, and why One PR that supersedes the three open PRs, merged locally on top of current `main` and driven to green together. Supersedes #1495, #1496 and #1499; each of those is closed in favour of this one. **Tags on the Operations Center board, and a tag filter** (from #1499). Every task row and phone card shows its tags as chips; pressing a chip filters the board by that tag, and the filter bar offers a tag dropdown fed by a deployment-wide catalogue (`GET /api/orchestrator/tasks/tags`, proxied to the backend) unioned with the tags on the listed tasks. The catalogue is refreshed at most every five minutes off the dashboard's ordinary reload cadence. Design note: `docs/TASK-TAGS.md`; both Operations Center guide copies updated and `docs/USER-GUIDES.md` corrected so it no longer says tags do not filter the board. **Seven built-in catalog entries corrected** (from #1495). Data-only fixes the #1006 OAuth audit found by running fleet's own discovery against every official entry: expensify's trailing slash, cartesia's `/mcp` endpoint, octagon's declared resource host, globalping now OAuth, zerodha-kite open with a sign-in hint, sage-intacct manual registration with a required client secret (pinned by test), openrouter's docs URL. Square and smartlead (SSE-only) are deliberately not changed. **The #1006 OAuth pack recorded** (from #1496). `docs/MCP-CATALOG-STATUS.md` (live-run status table for twelve hosted connectors, the fleet changes the pack produced, and a per-entry appendix from re-probing all 231 official OAuth/tenant/open entries) and `docs/HOSTED-CONNECTORS-RUNBOOK.md` (what an operator needs before and after Connect, per vendor). Both indexed in `docs/README.md`. **Review fixes on the merged tree** (new here, from a pre-PR review of the combined diff): - The tag catalogue's TTL effect was cancelled by any dashboard reload finishing mid-flight, dropping a valid response and leaving the stamp set, so the dropdown could stay empty for five minutes. Request lifetime is now a generation counter, bumped on fetch start and on deactivation/unmount (which also zeroes the stamp). Three regression tests. - Enter/Space on a focused desktop tag chip bubbled to the row handler, which opened the log viewer and blocked the chip's activation. The row handler now acts only when the row itself is the target. Regression test. - `docs/MCP-CATALOG-STATUS.md` overstated grantee isolation (a grantee's run does refresh the owner's token row; revocation is checked at mount time) and embedded the audit's probe tenant hostname in the spacelift row, now a `<tenant>` placeholder. **Codex GitHub review of this PR** (five P1 threads, all verified against the code and fixed in `61f9b9df`): stale #1488/#1495 dispositions in the status record; the runbook now states the eight-server overlay cap and that transient refresh failures do not mark a connection for reconnect; saved connections keeping a pre-correction URL is documented in `CONNECTOR-ONBOARDING.md` and recorded as finding F13 (reconciliation deferred, remove and re-add); the Zerodha Kite entry's hint no longer claims the login session persists across turns or works in scheduled runs. **Codex re-review** (three P2 runbook threads and one P3 security finding, fixed in the third follow-up commit): `GET /tasks/tags` returned the deployment-wide catalogue with counts to any signed-in user; it is now scoped exactly like `ListTasks` (#1082 own-rows rule, `view_tasks` required, SQL filter on `created_by` / `created_by_key_id`), with `TestTagCatalogueScope` and `TestTagCatalogueAuthz`. The design note and both Operations Center guide copies describe the scoped catalogue. The runbook no longer implies a Kubernetes deployment has an Ingress or prescribes where TLS terminates, names 128 tools as the default disclosure threshold with its two overrides, and distinguishes terminal from transient refresh failures in troubleshooting. **Third Codex pass** (five threads, fixed in the fourth follow-up commit): the phone card's keyboard focus ring was clipped by the list item's `overflow: hidden` and is now drawn on the list item via `:has()`; the guide discloses the catalogue's five-minute refresh bound; the runbook stops telling operators to keep the OAuth encryption key with the database backups, says only user-enabled connections mount in scheduled runs (a disabled one is omitted silently), and qualifies the 401 catalog check as the OAuth shape only. ## How you verified it Local Postgres (podman `postgres:18`) with the three DSN vars set, so the DB-backed packages ran rather than skipped: - `make build`: clean. - `scripts/go-test.sh --count=1` (the `make test` path): 63 packages `ok`, 0 failures; `internal/store` 12.7s, `internal/httpapi` 22.0s, `internal/runner` 7.7s confirm the DB suites executed. - `make lint`: golangci-lint 0 issues; ruff check and format --check clean; migration lint 0 files. - `go test -tags fleet_host_executor ./scripts/ ./internal/clientconfig/...`: PASS (docs-index check, guide sync check, catalog tests including the new `sage-intacct` pin). - `make sync-guides`: no drift between the two guide copies. - `make ci-web`: npm audit 0 vulnerabilities; oxlint 0 warnings/errors on 532 files; typecheck clean; vitest 153 files / 1614 tests passed (4 new); `next build` 74/74 pages. - `make ci-e2e-mocked`: 98 passed. - `gitleaks git --log-opts=origin/main..HEAD`: 5 commits scanned, no leaks. - Each of the four new regression tests was confirmed to fail against the code it replaces. - After the docs/catalog follow-up (`61f9b9df`): `go test -tags fleet_host_executor -count=1 ./scripts/ ./internal/clientconfig/...` PASS (docs index, catalog decode and pins); `make lint` clean. - After the tag-catalogue scoping fix: `scripts/go-test.sh --count=1` against Postgres again, 63 packages `ok`, 0 failures; `TestTagCatalogueScope` and `TestTagCatalogueAuthz` print `PASS` (not `SKIP`) under `-v`; `make lint` clean; `make sync-guides` no drift; `go test ./scripts/` PASS; `make ci-web` green (1614 tests, build 74/74). - After the focus-ring and runbook fixes: `make ci-web` green again (1614 tests, 74/74), `make sync-guides` no drift, `go test ./scripts/` PASS, `make lint` clean, oxlint clean. - Each fix was reviewed locally by Codex before pushing. Reviewed twice by Codex before opening (the four findings above plus two residual ones on the first fix, all addressed). ## Scope and deviations The three PR branches are merged unchanged (merge commits, then one fix commit); the only conflict was two bullets added to the same spot in `docs/README.md`, both kept. The Codex threads open on #1499 were addressed by its own follow-up commits (`df1b7e2e`, `96ad1806`) and verified here. Not done: square and smartlead catalog entries (SSE-only, a product/transport question per #1495); the catalogue is deployment-wide while the board is scoped, so no tag counts are shown (`docs/TASK-TAGS.md`). --- - [x] The title and "What changed, and why" are written for the release notes they become - [x] A design note (`docs/TASK-TAGS.md`) added, if this ships a feature - [x] An ADR added or superseded in `docs/adr/`, if this adds, weakens or reverses an invariant — none touched - [x] The diff is scoped to one change (no unrelated refactors) — three related changes consolidated deliberately, see above 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Kristian Yendrek <yendrek.kristian@gmail.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
|
Superseded by #1501, which merges this branch (merge commit |
This was referenced Sep 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed, and why
Docs only — the record #986 and #1006 asked for.
docs/MCP-CATALOG-STATUS.md— the status table for the manual OAuth pack: twelve hosted connectors exercised against real vendor accounts on a local rig (add, consent, tools list, tool call from chat, scheduled task, refresh, sign-out, seats and sharing), each with a verdict, the fleet PR it needed, and the date it was last verified. Then the cross-cutting checks (seats, sharing, headless refresh, deferred mode), the fourteen fleet PRs the pack produced, the catalog-audit findings with their disposition (F1–F12, C1–C9, V1–V3 — including the items deliberately skipped, named as skipped), and an appendix of all 231 official OAuth/tenant/open entries re-probed on 2026-09-14 with fleet's ownmcpoauth.Discoveragainst the catalog as of #1495: 177 discover cleanly, 31 tenant entries cannot be probed without a customer value, 12 open entries answerinitialize, 7 still fail (four answer 403 to every unauthenticated request from the audit network; Plaid and Intercom are refused onmainsince #1485's final form; Bugsnag advertises its metadata pointer over plain http — new, F12).docs/HOSTED-CONNECTORS-RUNBOOK.md— what an operator needs before and after Connect: how the callback URL is derived fromFLEET_PUBLIC_BASE_URLand which vendors refuse plain http (Slack: HTTPS; Entra:localhostonly); whatFLEET_MCP_OAUTH_ENCRYPTION_KEYprotects; the three shapes of Connect and why a client secret and a user login are both needed; measured per-vendor prerequisites (GitHub, Google Workspace, Slack, Notion, Linear, Azure DevOps, Stripe, Grafana Cloud, Uptime Robot, Plaid, Intercom, Square, Smartlead); how chat and scheduled runs mount connections, seats and sharing; how to read thefleet.loglines and the Add-time andAADSTSerrors; what to check before listing a vendor in the directory.Both pages are indexed in
docs/README.md(a "By question" entry plus the two "All pages" rows). Live results and discovery-only probes are kept apart throughout, per the honesty-in-docs rule.How I verified it
go test ./scripts/ -run TestDocsIndexIsComplete— green.mcpoauth.Discover+ add-time guards, 231 entries, 2026-09-14) rather than typed by hand; the live-run rows come from the rig's database rows,fleet.logand chat transcripts recorded during the pack.Scope and deviations
🤖 Generated with Claude Code