Skip to content

Commit 2ca22f1

Browse files
committed
docs(runtime): the route ledger's connection-door rows name the begin leg's closed body set and its refusals
Claude-Session: https://claude.ai/code/session_01ADHkmSB1MQ9Npyv1kGL3DV Co-authored-by: Claude <noreply@anthropic.com>
1 parent 59630d9 commit 2ca22f1

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

‎packages/runtime/src/route-ledger.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -583,9 +583,9 @@ export const ROUTE_LEDGER: readonly RouteLedgerEntry[] = [
583583
// `authorization_code` instance for their organization (Q1 = A). The
584584
// store is `sys_connector_connection`, whose refresh token is a `Field.secret`.
585585
{ route: 'GET /automation/connectors/:name/connection', domain: '/automation', disposition: 'server-only',
586-
note: "The caller's organization's connection of one declared `oauth2` `authorization_code` instance: `status` (`not_connected` / `connected` / `reconnect_required`), its reason, the granted scopes, the access token's expiry and who connected it. ⛔ Never a token. Refused: an undeclared instance 404 `RESOURCE_NOT_FOUND`; one whose auth is not that grant, or a caller with no organization, 400 `VALIDATION_ERROR`. ⚑ `manage_connector_connections`, the organization-scoped capability (ADR-0143 D5), fail-closed, only `isSystem` bypassing; the platform-scoped `manage_metadata` does not admit a caller. No walled refusal, since a connection belongs to its organization. Closed query set: none. NOT JS-SDK surface on this leg: the driver is the Console's Connect / Reconnect flow (ADR-0143 S4). Pinned in `domains/automation-connector-connection-door.test.ts`" },
586+
note: "The caller's organization's connection of one declared `oauth2` `authorization_code` instance: `status` (`not_connected` / `connected` / `reconnect_required`), its reason, the granted scopes, the access token's expiry, who connected it and, for an instance declaring `clientSource: 'installer'`, `client: { source, clientId, hasSecret }`. ⛔ Never a token or a client secret. Refused: an undeclared instance 404 `RESOURCE_NOT_FOUND`; one whose auth is not that grant, or a caller with no organization, 400 `VALIDATION_ERROR`. ⚑ `manage_connector_connections`, the organization-scoped capability (ADR-0143 D5), fail-closed, only `isSystem` bypassing; the platform-scoped `manage_metadata` does not admit a caller. No walled refusal, since a connection belongs to its organization. Closed query set: none. NOT JS-SDK surface on this leg: the driver is the Console's Connect / Reconnect flow (ADR-0143 S4). Pinned in `domains/automation-connector-connection-door.test.ts`" },
587587
{ route: 'POST /automation/connectors/:name/connection', domain: '/automation', disposition: 'server-only',
588-
note: "Begin connecting (or reconnecting) the instance for the caller's organization: answers `{ authorizationUrl, expiresAt }`, the vendor URL carrying a fresh `state` and an `S256` PKCE challenge. Nothing is written to the connection record until the callback completes; the pending authorization (verifier included) waits ten minutes in the cluster KV, or in process on a single node, sealed (AES-256-GCM) under a key derived from the raw `state`, which the server keeps only as a digest. The redirect URI is the deployment's (`OS_AUTH_URL` / `OS_BASE_URL`, or the plugin option), never the request's — 503 `SERVICE_UNAVAILABLE` when there is none. No body. Same refusals, gates and SDK posture as the GET row above. Pinned in `domains/automation-connector-connection-door.test.ts`" },
588+
note: "Begin connecting (or reconnecting) the instance for the caller's organization: answers `{ authorizationUrl, expiresAt }`, the vendor URL carrying a fresh `state` and an `S256` PKCE challenge. Nothing is written to the connection record until the callback completes; the pending authorization (verifier included) waits ten minutes in the cluster KV, or in process on a single node, sealed (AES-256-GCM) under a key derived from the raw `state`, which the server keeps only as a digest. The redirect URI is the deployment's (`OS_AUTH_URL` / `OS_BASE_URL`, or the plugin option), never the request's — 503 `SERVICE_UNAVAILABLE` when there is none. Closed body set: `{ clientId, clientSecret? }`, the OAuth client an administrator registered with the vendor for an instance declaring `clientSource: 'installer'` (ADR-0143 D2.1); no body, or `{}`, begins with no client. Refused 400 `VALIDATION_ERROR`, naming keys only and never repeating a value: a body key other than `clientId` / `clientSecret` (or a non-object body, or a `clientSecret` without its `clientId`); an installer instance begun with no client (the message names the vendor registration step and the redirect URI to register); a client offered to an instance that declares its own or leaves it to MCP dynamic registration. The secret is kept only encrypted in the connection record, never answered back. Same refusals, gates and SDK posture as the GET row above. Pinned in `domains/automation-connector-connection-door.test.ts`" },
589589
{ route: 'DELETE /automation/connectors/:name/connection', domain: '/automation', disposition: 'server-only',
590590
note: "Revoke the caller's organization's connection: the row is removed, the cached access token dropped, and the instance re-judged — its next dispatch there is refused 'not connected'. ⚑ Local only: no RFC 7009 revocation is sent to the vendor, because no revocation endpoint is known for the instance (the auth declares none; ADR-0143 S2 discovery would supply one), so the refresh token stays valid at the vendor until it expires or is revoked there. 404 `RESOURCE_NOT_FOUND` when it was not connected; 503 `SERVICE_UNAVAILABLE` when the connection store cannot be read. Same gates and SDK posture as the GET row above. Pinned in `domains/automation-connector-connection-door.test.ts`" },
591591
{ route: 'GET /automation/connectors/oauth/callback', domain: '/automation', disposition: 'server-only',

0 commit comments

Comments
 (0)