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

Blocked-by: #26768

Filing gate ③ (maintainer-directed task). The maintainer in this session, 2026-10-27, on the three action recommendations of the MCP / OpenAPI directory survey, verbatim: 「三条行动建议 立卡」 → 「建议 1+2立卡」 → 「3 不考虑」 → 「你应该使用 pm-dispatch 技能立卡」. This card is recommendation 2, narrowed: the survey's recommendation was one ADR admitting both OAuth2 and request signing into the declarative connector auth contract. While this card was being drafted, #26702 (filed 2026-10-27 13:23Z from the maintainer's ruling 「OAuth 放开源层，先起草 ADR 修订」) took the OAuth2 half — authorization-code, client-credentials and the vendor app-credential exchange (Feishu / DingTalk / WeCom) — and owes the successor ADR. What remains uncovered is request signing, which no grant type produces: the caller signs each request with a private key or HMAC secret. This card is that half.

Filed by session_01J8VVAjRKqdoEYQ4hXxtBuf. ⛔ Not a claim. Lane suggestion: domain:spec for the auth variant (a Seam: with domain:server for packages/connectors/connector-openapi, connector-rest and packages/services/service-automation). Triage sets labels and priority. Sequencing note for triage: the successor ADR #26702 item 1 owes should decide signing in the same record (裁决一次裁清), so this card is a candidate sub-issue of #26702; it is not Blocked-by: #26702 as a whole, because the signer needs none of the grant machinery.

Business reason. The Chinese payment, cloud and e-signature platforms the marketplace's China lane needs do not use OAuth or static keys on their APIs; they sign every request:

Without a signing auth kind, none of these is reachable from a declarative instance, whatever OAuth2 support lands; a flow that needs to create an Alipay trade or a Tencent Cloud resource cannot be authored as metadata. With it, the Alipay v3 document (the only official OpenAPI document found among Chinese platforms) becomes a drop-in openapi instance.

Who acts. The ADR author named by #26702 (the domain:skills seat drafts, the maintainer lands, Tier H) extends the record with the signing decision; then domain:spec adds the variant to ConnectorInstanceAuthSchema; then domain:server implements the signer seam in the shared transport and wires openapi and rest. Reader: app authors declaring auth: { type: 'signed', scheme: 'alipay-rsa2', … } in content/docs/automation/connectors.

Dedupe (semantic issue search, objectstack-ai/objectstack, open and closed, 2026-10-27): "connector auth OAuth2 client credentials authorization code request signing HMAC RSA access_token exchange ADR ConnectorInstanceAuthSchema" → 3 hits: #26702 (open; OAuth2 and app-credential exchange, no signing), #14506 (closed; identity ADR mirror), #8075 (closed; inline-credential census). No card covers request signing.

Governing text

• packages/spec/src/shared/connector-auth.zod.ts:113-114 (header of the declarative auth block): "OAuth2 is intentionally absent (enterprise tier, ADR-0015)." The declared kinds are none | bearer | api-key | basic (lines 119–145). Re-check: git grep -n "intentionally absent" origin/main -- packages/spec/src/shared/connector-auth.zod.ts.
• ADR-0097 line 119: "The open tier deliberately omits OAuth2 from ConnectorInstanceAuthSchema" and §3: credentialRef resolves at materialization; inline secrets are refused at publish. Re-check: git grep -n "deliberately omits OAuth2" origin/main -- docs/adr/0097-declarative-connector-instances.md.
• AGENTS.md Prime Directive [WIP] Add Chinese version of the documentation #13: an accepted ADR binds until a superseding ADR says otherwise — the auth boundary moves by ADR, which 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 item 1 already owes; this card adds the signing decision to that record rather than opening a second one.
• AGENTS.md Prime Directive Add comprehensive test suite for Zod schema validation #12: contract-first; the variant is a closed enum of named schemes, refused at publish when unknown — never a free-form "custom header function".

Protocol statement. Metadata-protocol: added: a new ConnectorInstanceAuthSchema variant. Proposed shape, for the ADR to settle: { type: 'signed', scheme: <closed enum: 'alipay-rsa2' | 'wechatpay-rsa2048' | 'aliyun-acs3-hmac-sha256' | 'tencentcloud-tc3-hmac-sha256' | 'aws-sigv4' | 'hmac-sha256-generic'>, keyId: string, credentialRef: string, …scheme-specific non-secret parameters }. The private key or HMAC secret is a credentialRef only (ADR-0097 §3). Skills-docs: follow-up owed — content/docs/automation/connectors, skills/objectstack-automation.

Premises (each with a re-check; read at c3fb185a)

1. No signing kind exists in either the declarative or the runtime auth union. Re-check: git grep -n "z.literal('" origin/main -- packages/spec/src/shared/connector-auth.zod.ts (expected: oauth2, api-key, basic, bearer, none only).
2. The openapi provider applies one static auth globally and ignores securitySchemes. Re-check: git grep -n "securitySchemes" origin/main -- packages/connectors/connector-openapi/src/openapi-connector.ts (type only, no consumer).
3. 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 does not list signing in its grant types or its spec variant. Re-check: read 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 "Work" items 3 and 5.

Work

1. ADR (with 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 item 1): admit a signed auth kind with a closed scheme enum into the open tier; state which schemes ship first and that the secret is always a credentialRef.
2. Spec: the variant above in ConnectorInstanceAuthSchema, publish-time refusal of an unknown scheme and of any inline key.
3. Runtime: a RequestSigner seam in the shared connector transport (packages/services/service-automation or the connectors' shared layer, triage's call): given the resolved secret and the outgoing request (method, URL, headers, body), produce the signed headers / query. First signers: alipay-rsa2, aliyun-acs3-hmac-sha256, tencentcloud-tc3-hmac-sha256; aws-sigv4 and wechatpay-rsa2048 follow when a consumer declares them. Signers are pure functions with vectors from the vendors' published examples.
4. Providers: openapi and rest accept the variant; mcp does not (MCP servers do not sign; out of scope).

Acceptance

• A declarative openapi instance over the normalized Alipay v3 document (see connectors: auto-shelf readiness — declarative include and a loud Swagger 2.0 refusal for connector-openapi; tools/list pagination, fatal 401 and a tool-snapshot hash for connector-mcp; an offline spec-normalization tool #26709's normalization tool) with auth: { type: 'signed', scheme: 'alipay-rsa2', keyId, credentialRef } dispatches a sandbox query end to end; the request carries the Alipay Authorization header computed by the signer; the private key appears nowhere in sys_metadata, in GET /api/v1/automation/connectors, or in logs.
• Signer unit tests reproduce the vendors' published signature examples byte for byte for each shipped scheme.
• An unknown scheme or an inline key is refused at publish with a located error; changeset per touched package.

Out of scope

• OAuth2 grants and app-credential (appKey/secret → access_token) exchange: 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.
• Writing OpenAPI documents for WeChat Pay, WeCom, e签宝 where the vendor publishes none: recommendation 3, not filed (「3 不考虑」).

Related

#26702 (parent candidate) · ADR-0097 · ADR-0015 · ADR-0023 · #26709 (recommendation 1, same batch).

Generated by Claude Code