Skip to content

Commit 8269772

Browse files
committed
fix(spec): mark clientSource as declared, not yet served, until the server slice reads it
Contract review 6569108322 on #28920: - The key's describe carries `[PLANNED — not enforced]` and says what an instance that declares it does meanwhile (held degraded off MCP over http; dynamic registration on MCP over http). It names ADR-0143 D2.1, not the tracker id, because check:doc-authoring refuses an issue id in customer-facing spec prose; the adjacent comment names #28866. Reference regenerated. - The liveness ledger's `connector/auth` row records the key as `planned` until #28866: the walker does not descend into the auth union, so that row is the only ledger coordinate over it. - A test pins the marker, the ADR reference, no tracker id in the describe, and the ledger sentence, so #28866 drops them together. - The authorization_code `credentialRef` describe names the installer form. - ADR-0143: a pointer under D3's persisted list to the 2026-11-02 D2.1 note, and the note's Slices bullet states the interim behaviour. - The changeset names the marker and the ledger row. Claude-Session: https://claude.ai/code/session_01ADHkmPS39tCwZRCvghgPQf Co-authored-by: Claude <noreply@anthropic.com>
1 parent 23acaa6 commit 8269772

6 files changed

Lines changed: 56 additions & 16 deletions

File tree

‎.changeset/28864-oauth2-installer-client.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,6 @@ connectors: [{
3131
- **What it means.** The administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection. The definition names no client and no secret.
3232
- **What it refuses.** A `clientId` beside `clientSource` is refused at publish, located at `auth.clientId`: the definition would name two clients. A `credentialRef` without its `clientId` is refused as before, and its message now names this form. An unknown value is refused at `auth.clientSource`. On `grant: 'client_credentials'` the key is refused with guidance, because that grant keeps no connection to enter a client on.
3333
- **What it does not change.** The endpoints stay declared, or discovered on `provider: 'mcp'` over http: the installer owns the client, not the vendor's authorization server. An instance that names a pre-registered `clientId` without the key parses exactly as before. That form is kept for an app whose author registers the callback of every deployment that installs it, such as an organization's own app.
34-
- **Not yet served.** The automation service does not read the key yet. The connection door that takes the installer's client, and the form that asks for it, land in follow-up changes. Until then an instance that declares it on a non-MCP provider is held degraded, with a reason naming the missing `clientId`, and is never called without a client. On `provider: 'mcp'` over http the service runs the MCP authorization flow as it does for an instance that leaves its client to dynamic registration.
34+
- **Not yet served.** The automation service does not read the key yet. The connection door that takes the installer's client, and the form that asks for it, land in follow-up changes. Until then an instance that declares it on a non-MCP provider is held degraded, with a reason naming the missing `clientId`, and is never called without a client. On `provider: 'mcp'` over http the service runs the MCP authorization flow as it does for an instance that leaves its client to dynamic registration. The key's reference row carries `[PLANNED — not enforced]` until then, and the liveness ledger's `connector/auth` row records it as `planned`.
3535

3636
ADR-0143 D2.1 carries the amendment (2026-11-02).

‎content/docs/references/integration/connector.mdx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -270,8 +270,8 @@ const result = ConnectorSchema.parse(data);
270270
| **clientId** | `string` | optional | OAuth2 client id of a pre-registered client (not a secret). Required, except where the client comes from elsewhere: `provider: 'mcp'` over http may register one dynamically, and with `clientSource: 'installer'` the administrator enters it on the connection, so it is not named here. |
271271
| **grant** | `'authorization_code'` | ✅ | An administrator connects once; the platform refreshes the grant per dispatch. |
272272
| **authorizationUrl** | `string` | optional | Authorization endpoint. Required (except `provider: 'mcp'` over http, which discovers it). |
273-
| **clientSource** | `Enum<'installer'>` | optional | Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. |
274-
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client. Never an inline secret. |
273+
| **clientSource** | `Enum<'installer'>` | optional | [PLANNED — not enforced] Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. Not served yet: the automation service reads it once the server half of the ADR-0143 D2.1 amendment lands. Until then, off `provider: 'mcp'` over http, an instance that declares it is held degraded for a missing `clientId`; on `provider: 'mcp'` over http the provider registers a client dynamically instead of taking the installer's. |
274+
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client, and with `clientSource: 'installer'`, where the administrator enters the secret on the connection. Never an inline secret. |
275275

276276
### Nested Shape: `Connector.auth[option 5][grant='client_credentials']`
277277

@@ -565,8 +565,8 @@ This schema accepts one of the following structures:
565565
| **clientId** | `string` | optional | OAuth2 client id of a pre-registered client (not a secret). Required, except where the client comes from elsewhere: `provider: 'mcp'` over http may register one dynamically, and with `clientSource: 'installer'` the administrator enters it on the connection, so it is not named here. |
566566
| **grant** | `'authorization_code'` | ✅ | An administrator connects once; the platform refreshes the grant per dispatch. |
567567
| **authorizationUrl** | `string` | optional | Authorization endpoint. Required (except `provider: 'mcp'` over http, which discovers it). |
568-
| **clientSource** | `Enum<'installer'>` | optional | Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. |
569-
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client. Never an inline secret. |
568+
| **clientSource** | `Enum<'installer'>` | optional | [PLANNED — not enforced] Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. Not served yet: the automation service reads it once the server half of the ADR-0143 D2.1 amendment lands. Until then, off `provider: 'mcp'` over http, an instance that declares it is held degraded for a missing `clientId`; on `provider: 'mcp'` over http the provider registers a client dynamically instead of taking the installer's. |
569+
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client, and with `clientSource: 'installer'`, where the administrator enters the secret on the connection. Never an inline secret. |
570570

571571
---
572572

@@ -604,8 +604,8 @@ This schema accepts one of the following structures:
604604
| **clientId** | `string` | optional | OAuth2 client id of a pre-registered client (not a secret). Required, except where the client comes from elsewhere: `provider: 'mcp'` over http may register one dynamically, and with `clientSource: 'installer'` the administrator enters it on the connection, so it is not named here. |
605605
| **grant** | `'authorization_code'` | ✅ | An administrator connects once; the platform refreshes the grant per dispatch. |
606606
| **authorizationUrl** | `string` | optional | Authorization endpoint. Required (except `provider: 'mcp'` over http, which discovers it). |
607-
| **clientSource** | `Enum<'installer'>` | optional | Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. |
608-
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client. Never an inline secret. |
607+
| **clientSource** | `Enum<'installer'>` | optional | [PLANNED — not enforced] Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. Not served yet: the automation service reads it once the server half of the ADR-0143 D2.1 amendment lands. Until then, off `provider: 'mcp'` over http, an instance that declares it is held degraded for a missing `clientId`; on `provider: 'mcp'` over http the provider registers a client dynamically instead of taking the installer's. |
608+
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client, and with `clientSource: 'installer'`, where the administrator enters the secret on the connection. Never an inline secret. |
609609

610610

611611
---
@@ -876,8 +876,8 @@ Connector type
876876
| **clientId** | `string` | optional | OAuth2 client id of a pre-registered client (not a secret). Required, except where the client comes from elsewhere: `provider: 'mcp'` over http may register one dynamically, and with `clientSource: 'installer'` the administrator enters it on the connection, so it is not named here. |
877877
| **grant** | `'authorization_code'` | ✅ | An administrator connects once; the platform refreshes the grant per dispatch. |
878878
| **authorizationUrl** | `string` | optional | Authorization endpoint. Required (except `provider: 'mcp'` over http, which discovers it). |
879-
| **clientSource** | `Enum<'installer'>` | optional | Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. |
880-
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client. Never an inline secret. |
879+
| **clientSource** | `Enum<'installer'>` | optional | [PLANNED — not enforced] Where the OAuth client comes from. `'installer'`: the administrator of each deployment registers their own client with the vendor, against that deployment's callback, and enters its id and secret on the instance's connection, so the definition names no `clientId` and no `credentialRef`. Omit it to name a pre-registered `clientId` here, or to let `provider: 'mcp'` over http register a client. Not served yet: the automation service reads it once the server half of the ADR-0143 D2.1 amendment lands. Until then, off `provider: 'mcp'` over http, an instance that declares it is held degraded for a missing `clientId`; on `provider: 'mcp'` over http the provider registers a client dynamically instead of taking the installer's. |
880+
| **credentialRef** | `string` | optional | Secrets-layer reference resolved to the client secret of a pre-registered client (requires `clientId`). Omit for a public client, and with `clientSource: 'installer'`, where the administrator enters the secret on the connection. Never an inline secret. |
881881

882882
### Nested Shape: `DeclarativeConnectorEntry.auth[option 5][grant='client_credentials']`
883883

‎docs/adr/0143-outbound-connector-auth-is-open-tier.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,10 @@ carry and forbid; exact key spelling is the spec slice's, reviewed against this
246246
> targets one host set, sandbox first. Discovering an API host per connection is a follow-up.
247247
> - **Slices.** The server slice keeps the installer's client on the connection and sends it: the connect
248248
> door takes it, and the grant handle uses it in place of a declared one. The ui slice asks for it on
249-
> the connection form and shows the deployment's redirect URI.
249+
> the connection form and shows the deployment's redirect URI. Until the server slice lands, the key is
250+
> declared and not served, and its schema description says so: off `provider: 'mcp'` over http an
251+
> instance that declares it is held degraded for a missing `clientId`, and on MCP over http the
252+
> provider registers a client dynamically instead of taking the installer's.
250253
251254
### D3 — Secrets are references; tokens are runtime state in a connection record
252255

@@ -258,6 +261,9 @@ carry and forbid; exact key spelling is the spec slice's, reviewed against this
258261
client a dynamic registration created, and the grant's status, scopes and expiry. These live in a
259262
dedicated connection record bound to the instance (Q2), their secrets encrypted at rest through the
260263
`secret` channel (ADR-0100).
264+
> **Amended (2026-11-02, #28864).** This list also holds a client the installing administrator supplies,
265+
> kept in the same per-connection client record as a dynamically registered one. See the 2026-11-02
266+
> D2.1 note under D2.
261267
- Access tokens are never persisted. They live in an in-process cache. This includes every
262268
`client_credentials` and `app-credential` token, which the configured secret re-derives at any time.
263269

‎packages/spec/liveness/connector.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@
6464
"verifiedAt": "2026-09-17",
6565
"evidence": "packages/services/service-automation/src/plugin.ts#materializeDeclaredConnectors — `auth = await this.resolveInstanceAuth(entry.auth, resolver, name, provider)` resolves the declared `credentialRef` through the secrets/env layer and puts the RESOLVED credential on the provider context; a failure there degrades or fails the instance by name (ADR-0097 §3). packages/connectors/connector-rest/src/rest-provider.ts, packages/connectors/connector-openapi/src/openapi-provider.ts and packages/connectors/connector-mcp/src/mcp-provider.ts each read `ctx.auth` and use it to sign the upstream call. packages/spec/src/integration/connector.zod.ts#DeclarativeConnectorEntrySchema refuses it on an entry with no `provider`.",
6666
"producer": "packages/services/service-automation/src/plugin.ts#materializeDeclaredConnectors — the ADR-0097 reconcile: it builds the desired set from the declared `connectors:` items, resolves the provider factory and calls `engine.registerConnector(def, handlers, 'declarative')`. This is the ONLY seam by which an authored entry reaches the connector registry, so it is the producer every `live` row below depends on (#4837): without it a declared connector is a stored document and nothing else.",
67-
"note": "The live half of the pair whose other half (`authentication`) is refused ANY VALUE BUT `{ type: 'none' }` — the key itself is accepted and inert, so ⛔ do not compress this to '`authentication` is refused' (see that row): this key is how an authored connector carries a credential at all, and it carries a REFERENCE, never the secret."
67+
"note": "The live half of the pair whose other half (`authentication`) is refused ANY VALUE BUT `{ type: 'none' }` — the key itself is accepted and inert, so ⛔ do not compress this to '`authentication` is refused' (see that row): this key is how an authored connector carries a credential at all, and it carries a REFERENCE, never the secret. 2026-11-02 (#28864): one member of this union is `planned`, not `live` — `clientSource` on the `oauth2` `authorization_code` shape (ADR-0143 D2.1 amendment), until #28866 makes the automation service read the installer's client from the connection. The walker does not descend into the `auth` union, so this row's `live` verdict is the only ledger coordinate over the key and would otherwise cover it unseen; its `.describe()` carries `[PLANNED — not enforced]`. Meanwhile an instance that declares it is held degraded for a missing `clientId` off `provider: 'mcp'` over http (`oauth2NotServableReason` in service-automation's plugin.ts), and on MCP over http the provider registers a client dynamically instead of taking the installer's. When #28866 lands, drop this sentence and the marker together."
6868
},
6969
"actions": {
7070
"children": {

‎packages/spec/src/integration/connector-auth-grant-kinds.test.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@
77
// error the ADR's Acceptance asks for; every member has a CONTROL accept, so a
88
// refusal that fired on everything could not pass.
99

10+
import fs from 'node:fs';
1011
import { describe, it, expect } from 'vitest';
1112
import { DeclarativeConnectorEntrySchema, ConnectorInstanceAuthSchema } from './connector.zod';
13+
import { ConnectorInstanceOAuth2AuthorizationCodeAuthSchema } from '../shared/connector-auth.zod';
1214

1315
const entry = (auth: unknown, over: Record<string, unknown> = {}) => ({
1416
name: 'vendor',
@@ -213,6 +215,26 @@ describe("ADR-0143 D2.1 — an `authorization_code` client supplied by the insta
213215
['authorizationUrl', 'clientSource', 'grant', 'scopes', 'tokenUrl', 'type'],
214216
);
215217
});
218+
219+
// Declared before it is served (ADR-0049): until #28866 makes the automation
220+
// service read the installer's client, the key says so on the spec surface.
221+
// The liveness walker does not descend into the `auth` union, so the
222+
// `connector/auth` row is the only ledger coordinate over the key. #28866
223+
// drops the marker and the row's sentence together, and flips this test.
224+
it('is PLANNED until the automation service serves it: the describe marker, and the ledger row over the key', () => {
225+
const shape = (ConnectorInstanceOAuth2AuthorizationCodeAuthSchema as unknown as {
226+
shape: Record<string, { description?: string }>;
227+
}).shape;
228+
expect(shape.clientSource.description).toMatch(/^\[PLANNED — not enforced\] /);
229+
expect(shape.clientSource.description).toContain('ADR-0143 D2.1');
230+
// Customer-facing prose carries no tracker id (check:doc-authoring); the slice is named in the ledger row.
231+
expect(shape.clientSource.description).not.toMatch(/#\d{3,}/);
232+
const ledger = JSON.parse(fs.readFileSync(new URL('../../liveness/connector.json', import.meta.url), 'utf8'));
233+
const note: string = ledger.props.auth.note;
234+
expect(note).toContain('`clientSource`');
235+
expect(note).toContain('`planned`');
236+
expect(note).toContain('#28866');
237+
});
216238
});
217239

218240
describe('ADR-0143 D2.2 — `app-credential` instance auth', () => {

0 commit comments

Comments
 (0)