Repository navigation
Commit 75abd91
docs(adr): ADR-0143 — outbound connector auth is open tier: OAuth2 grants, vendor app-credential exchange and request signing in one declarative auth contract (#26833)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9BaU5Bf8FsJVKEf1GxktFtv)_
Refs #26768
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:新增
ADR-0143(Proposed),把出站连接器认证整体放进开源层:OAuth2(authorization_code+PKCE+刷新、client_credentials)、飞书/钉钉/企业微信应用凭证换
token、请求签名 `signed`(封闭方案枚举);并在 ADR-0015/0018/0022/0023/0024/0097
追加带日期的修订注记(只追加,不改写原文),重新生成 ADR 索引。
- 为什么改:落实「OAuth 放开源层,先起草 ADR 修订」和「建议 1+2立卡」;#26702、#26710 的
spec/运行时/控制台切片都卡在这份记录上。
- 风险与回滚:纯文档,无代码、无 spec 变更;四个决定未答前不应合并。回滚即撤掉本 PR。注意 ADR-0015 原文其实从没划过
OAuth/企业版这条线,注记里如实写明。
- 先看:① `docs/adr/0143-outbound-connector-auth-is-open-tier.md`
的「Decisions put to the maintainer」四问(Q1 连接归属与执行身份、Q2 存储复用 better-auth
account 还是独立连接对象、Q3 首批产品、Q4 首批签名方案);② 同文件 D1(哪些从企业版移出、哪些不动);③
`docs/adr/0097-declarative-connector-instances.md` 两条注记。
- 两分钟验证:`pnpm check:adr-symbol-anchors && pnpm check:adr-index`,预期两条都 0
退出、无 0143 相关告警。
- 需要你做的:在 ADR 里回答四个决定并批准
## What changes
- **New `docs/adr/0143-outbound-connector-auth-is-open-tier.md`**
(Proposed). It decides, in one record:
- D1, the tier move: outbound connector auth is open tier. Vault
backends, curated or paid catalogs, marketplace and sandboxed stdio keep
their placement.
- D2, three closed authored variants: `oauth2` (`authorization_code`
with mandatory S256 PKCE and refresh, `client_credentials`, MCP
authorization discovery), `app-credential` (`feishu` / `dingtalk` /
`wecom`) and `signed` (a closed scheme enum; a member enters only with
its signer and vendor vectors).
- D3: secrets stay `credentialRef`, and tokens live in an encrypted
connection record, never in metadata.
- D4: grant-bearing kinds resolve per dispatch, refreshing on expiry and
once on a 401 with single-flight refresh. A revoked grant degrades the
instance with a reason and never fails boot.
- D5: a server-side Connect flow. D6: a grant is never a sign-in method.
D7: the unused runtime `ConnectorOAuth2Schema` goes to the spec slice
under ADR-0087.
- The four maintainer decisions are stated as open questions, each with
options and a recommendation, and none is decided: Q1 connection
ownership / execution identity (rec. organization-shared), Q2 storage
(rec. a dedicated connection object, with measured reasons `sys_account`
does not fit), Q3 first products (rec. HubSpot MCP, Feishu, Alipay v3
sandbox), Q4 first signing schemes (rec. `alipay-rsa2`,
`aliyun-acs3-hmac-sha256`, `tencentcloud-tc3-hmac-sha256`).
- **Dated, append-only amendment notes** (each adds an `**Amended by**:`
header line and a blockquote; no existing line changes):
- ADR-0015: attribution only. It never drew the split others cite it
for.
- ADR-0018 "Out of scope (deliberately not baseline)": where the
connector line was first drawn.
- ADR-0022 §4: the connector half moves. The `sys_channel_account`
lifecycle does not.
- ADR-0023 §4.
- ADR-0024 §3–§4.
- ADR-0097 §3 and its "Open / enterprise line".
- **`docs/adr/README.md`**, regenerated by `node scripts/adr-index.mjs`
(one new row and the summary counts).
- Forced test edits: none.
## Tests
Docs-only diff; no package touched, so no build closure, unit test or
typecheck is owed. The derived ADR gate family ran on the final head
(see Verification).
## Acceptance notes
- **Governing text, re-checked on `origin/main` at `0ea90c7a`.**
- `git grep -n "deliberately omits OAuth2" origin/main --
docs/adr/0097-declarative-connector-instances.md` matches line 119: "The
open tier deliberately omits OAuth2 from `ConnectorInstanceAuthSchema`."
- `git grep -n "intentionally absent" origin/main --
packages/spec/src/shared/connector-auth.zod.ts` answers **nothing**, but
the sentence is still in the file: it wraps across lines 113-114
("OAuth2 is intentionally" / "absent (enterprise tier, ADR-0015)."). A
one-line grep cannot match it. The ADR says so and names which surface
each schema serves: `ConnectorOAuth2Schema` (L30-40, inside the runtime
union `ConnectorAuthConfigSchema` L79-85) vs
`ConnectorInstanceAuthSchema` (L158-163, authored, four static kinds).
- **file:line readings behind the ADR's citations** (at `0ea90c7a`). The
ADR itself cites `path#symbol`, because `check:adr-symbol-anchors`
refuses line anchors in `docs/adr/**`.
- `connector-auth.zod.ts`: L35 and L38 inline `clientSecret` /
`refreshToken`; L99-102 `ResolvedConnectorAuth`.
- `credential-resolver.ts`: L12, L21-22.
- `service-automation/src/plugin.ts`: L1955 resolver pick, L1997 resolve
at materialization, L2306-2337 `resolveInstanceAuth` (static kinds
only).
- `connector-mcp/src/mcp-provider.ts`: L63-79 `applyAuthToHeaders`,
L115.
- `connector-openapi/src/openapi-connector.ts`: L52 and L88-93
(`securitySchemes` typed, never read), L365 `applyAuth`.
- `connector-rest/src/rest-connector.ts`: L89.
- `integration/connector.zod.ts`: L1168-1192
`DeclarativeConnectorEntrySchema` (inline-secret refusal).
- `sys-account.object.ts`: L183-187 (`user_id` required), L236-255
(token columns `textarea` + `internal`, not `secret`).
- `auth-schema-config.ts`: L124 `AUTH_ACCOUNT_CONFIG`.
- `auth-plugin.ts`: L557 `socialProviders`.
- `auth-manager-plugin-list.ts`: L478-488 (oauth-provider).
- `connector-imap/src/account.ts`: L60, L68-69
(`MailCredentialProvider`).
- **Premise finding.** ADR-0015 contains neither "OAuth" nor
"enterprise" (`grep -c -i enterprise` = 0). The enterprise placement was
first drawn for connectors by ADR-0018 line 229, then repeated by 0022,
0023, 0024 and 0097. The ADR-0015 note therefore corrects the
attribution and changes no decision.
- **ADR-0018 line 229** also places "OAuth2 token refresh" in the
enterprise tier. The seat's claim amendment 6449956947 added that file
to the surface, so it carries the sixth note, and ADR-0143 lists it
under Amends.
- **Not in this PR:** card item 3, the cloud-repository record with a
`## Provenance` pointer. This lane cannot reach the cloud repository.
ADR-0143's Provenance section records that the boundary was only ever
drawn in this repository (no `cloud ADR` citation in any of the six
records) and that the cloud record is owed.
- **Tier H.** This PR is a draft and waits for an approval from an
account in `GOVERNED_APPROVERS`. The seat does not ready it, arm
auto-merge or enqueue it.
## Verification
<details><summary>Derived gate family, final head 6948496: 21/21 exit
0, --ran reconciles 21/21, 0 NOT-MEASURED (derived zero)</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` (no paths): 8 paths, 440 changed lines
(under the 3000 threshold), 21 commands. Each one ran on `69484961`,
with exit codes captured before any pipe:
```
0 | node scripts/check-adr-links.mjs
0 | node scripts/check-adr-links.mjs --self-test
0 | node scripts/check-closing-keyword-parity.mjs
0 | node scripts/check-closing-keyword-parity.mjs --self-test
0 | node scripts/check-comment-mask-corpus.mjs
0 | node scripts/ci/plan-test-core-shards.mjs --self-test
0 | pnpm --filter @objectstack/lint run check:doc-formula-expressions
0 | pnpm check:adr-anchors
0 | pnpm check:adr-index
0 | pnpm check:adr-symbol-anchors
0 | pnpm check:ci-filter-parity
0 | pnpm check:closed-ceremony-text
0 | pnpm check:cross-package-test-inputs
0 | pnpm check:doc-authoring
0 | pnpm check:driver-memory-census
0 | pnpm check:gitlink-declared
0 | pnpm check:nul-bytes
0 | pnpm check:pm-governed-merges
0 | pnpm check:pm-prior-rulings
0 | pnpm check:refd-timer-probe
0 | pnpm check:watch-hint-literal
```
`--ran` (each line `command :: exit N`): "21 derived famil(ies)
accounted for — 21 run, 0 NOT-MEASURED (a DERIVED zero — all 21 recorded
an exit code and none of them is 3)".
First-pass history:
- On `a8384e3b`, `check:adr-symbol-anchors` was red with 24
`[line-anchor]` findings in ADR-0143. They were fixed in `c965eb87` by
moving to `path#symbol`.
- `69484961` adds the ADR-0018 note (seat review round 1); the same 21
commands re-ran there, all exit 0.
- `check:doc-formula-expressions` first exited 3 (prerequisite not met,
nothing measured). It went green after `pnpm exec turbo run build
--filter=@objectstack/formula --filter=@objectstack/lint` under
`os-verify-lock.sh` (VERDICT command-exit 0).
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmP2wqmTYar443bTqhK)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 17b5152 commit 75abd91
8 files changed
Lines changed: 437 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
7 | 16 | | |
8 | 17 | | |
9 | 18 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
| |||
228 | 229 | | |
229 | 230 | | |
230 | 231 | | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
231 | 240 | | |
232 | 241 | | |
233 | 242 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
| |||
113 | 114 | | |
114 | 115 | | |
115 | 116 | | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
116 | 126 | | |
117 | 127 | | |
118 | 128 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
| |||
116 | 117 | | |
117 | 118 | | |
118 | 119 | | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
119 | 127 | | |
120 | 128 | | |
121 | 129 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
| |||
113 | 114 | | |
114 | 115 | | |
115 | 116 | | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
116 | 126 | | |
117 | 127 | | |
118 | 128 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| 8 | + | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
| |||
70 | 71 | | |
71 | 72 | | |
72 | 73 | | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
73 | 82 | | |
74 | 83 | | |
75 | 84 | | |
| |||
118 | 127 | | |
119 | 128 | | |
120 | 129 | | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
121 | 144 | | |
122 | 145 | | |
123 | 146 | | |
| |||
0 commit comments