Repository navigation
connectors: outbound OAuth in the open tier — connection-scoped authorization-code / client-credentials / app-credential tokens, refreshed per dispatch, for the openapi, mcp and rest providers #26702
Description
Unblocked (triage, 2026-10-30): ADR-0143 is Accepted on main (PR #27231); #26768's only open item is the cloud mirror record (objectstack-ai/cloud#3350), which gates no code in this repo.
Filing-gate category: ③ maintainer-directed task.
Maintainer ruling (verbatim, not translated)
OAuth 放开源层,先起草 ADR 修订
平台基于 better-auth ,怎么会有没有 oauth
创建issue 就行
The first line moves the boundary. The third replaces the ADR draft with this card. The ADR revision is still owed and is listed under "Work" below.
Business reason
Who benefits: app builders whose flows and agents must act in the SaaS their customers already run. That means Salesforce, Slack, HubSpot, Jira/Confluence, Notion, Asana and Stripe abroad, and Feishu, DingTalk and WeCom at home.
Scenario: an AI-authored app declares a connector instance as metadata. An admin clicks "Connect" once. A flow's connector_action step then calls the vendor on every run without anyone pasting tokens into env vars.
Without it: the connector layer reaches only APIs that accept a static key. A survey of the vendors' own channels found that the common products now ship their integrations as hosted MCP servers that require OAuth. The same survey found the Chinese suites issue short-lived tokens from app credentials. Neither shape is reachable today, so the "integration-heavy enterprise core system" the platform targets stops at the long tail.
| Product | Vendor channel found | Auth it requires |
|---|---|---|
| Salesforce, Slack, HubSpot, Atlassian, Notion, Asana | official hosted MCP server | OAuth (HubSpot: OAuth 2.1 + PKCE) |
| Stripe | stripe/openapi (MIT, OpenAPI 3) + hosted MCP |
static key for the spec path; OAuth for MCP |
| Feishu | official lark-openapi-mcp (MIT, beta) |
App ID/Secret → tenant_access_token (~2 h) |
| DingTalk | official open-dingtalk/dingtalk-mcp + MCP square |
AppKey/Secret → access token |
The bulk-catalog alternatives were measured and rejected for this goal; the numbers are in the session analysis. For example, microsoft/PowerPlatformConnectors has 1187 definitions, and 766 of them convert with createOpenApiConnector. None of the mainstream products above is among them: those connectors are closed-source, and the ones present are in the OAuth tier.
Current state (read at 71a4b4ea)
Inbound OAuth exists; outbound connector OAuth does not. better-auth already gives the platform three things:
- sign-in OAuth (
socialProviders,packages/plugins/plugin-auth/src/auth-plugin.ts); - an authorization server for MCP clients (
@better-auth/oauth-provider, mapped inauth-schema-config.ts); - a user
accounttable that storesaccess_token/refresh_token/access_token_expires_at.
Nothing on the connector side uses any of it:
ConnectorInstanceAuthSchema(packages/spec/src/shared/connector-auth.zod.ts) isnone | bearer | api-key | basic. Its header says "OAuth2 is intentionally absent (enterprise tier, ADR-0015)".ConnectorOAuth2Schemaexists as a runtime shape, but no provider consumes it.credentialRefis resolved once, at materialization (ADR-0097 §3;defaultEnvCredentialResolverreads env vars). A token that expires has no refresh point.- The
connector-mcphttp transport sends only static headers (mcp-provider.ts,applyAuthToHeaders). It cannot perform the MCP authorization flow: protected-resource discovery, dynamic client registration and PKCE. connector-openapimaps only static schemes. Anoauth2securitySchemesentry is dropped.
Work (each item is a slice; the ADR comes first)
- Governance. Write a successor ADR in this repo that moves outbound connector OAuth into the open tier. Amend the status lines of ADR-0015, ADR-0022, ADR-0023, ADR-0024 and ADR-0097 where they place OAuth2 in the enterprise tier. Per AGENTS.md Prime Directive 13, the boundary half also needs a
cloud ADR-NNNNrecord with a## Provenancepointer from here. Both are Tier H governed surfaces, so the maintainer lands them. - Connection record. Store per-connection grants with tokens encrypted at rest, never in metadata. Org-scoped by default; the ADR decides whether per-user connections exist. Design fork for the ADR: reuse better-auth's
accountstorage and refresh, or keep a separate connection object. A linkedaccountis also a sign-in method, which an integration grant must not become. - Grant types.
authorization_code+ PKCE + refresh;client_credentials;- vendor app-credential exchange (Feishu / DingTalk / WeCom), non-interactive.
- Resolve per dispatch, not at boot. The
CredentialResolverseam answers with a live access token, refreshing on expiry or on a 401 once. This is a change to the ADR-0097 contract. - Authoring contract (
packages/spec).ConnectorInstanceAuthSchemagains anoauth2variant: endpoints,clientId,credentialReffor the client secret, scopes and grant type, and a reference to the connection. Inline tokens or secrets are refused at publish, as today. - Providers.
mcp: the MCP authorization flow on the http transport.openapi: mapoauth2securitySchemes.rest: accept the oauth2 variant.
- Console. Add a "Connect / Reconnect" flow and a connection status view, so a
degradedinstance (ADR-0097, upstream-unavailable) names an expired or revoked grant. This is aui/follow-up.
Decisions the successor ADR must put to the maintainer
- Connection ownership and execution identity. Org-shared connection vs per-user connection, and whose grant a flow run uses (ADR-0073).
- Storage. Reuse better-auth
accountstorage, or a dedicated connection object. - First products. Which products the first acceptance targets.
Acceptance (to be pinned by the ADR)
- A declarative
provider: 'mcp'instance pointing at an OAuth-protected vendor MCP server is authorized once from the Console. A flowconnector_actiondispatches end to end. After the access token expires, the next dispatch refreshes it with no operator action. - A Feishu (or DingTalk) instance declared with app credentials dispatches through the
openapiorrestprovider. Its token renews without restart. - No token or client secret appears in
sys_metadata, inGET /api/v1/automation/connectors, or in logs.
Out of scope
- Curating which actions each product exposes. That is a separate catalog card once auth lands.
- Bulk import of third-party catalogs.
Who acts
- The
domain:skillsseat drafts the successor ADR, which the maintainer lands (Tier H). - The
domain:serverseat then takespackages/connectors/*,packages/services/service-automationandpackages/plugins/plugin-auth. Thepackages/specauth variant is aSeam:for thedomain:specseat. The Console flow goes todomain:ui.
Triage assigns the final lanes.
Duplicate check
Semantic issue search on objectstack-ai/objectstack, open and closed:
| Query | Hits | Relevant |
|---|---|---|
| "connector OAuth2 authorization code refresh token connection credential" | 0 | — |
| "credentialRef vault CredentialResolver token exchange client credentials Feishu DingTalk" | 0 | — |
| "connector oauth" | 4 | none — all inbound MCP-server OAuth (25118, 24166, 24137, 21885) |
| "MCP connector remote server OAuth client authentication" | 12 (10 returned and read) | none — all inbound: our MCP server and better-auth as authorization server, e.g. 20791, 25118, 24137 |
No card covers outbound connector OAuth.
Generated by Claude Code
Activity
objectstack-fleet commentedon Oct 27, 2026
Triage: first grade —
enhancement·security·priority:p1·domain:server·area:api·pm:queue· triage seat ·session_01AavokzJ5DndAwitDXvKy4U· 2026-10-27T14:12Z⛔ Not a claim, ⛔ not a dispatch.
security: outbound OAuth in the open tier (connection-scoped tokens, refreshed per dispatch) moves the open/enterprise boundary, which the maintainer ruled (「OAuth 放开源层」). New connector auth kinds are protocol additions. Under [Decision] Triage priority caliber for protocol additions: keep 「协议新增定 p1」 for every addition, or grade additions an app asks for at p2 unless a release needs them #26368 ruling A, every protocol addition is p1. Handled directly in 18.x. Skills, docs and eval are owed ([Decision] pm-dispatch: which PRs owe aSkills-docs:line (the #26184 audit Part B rule draft) — protocol-kind only, protocol-kind plus narrowing, or not adopted #26369 B). The ADR revision is owed first and is Tier H. Token storage stays encrypted at rest, and refresh failures are loud. ⛔ No token in logs or errors (skills: five principle gaps the #9296 wave exposed in checklist-test / checklist-author / dogfood-verification #9387 applies to the PR text).Generated by Claude Code
objectstack-fleet commentedon Oct 27, 2026
pm:queue→pm:blocked·domain:serverseat 3 ·session_01QSeKYmQXM3rHJcPnrEPk4B· 2026-10-27T15:09ZBlocked-by: #26768
docs/adr/**, Tier H) thedomain:skillsseat drafts and the maintainer lands. Every server slice (connection record, grant types or signers, per-dispatch resolve, providers) implements decisions that record has not made yet, so nothing here is dispatchable by the server lane today.carries item 1 of #26702 and item 1 of #26710), so one record decides OAuth2, the app-credential exchange and request signing together, as connectors: request-signing auth kind for the openapi and rest providers (RSA2 / HMAC canonical-request signers: Alipay, WeChat Pay, Aliyun, Tencent Cloud, e签宝) — the vendor-auth half that #26702 does not cover #26710 asked. This card keeps its other items unchanged; its grade and labels stay.pm:queue; re-read its premises against the merged record before claiming.objectstack-fleet commentedon Oct 28, 2026
Part of #27293 (E1 platform prerequisites) · 2026-10-28T14:59Z
Epic link on the maintainer's ruling 「是否建议立专题卡统一处理。」→「同意」 (2026-10-28,
session_01J8VVAjRKqdoEYQ4hXxtBuf). Role in the chain: the outbound OAuth variant that admits the OAuth-protected half of E4 (Microsoft Graph, Notion, Atlassian, Google, DocuSign); its successor ADR also carries #26710's signing decision. Lane claims and dispatch proceed as triage set them; the epic PM seat (epic:#27293) tracks this card and reserves only what it drives in order. ⛔ Not a claim.Generated by Claude Code
objectstack-fleet commentedon Oct 28, 2026
epic:#27293#1 · sunhaolin · session_017xRBcVBKAFk1ntXSjvPt7U
Reserved for the epic subtree · 2026-10-28T15:12Z —
pm:epicadded;pm:blocked(Blocked-by: #26768) unchanged.The maintainer in
session_017xRBcVBKAFk1ntXSjvPt7U, 2026-10-28, verbatim: 「有很多子卡,这是没有挂到子任务,你应该处理。」 This card is attached under #27293 and now carriespm:epic: other seats' candidate reads skip it; the epic PM claims it with the full claim protocol when it dispatches. ⛔ Not a claim, ⛔ not a dispatch.objectstack-fleet commentedon Oct 29, 2026
triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U
Path: 可对外的 API | none | P②
Triage: unblocked · p1 kept ·
domain:server· 2026-10-29T04:01Z⛔ Not a claim.
main(PR docs(adr): ADR-0143 accepted — the maintainer's Q1–Q4 decisions recorded; D2.1, D2.3, D3, D4 and D7 state what they settle #27231,d745bb5e, Q1–Q4 answered).## Provenancepointer (cloud#3350, PR cloud#3354, waiting on review). That record restates ADR-0143 for the cloud tree, and nothing in this card's open-tier code waits on it.pm:blocked→pm:queue, with p1 kept. The PR cites ADR-0143.connector-tiering.md), triage puts this card back on hold.Generated by Claude Code
49 remaining items
objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
ACCEPT → PR #28598 comment 6555280321 · head
d21e1bac· 2026-11-01T08:02Z · landing sent (ready + auto-merge).Part of: after the merge this claim is released and the card goes back for item 7 (Console). Filed from the review: #28614.objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
Landing record · #26702 · PR #28598
domain:serverseat 3 ·session_01FEkQ5kE5BrPUPNMMyv6oCH· 2026-11-01T08:25Zgit ls-remote origin 'refs/heads/gh-readonly-queue/main/pr-28598-*'git merge-base --is-ancestor 479ad08f origin/maingit grep -c holdConnectorForRefusedConnection origin/main -- packages/services/service-automation/src/plugin.ts479ad08f. When anmcpconnector instance (oauth2authorization code) is refused at tool discovery on the token it borrowed from the discovery organization's connection (ruling B6545215904), the refusal now marks that connectionreconnect_requiredinstead of marking the instance's client secretrejected. The instance falls over to the next connected organization, or holds as reconnect-required, and lists tools again as soon as that organization reconnects.client_credentials,app-credential) still mark the client secret.domain:ui), per landing record6546456165. Triage routes it.Release: claim
6554662603(session_01FEkQ5kE5BrPUPNMMyv6oCH, card threadsession_01FEkQ5oviX44TJs1t5J5G1S, branchclaude/project-thread-l5g8ho) · server half landed.pm:dispatched→pm:queue, assignee cleared.mainat479ad08for later.objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
Claim: PM loop round 1 · card thread · 2026-11-01T10:23Z
Session:
session_01FEkQ5kE5BrPUPNMMyv6oCH(the seat); the card thread issession_01FEkQ5pbcbVpMJpa91SdWu3Account:
os-project-manager(the seat's linked user; the card's assignee)Branch:
claude/project-thread-203pk8(the card thread's harness-pinned branch; it names no issue, so this claim is the identity record)Worktree: the card thread's own container checkout
Domain:
domain:serverSeat:
domain:server#3Ruling-ref: the maintainer, 2026-11-01T03:46Z: 「server 车道现在就是你负责,任务有一大堆啊,都可以派,包括 p3」, with 2026-10-26T10:29Z 「p1 p2 处理完了,就可以处理 p3」, and 2026-11-01T06:39Z 「server 队列还是很多任务,再开一个席位吧」. Leehom 2026-11-01T10:18Z: every graded
pm:queue+domain:servercard is dispatchable. Item 7 of this card (ui/), the server slices are landed. Ruling B6545215904binds. Security discipline: no secret or code value rendered or logged; no provoking recipe on public surfaces.File surface: the Console connector-connection surface (
ui/packages/app-shell,ui/apps/console: the connection status view and the Connect / Reconnect action over the server routes already served), the i18n bundles, tests, and changesets for the shippedui/packages. ⛔ Notpackages/spec; ⛔ no new server route.Container & model:
L(p1,security),mode:thread,model: opus(--tiernames no path mandate: PM's call, default),effort: xhighClause-②: no — the Console reads and drives connection status and authorize routes the server already serves; a missing server piece is a stop-and-report.
Metadata-protocol: none (expected; the dev measures and declares)
Responsibility: the code is the Console connector-connection pages · the platform path is the connection record (
reconnect_requiredsince PR #28598) and the oauth2 authorization-code routes · reached by an org admin whose connection grant expired or was revoked and who today cannot reconnect from the ConsoleThread-read: 6555521703
Premise: item 7 is open: no Console Connect / Reconnect flow or connection status view exists (landing records 6546456165, 6555521703); the dev inventories the served surface first
Serial constraints cleared: none: no open PR found on the Console connection pages at this read; the dev re-reads overlap at start and before
pr_create.Resume-from: none — fresh from
origin/mainState: →
pm:dispatched, assigned toos-project-manager, recorded by this claim. Order:pm-orders/server/order-26702.md(project folder).objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5pbcbVpMJpa91SdWu3
os-dev-report
{
"issue": 26702,
"status": "done",
"branch": "claude/project-thread-203pk8",
"pr": "#28651",
"session": "session_01FEkQ5pbcbVpMJpa91SdWu3",
"premise_still_valid": true,
"summary": "Item 7, the Console half: a new Setup page automation:connector-connections (ui/packages/app-shell) lists every declared oauth2 authorization_code connector instance with the organization's connection status (not_connected / connected / reconnect_required + statusReason), scopes, connectedAt/By and token expiry, and shows a degraded instance's degradedReason beside the connection that caused it. Connect / Reconnect open the sign-in window on the click, clear its opener, send it to the authorizationUrl the server answered (http(s) only), and re-read the status until the connect lands, the window closes or the begun connect expires; Disconnect revokes behind a confirmation. No spec edit, no server change; the Connector Credentials page links to the new page. Part of #26702: the Setup nav entry naming the page for an org admin is a service-automation UI-bundle item outside this claim (open_questions).",
"tests": "head 5986e26. cd ui && pnpm exec vitest run packages/app-shell/src/views/setup/ConnectorConnectionsPage.test.tsx: Test Files 1 passed, Tests 11 passed (red on main: the module does not exist). Neighbours: vitest run packages/app-shell/src/views/setup/ packages/app-shell/src/tests/ packages/app-shell/src/services/: 48 files, 719 tests passed; vitest run packages/i18n/: 94 files, 1438 passed, 13 skipped (all-locales key parity included). Typecheck: ui/packages/app-shell pnpm run type-check exit 0, 0 errors (after building the @object-ui/app-shell^... closure); ui/packages/i18n type-check exit 0. eslint --no-inline-config on the four touched app-shell files: exit 0. Ablations via scripts/ablation-replace.mjs on 5986e26 (relative source import, no dist hop): signIn.opener = null removed -> 'opens a detached window...' red, 1 failed 10 passed, restored blob == HEAD; the http(s) protocol check neutralised -> 'an authorization URL that is not http(s) is never navigated to' red, 1 failed 10 passed, restored blob == HEAD, git diff HEAD empty.",
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on the real diff: 66 families, each run on final head 5986e26 with the exit code captured before any pipe: all 66 exit 0. --ran: 66 run, 0 NOT-MEASURED (a DERIVED zero). First pass at 8538b11: check:skill-examples exited 3 (own refusal, stale @objectstack/client-react dist), 0 after building that package. Record: pm-orders/server/26702-item7-gates-ran.txt. pnpm lint scoped: eslint on touched files exit 0. CI check-runs on PR 28651: in_progress at report time (not waited on).",
"dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm",
"line_budget": "1294 added lines (0 removed) in 17 files: about 600 product code (ConnectorConnectionsPage.tsx, connectorConnections.ts, registration, link), 370 i18n (32+2 keys x 10 packs), about 250 tests, 10 docs, 1 changeset. Over the order's ~600 guide; not split because a status view without Connect would name a broken grant with no fix.",
"deviations": [
"Size over the ~600-line guide, kept as one PR (see line_budget).",
"No live dogfood probe: the showcase declares no authorization_code instance and a connect needs a vendor authorization server; the server door stays pinned in domains/automation-connector-connection-door.test.ts.",
"No labels sent with pr_create: the order names none and the diff ships packages (changeset present, so no skip-changeset)."
],
"files_changed": [
".changeset/26702-console-connector-connections.md",
"content/docs/automation/connectors.mdx",
"ui/packages/app-shell/src/services/builtinComponents.tsx",
"ui/packages/app-shell/src/views/setup/ConnectorConnectionsPage.test.tsx",
"ui/packages/app-shell/src/views/setup/ConnectorConnectionsPage.tsx",
"ui/packages/app-shell/src/views/setup/ConnectorCredentialsPage.tsx",
"ui/packages/app-shell/src/views/setup/connectorConnections.ts",
"ui/packages/i18n/src/locales/ar.ts, de.ts, en.ts, es.ts, fr.ts, ja.ts, ko.ts, pt.ts, ru.ts, zh.ts"
],
"mcp_calls": "1 — mcp__github__issue_read (get #26702); no write tool",
"api_writes": "2 — relay pr_create (POST /repos/objectstack-ai/objectstack/pulls, run 41303142989) and this os-dev-report comment (POST /repos//issues/26702/comments); git push is not a REST write",
"open_questions": [
{
"question": "Who adds the Setup navigation entry that shows the new page to an organization administrator? Setup entries are contributed by server UI bundles; the only nearby one, Connector Credentials, is gated on manage_metadata, which the org-admin set does not hold, while the connection door asks manage_connector_connections, which it does. Today the page is reached from the Connector Credentials link or its URL.",
"options": [
"A: a small domain:server follow-up on this card: one nav item in packages/services/service-automation/src/connector-credentials-ui.ts (componentRef automation:connector-connections, requiredPermissions manage_connector_connections, group_integrations), with its bundle test; then #26702 can close",
"B: re-claim this branch with the service-automation file added to the surface and fold the nav item into PR 28651",
"C: leave the page reachable only from Connector Credentials (platform admins), and close #26702"
],
"recommendation": "A, because the entry is a server-owned declaration (the nav lives and dies with the capability, the same shape as Connector Credentials), it keeps this PR inside its claim, and C leaves the org admin the capability ruling B on the capability's card gave them with no way to reach the page."
}
],
"out_of_scope_findings": [
"carrier: #26702 (the seat) · noted, not filed: the OAuth callback answers JSON in the sign-in window rather than redirecting back to the Console; the page works around nothing (it watches the status), but a refused callback leaves the administrator a JSON refusal in that window. A redirect-back would be a server change; recorded in the PR Acceptance notes only."
]
}
Generated by Claude Code
objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
Claim amendment to
6556683327· 2026-11-01T11:47Z · file surface increment, declared (seat ruling on the dev's open question, os-dev-report6557489910)packages/services/service-automation/src/connector-credentials-ui.ts(componentRef: automation:connector-connections,requiredPermissions: manage_connector_connections, the integrations group), with its bundle test. Grounds: one declaration line plus its test, same card item, and it lets the PR deliver all of item 7, so the card closes with it.packages/services/service-automation/src/connector-credentials-ui.tsand its UI-bundle test, and the@objectstack/service-automationchangeset line. Still ⛔ notpackages/spec, ⛔ no new route.Fixes #26702(item 7 was the card's last open item).Clause-②: nostays unless the nav item's gate measures otherwise.objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
Claim amendment to
6556683327· 2026-11-01T12:40Z · second file surface increment, declared, and the Clause-② line73a1b466):packages/platform-objects/src/apps/translations/{en,es-ES,ja-JP,zh-CN}.ts(check:app-nav-i18n), with apatchchangeset line for@objectstack/platform-objects;packages/cli/test/setup-integrations-order.pin.test.ts(the service-automation tier is nownav_connector_credentials,nav_connector_connections).nav_connector_connectionsis a new contributed navigation item, which measures the same as the Connector Credentials entry did (changeset of console: Setup → Integrations → "Connector credentials" page and the install dialog credential prompt (ruling A on #27230) #27238 declaredyes (widening)). No existing key, route or shape changes. Owed review:TIER_DEFAULT, by this seat in its ACCEPT (no spec path, no narrowing, no governed rule text).packages/spec, ⛔ no new route. Closing line:Fixes #26702.objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
ACCEPT → PR #28651 comment 6558341999 · head
0537d24f· 2026-11-01T13:06Z · landing sent (ready + auto-merge;Clause-②: yes (widening), non-spec, seatTIER_DEFAULTreview inside the ACCEPT).Fixes #26702: item 7 is the last open item, so the merge closes this card.objectstack-fleet commentedon Nov 1, 2026
domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH
Landing record · #26702 (item 7) · PR #28651
domain:serverseat 3 ·session_01FEkQ5kE5BrPUPNMMyv6oCH· 2026-11-01T13:25Zgit ls-remote origin 'refs/heads/gh-readonly-queue/main/pr-28651-*'git merge-base --is-ancestor da46b2af origin/maingit grep -c nav_connector_connections origin/main -- packages/services/service-automation/src/connector-credentials-ui.tsda46b2af;Fixes #26702closed the card (item 7 was its last open item). Setup → Integrations → Connector Connections (gated onmanage_connector_connections) opens the Console page that shows each OAuthauthorization_codeconnector instance's connection status and drives Connect / Reconnect / Disconnect.mainatda46b2afor later.