feat(spec): signed connector instance auth, with aliyun-acs3-hmac-sha256 signing every request (ADR-0143 D2.3, slice 1 of #26710) - #28273

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/connector-openapi, @objectstack/connector-rest, @objectstack/service-automation, @objectstack/spec, touching 50 documentable anchor(s). ⚠️ 7 changed file(s) yielded no anchor (packages/spec/api-surface/integration.json, packages/spec/authorable-surface/integration.json, packages/spec/declaration-map/integration.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/connectors.mdx (via accessKeySecret (symbol, a field of const object SIGNED_GUIDANCE), privateKey (symbol, a field of const object SIGNED_GUIDANCE), requestSignerApplied (symbol, a field of interface ConnectorMaterialization), secretKey (symbol, a field of const object SIGNED_GUIDANCE), keyId (literal, a string literal in ConnectorInstanceSignedAliyunAcs3AuthSchema))
• content/docs/plugins/index.mdx (via keyId (literal, a string literal in ConnectorInstanceSignedAliyunAcs3AuthSchema))
• content/docs/protocol/objectql/security.mdx (via keyId (literal, a string literal in ConnectorInstanceSignedAliyunAcs3AuthSchema))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via DeclarativeConnectorEntrySchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ee460953535dfd33a91d881427d347b67e139170 && git checkout ee460953535dfd33a91d881427d347b67e139170
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 361ea242450cf22cbfd58c2aa21f12c0d5c0c9d1 8c6135c75d148c6ac914999f7656a33f57c264d3 && git checkout -B drift-repro 361ea242450cf22cbfd58c2aa21f12c0d5c0c9d1 && git merge --no-ff 8c6135c75d148c6ac914999f7656a33f57c264d3

node scripts/docs-audit/affected-docs.mjs --json 361ea242450cf22cbfd58c2aa21f12c0d5c0c9d1

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 361ea242450cf22cbfd58c2aa21f12c0d5c0c9d1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Contract-review-claim: session_016WV4czuTWNgKR22fKv7jia · head 8c6135c75d148c6ac914999f7656a33f57c264d3 · 2026-10-31T00:30Z

The lane seat runs the CONTRACT_REVIEW_TIER review this PR owes (Clause-②: yes, Metadata-protocol: added, packages/spec/src/** paths).

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8c6135c75d148c6ac914999f7656a33f57c264d3
Local-runs: probe — the ADR-0143 D2.3 vector rule is a byte-for-byte claim, so the PR's aliyun-acs3-hmac-sha256.ts (copied to the scratchpad, run with plain node --experimental-strip-types, no install, repo tree untouched) was run on the vendor's published worked example: hashed canonical request and signature match the vendor document's values, the bound signer answers a fresh nonce per sign(), and the canonical URL equals the vendor URL. Exit 0.
Scope: packages/spec/src/integration/connector-fetch-policy.ts, packages/spec/src/integration/connector-provider.ts, packages/spec/src/integration/connector.zod.ts, packages/spec/src/shared/connector-auth.zod.ts + packages/services/service-automation/src/plugin.ts, packages/services/service-automation/src/request-signing/{index,aliyun-acs3-hmac-sha256,clock}.ts, packages/services/service-automation/src/connector-credential-source.ts, packages/connectors/connector-rest/src/{rest-connector,rest-provider}.ts, packages/connectors/connector-openapi/src/{openapi-connector,openapi-provider}.ts, packages/spec/src/shared/resilient-fetch.ts (read, untouched), packages/spec/src/shared/strict-object.ts (read), .changeset/26710-signed-connector-auth-aliyun.md, content/docs/automation/connectors.mdx, packages/spec/variant-docs.json, scripts/adr-anchors/packages__services__service-automation__src__request-signing__index.ts.json, the regenerated packages/spec/{api-surface,export-origins,declaration-map,authorable-surface,json-schema.manifest}/integration.json and content/docs/references/**

① Derived judgments

• Accept set, authored metadata. ConnectorInstanceAuthSchema gains one member, { type: 'signed', scheme, keyId, credentialRef }: a union on scheme with one strictObject per scheme. ConnectorSigningSchemeSchema is ['aliyun-acs3-hmac-sha256'] only, and connector-auth-signed.test.ts pins the enum equal to the union's members. Q4 ruled A with three members; D2.3 says a scheme enters only with its signer and vectors, so shipping one member in S1 is the conforming reading, not a shortfall. Correct.
• Declared = enforced (ADR-0049). request-signing/index.ts switches on auth.scheme with default: const unsigned: never = auth.scheme; a second enum member without a case is a tsc error in service-automation (covered by Type Check · workspace). Correct.
• Publish refusals, all located. Unknown or missing scheme → invalid_union @ auth.scheme, naming the value and the shipped set; secret / privateKey / secretKey / accessKeySecret → unrecognized_keys @ auth with the credentialRef prescription (strict shape: every unknown key is refused, these four carry the prescription); authored signature refused; accessKeyId answered with keyId; signed on provider: 'mcp' → custom @ auth.type. Missing keyId / credentialRef → invalid_type at their path. Correct; each has a CONTROL accept on rest and openapi.
• Public surface widened only. New spec exports: ConnectorInstanceSignedAuthSchema, ConnectorInstanceSignedAliyunAcs3AuthSchema, ConnectorSigningSchemeSchema (+ types), ConnectorRequestSigner, ConnectorSignableRequest, ConnectorRequestSignature, ConnectorSignedResponse, ConnectorHttpResult, readConnectorResponse; optional third parameter on connectorFetchOptions; optional ConnectorProviderContext.requestSigner; optional ConnectorMaterialization.requestSignerApplied. ResolvedConnectorAuth unchanged (comment only). Without a signer connectorFetchOptions leaves fetchImpl untouched and readConnectorResponse is the former inline read of both HTTP connectors, so bearer / api-key / basic are byte-identical (CONTROL pins in both connector packages). Widening confirmed. (PR body's "two exports added" undercounts; api-surface/integration.json lists all of them, so the declaration of record is right.)
• The key never leaves the host. credentialRefOf reads signed.credentialRef like the static kinds; an unresolved reference takes degradeConnectorForCredential naming the reference before any factory is called (pinned); a resolved key is bound into the signer's closure, auth is undefined, and the context carries only the signer (pinned: the key is absent from the serialized context, from every call, from the descriptors). Factory errors pass through withoutCredentialThrown(credentialForms(credential.value)), which now covers the signing key; the signer's own errors never carry key text.
• Fail-closed on every path. A materialization without requestSignerApplied: true is closed and refused as a configuration fault (fatal at boot, logged and skipped on reload); mcp is refused at publish and, belt-and-braces, by the same host check; a third-party factory that ignores the member is refused the same way; lendRefusal answers a signed borrow with 422. Nothing dispatches unsigned.
• Per attempt, body as sent. The wrap sits on fetchImpl, which resilientFetch calls once per attempt in the URL + init form (resilient-fetch.ts line 140, untouched), so the wrapper's refusal of Request objects never fires for the built-ins; sign() chooses a new date and nonce on every call; the body is the JSON string the connector sends and is hashed as that string; the signer's canonical URL replaces the sent URL, so the bytes signed are the bytes sent. Pinned (503→200 signed twice, different nonces) and reproduced on the rest provider end to end.
• Vector. The vendor's published example (Alibaba Cloud "V3 request structure and signature", cited by source name in the test) is reproduced byte for byte at every intermediate; a wrong key yields a different signature. Confirmed by the vector run above.
• Generated artefacts are consistent with the schema (3 new schemas: references index 1566→1569, integration 18→21; export-origins, declaration-map, authorable-surface and the json-schema manifest each carry exactly the new names; the strict-object ledger count 23→24 for the one new strict shape). No hand-edit signature. variant-docs.json gains scheme:aliyun-acs3-hmac-sha256 pointing at connectors.mdx, which carries the "Request signing: signed" section; the ADR anchor for the registry names ADR-0143 and ADR-0049 with a teaching invariant; SYNC_ARCHITECTURE.md names the kind.
• Docs accuracy (connectors.mdx). Every statement checked against the code: fresh nonce and date per attempt; key bound at materialization and never handed over; 422 on borrow; responses verified when a scheme verifies; the signed header set for Aliyun; the three refusals and their paths; static + signer refused; the openapi remote spec URL fetched unsigned (loadOpenApiDocument takes deps.fetchImpl, not the signing options); third-party factory refused at boot without the acknowledgement. Accurate.
• Surface. All 36 files sit inside the amended claim (6535175098) and the plan's S1 list; resilient-fetch.ts, connector-mcp, inbound auth, OAuth2 machinery and skills/** are untouched. Nothing outside the claimed surface.

② Semver level

• minor on @objectstack/spec, @objectstack/service-automation, @objectstack/connector-rest, @objectstack/connector-openapi: right. Metadata-protocol: added takes at least minor on every package the diff moves, and all four are moved.
• Clause-②: yes (widening) on the changeset; the PR body's yes (widening: …) reads as the widening arm (readClause2Line → arm: widening). Both carriers agree with the diff.
• ADR-0087: the gate judges only a changeset that declares breaking; a widening owes no marker (gate battery G1). The not-required (no-migration-prescription) marker present is surplus, honest (the body carries no FROM → TO prescription) and renders as nothing in the CHANGELOG. Not a finding.

③ Boundary flags

• Author is objectstack-fleet[bot]; no relay-login note owed.
• Head check-runs at review time: 19 success, 9 skipped, 19 still in progress, 0 failed. Landing precondition ② (every check green) is the seat's to confirm at landing; this record does not stand in for it.
• packages/spec now holds two more transport helpers (signingFetch, readConnectorResponse) beside connectorFetchOptions and resilientFetch. Prime Directive ✨ Set up Copilot instructions #2 tension, accepted on that standing precedent: no node:crypto, Web APIs only (Headers, URL, fetch), browser-safe. A later card may move the transport layer out of spec wholesale; not this slice's to do.
• ADR-0143 D4 lists signed among the per-dispatch answers; S1 resolves the key once at materialization (as the static kinds do) and signs per attempt. Operationally equivalent for a key with no expiry: the credential fingerprint joins the reconcile signature, so a rotated stored key re-materializes the instance. Noted for S2/S3 or 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's per-dispatch seam; not a must-fix.
• An empty resolved key is a configuration fault at boot for signed (a static kind would reach the upstream and degrade on refusal). Stricter and fail-closed; fine.
• The signing wrap refuses a non-text body or a Request object rather than sign something else. The built-ins send string bodies only; a custom factory hitting that refusal gets a thrown error, never an unsigned send.
• Dev's open items answered: skills text rides Teach oauth2 and app-credential connector auth once S1 serves them: skills recipe bullet, its eval, and lint steer strings still say the union has no oauth2 #28226 (a skills/** edit would make this Tier H) — accepted; packages/qa/downstream-contract and liveness/connector.json untouched because the walks did not ask — accepted. Docs-drift's "7 files with no anchor" are the generated JSONs — expected.
• security card: this record stays at rule level by design.

④ Design judgment

• connector-auth.zod.ts against ADR-0143 D2.3 / Q4 and its first consumer (createConnectorRequestSigner): the shape is the ADR's normative one (scheme, public key id, secret only as credentialRef); the closed enum is pinned to the union members so the list cannot drift from the shapes; the refusal names the value and the shipped set. Holds. Nit, not must-fix: ConnectorRequestSigner.scheme is typed string rather than ConnectorSigningScheme.
• connector-provider.ts against Q4 condition 2 and ADR-0049: the seam carries verifyResponse? from the first slice, so later schemes join with no seam change; the acknowledgement makes a factory opt in to serving a signed instance, so the default for an unaware factory is refusal, not an unsigned call. Against both first consumers (rest, openapi) it holds.
• connector.zod.ts against card item 4: the mcp refusal sits where the provider is known and is located at auth.type; the re-exports match the generated surface. Holds.
• connector-fetch-policy.ts against both consumers and the vector: one site signs every attempt for both built-ins with resilient-fetch.ts untouched; signer headers replace same-named request headers case-insensitively; the canonical URL is the sent URL; readConnectorResponse verifies the raw body before any parse and throws on failure so an unverified body never reaches a flow. Holds (vector run above).

Implemented-by: claude/project-thread-tpb1yk
Reviewed-by: session_016WV4czuTWNgKR22fKv7jia (seat subagent)

VERDICT: PASS

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Seat ACCEPT · PR #28273 · head 8c6135c75d148c6ac914999f7656a33f57c264d3 · 2026-10-31T00:52Z

维护者速读

• 改了什么： 声明式连接器（rest / openapi）新增 signed 鉴权：{ type: 'signed', scheme, keyId, credentialRef }，首个方案 aliyun-acs3-hmac-sha256，每一次请求（含重试）都重新签名。密钥只能是 credentialRef，不能内联；主机把解析出的密钥绑进签名器，连接器只拿到签名器，看不到密钥（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 第 1 片，ADR-0143 D2.3 / Q4 A）。
• 为什么改： 阿里云、腾讯云、支付宝等平台的 API 不用 OAuth 或静态密钥，而是逐请求签名；没有这一种鉴权，这些平台无法用元数据接入。
• 风险与回滚： 纯新增（Clause-②: yes，Metadata-protocol: added）；bearer / api-key / basic 行为逐字不变（已钉）。失败一律关闭：未知方案、内联密钥、mcp 上声明 signed 在发布时按名拒绝；没确认应用签名器的连接器启动时拒绝；数据源借用 signed 拒绝 422。回滚即还原本 PR。
• 先看： packages/spec/src/shared/connector-auth.zod.ts 的 signed 变体，和 service-automation/src/request-signing/。
• 两分钟验证： 跑 aliyun-acs3-hmac-sha256.test.ts（阿里云官方示例逐字节复现）。
• 需要你做的： 无（Tier S，未命中受管面；契约复核 PASS 6536676170，按本期落地授权由席位落地）。

席位核对

• Shape: draft → main, Refs #26710 (slice 1 of 3; S2 tencentcloud-tc3-hmac-sha256, S3 alipay-v3 with response verification, carrying Fixes). 36 files (+1611/−49). check-governed-merges --pr 28273: NOT governed.
• Premise: ADR-0143 Accepted on main; ConnectorInstanceAuthSchema carried none | bearer | api-key | basic only; the thread's slice plan was accepted by the seat before code.
• File surface: within the claim as amended (6535175098), including packages/spec/variant-docs.json and the new scripts/adr-anchors file.
• Declarations: Clause-②: yes (widening), Metadata-protocol: added, ADR-0087 marker; changesets minor on spec, service-automation, connector-openapi, connector-rest. Generated artefacts regenerated by the repo's tooling.
• Contract review: CONTRACT_REVIEW_TIER, PASS at this head, 6536676170. Flags carried to later slices, not must-fix: transport logic growing in spec (PD#2 precedent), and S1 binds the signer at materialization where D4 says per-dispatch (key rotation re-materializes by fingerprint); both go in S3's PR text. One nit (ConnectorRequestSigner.scheme typed string) rides S2.
• Security wording: security card; the PR body, changeset and records stay at rule level; the test vectors are the vendor's published example, cited by source.
• Local (card thread): dispatch-gates 115/115, 0 NOT-MEASURED; pnpm lint 0; targeted suites green (spec 211, service-automation 93, connector-rest 32, connector-openapi 75); ablations red when each guard is removed. Report 6536533657.
• Gate check-runs on this head: 50 total, 41 success, 9 skipped by the path filter, 0 failed. mergeable_state: clean.
• Landing: Tier S, under the maintainer's landing grant for this term (2026-10-29 22:05Z, seat thread). Ready + auto-merge through the relay. The card stays open for S2 and S3.

ACCEPT