[codex] Clean up OpenAPI add source API (#843)

* Clean up OpenAPI add source API * Update OpenAPI add source credential UI * Address OpenAPI add source PR feedback * Document OpenAPI credential configuration plan * Fix OpenAPI add flow CI

Rhys Sullivan committed 5 months ago

Commit 529a54f1 parent 1d16b0b20 files · +1477 −467Browse files

Unified · Split

20 files

apps/cloud/src/services/sources-api.node.test.ts +23 −29
apps/cloud/src/services/sources-refresh.node.test.ts +6 −4
apps/cloud/src/services/tenant-isolation.node.test.ts +10 −25
apps/marketing/src/pages/api/detect.ts +3 −1
examples/all-plugins/src/main.ts +2 −1
examples/docs-sdk-quickstart/src/main.ts +6 −1
examples/promise-sdk/src/main.ts +6 −1
notes/openapi-add-source-api-cleanup.md +316 −0
notes/openapi-sdk-credential-configuration.md +509 −0
notes/source-binding-consolidation.md +209 −0
packages/kernel/runtime-dynamic-worker/src/integration.test.ts +7 −1
packages/plugins/openapi/src/api/group.ts +23 −31
packages/plugins/openapi/src/api/handlers.ts +11 −14
packages/plugins/openapi/src/react/AddOpenApiSource.tsx +143 −110
packages/plugins/openapi/src/react/atoms.ts +1 −1
packages/plugins/openapi/src/sdk/plugin.test.ts +66 −44
packages/plugins/openapi/src/sdk/plugin.ts +76 −177
packages/plugins/openapi/src/sdk/real-specs.test.ts +2 −1
packages/plugins/openapi/src/sdk/source-contracts.ts +6 −0
packages/plugins/openapi/src/testing/index.ts +52 −26

apps/cloud/src/services/sources-api.node.test.ts+23−29

   .annotateMerge(OpenApi.annotations({ title: "Sources API Test", version: "1.0.0" }));
 const makeMinimalOpenApiSourcePayload = (
-  targetScope: ScopeId,
   namespace: string,
-  options: Omit<
+  options: Omit<Parameters<typeof makeOpenApiHttpApiTestAddSpecPayload>[1], "namespace"> = {},
-    Parameters<typeof makeOpenApiHttpApiTestAddSpecPayload>[1],
-    "targetScope" | "namespace"
-  > = {},
 ) =>
   makeOpenApiHttpApiTestAddSpecPayload(MinimalSourceApi, {
-    targetScope,
     namespace,
     ...options,
   });
         Effect.gen(function* () {
           const result = yield* client.openapi.addSpec({
             params: { scopeId: ScopeId.make(org) },
-            payload: makeMinimalOpenApiSourcePayload(ScopeId.make(org), namespace),
+            payload: makeMinimalOpenApiSourcePayload(namespace),
           });
           expect(result.namespace).toBe(namespace);
           expect(result.toolCount).toBeGreaterThan(0);
       yield* asOrg(org, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(org) },
-          payload: makeMinimalOpenApiSourcePayload(ScopeId.make(org), namespace),
+          payload: makeMinimalOpenApiSourcePayload(namespace),
         }),
       );
       const result = yield* asOrg(org, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(org) },
-          payload: makeMinimalOpenApiSourcePayload(
+          payload: makeMinimalOpenApiSourcePayload(`ns_${crypto.randomUUID().replace(/-/g, "_")}`, {
-            ScopeId.make(org),
+            baseUrl: "http://example.com",
-            `ns_${crypto.randomUUID().replace(/-/g, "_")}`,
+          }),
-            { baseUrl: "http://example.com" },
-          ),
         }),
       );
         client.openapi.addSpec({
           params: { scopeId },
           payload: {
-            targetScope: scopeId,
+            spec: { kind: "blob", value: server.specJson },
-            spec: server.specJson,
+            name: "Invocable Source API",
+            baseUrl: server.baseUrl,
             namespace,
           },
         }),
         Effect.gen(function* () {
           yield* client.openapi.addSpec({
             params: { scopeId: ScopeId.make(org) },
-            payload: makeMinimalOpenApiSourcePayload(ScopeId.make(org), namespace),
+            payload: makeMinimalOpenApiSourcePayload(namespace),
           });
           yield* client.sources.remove({
             params: { scopeId: ScopeId.make(org), sourceId: namespace },
         Effect.gen(function* () {
           yield* client.openapi.addSpec({
             params: { scopeId: ScopeId.make(org) },
-            payload: makeMinimalOpenApiSourcePayload(ScopeId.make(org), namespace),
+            payload: makeMinimalOpenApiSourcePayload(namespace),
           });
           yield* client.openapi.updateSource({
             params: { scopeId: ScopeId.make(org), namespace },
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgId) },
           payload: {
-            ...makeMinimalOpenApiSourcePayload(ScopeId.make(orgId), namespace),
+            ...makeMinimalOpenApiSourcePayload(namespace),
             headers: {
               Authorization: {
-                kind: "binding",
+                kind: "secret",
-                slot: "auth:personal-token",
                 prefix: "Bearer ",
               },
             },
               sourceId: namespace,
               sourceScope: ScopeId.make(orgId),
               scope: ScopeId.make(aliceScope),
-              slot: "auth:personal-token",
+              slot: "header:authorization",
               value: {
                 kind: "secret",
                 secretId: SecretId.make("alice_pat"),
             sourceId: namespace,
             sourceScopeId: ScopeId.make(orgId),
             scopeId: ScopeId.make(aliceScope),
-            slot: "auth:personal-token",
+            slot: "header:authorization",
             value: {
               kind: "secret",
               secretId: SecretId.make("alice_pat"),
               sourceId: namespace,
               sourceScope: ScopeId.make(orgId),
               scope: ScopeId.make(bobScope),
-              slot: "auth:personal-token",
+              slot: "header:authorization",
               value: {
                 kind: "secret",
                 secretId: SecretId.make("bob_pat"),
       expect(aliceBindings).toContainEqual(
         expect.objectContaining({
           scopeId: ScopeId.make(aliceScope),
-          slot: "auth:personal-token",
+          slot: "header:authorization",
           value: {
             kind: "secret",
             secretId: SecretId.make("alice_pat"),
       expect(
         aliceBindings.some(
           (binding) =>
-            binding.slot === "auth:personal-token" &&
+            binding.slot === "header:authorization" &&
             binding.value.kind === "secret" &&
             binding.value.secretId === SecretId.make("bob_pat"),
         ),
       expect(bobBindings).toContainEqual(
         expect.objectContaining({
           scopeId: ScopeId.make(bobScope),
-          slot: "auth:personal-token",
+          slot: "header:authorization",
           value: {
             kind: "secret",
             secretId: SecretId.make("bob_pat"),
       expect(
         bobBindings.some(
           (binding) =>
-            binding.slot === "auth:personal-token" &&
+            binding.slot === "header:authorization" &&
             binding.value.kind === "secret" &&
             binding.value.secretId === SecretId.make("alice_pat"),
         ),
           client.openapi.addSpec({
             params: { scopeId: ScopeId.make(org) },
             payload: {
-              targetScope: ScopeId.make(org),
+              spec: { kind: "blob", value: CLOUDFLARE_SPEC },
-              spec: CLOUDFLARE_SPEC,
+              name: namespace,
+              baseUrl: "https://api.cloudflare.com/client/v4",
               namespace,
             },
           }),

apps/cloud/src/services/sources-refresh.node.test.ts+6−4

           client.openapi.addSpec({
             params: { scopeId: ScopeId.make(org) },
             payload: {
-              targetScope: ScopeId.make(org),
+              spec: { kind: "url", url: server.specUrl },
-              spec: server.specUrl,
+              name: namespace,
+              baseUrl: server.baseUrl,
               namespace,
             },
           }),
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(org) },
           payload: {
-            targetScope: ScopeId.make(org),
+            spec: { kind: "blob", value: makeRefreshSpecText() },
-            spec: makeRefreshSpecText(),
+            name: namespace,
+            baseUrl: "https://api.example.test",
             namespace,
           },
         }),

apps/cloud/src/services/tenant-isolation.node.test.ts+10−25

   .annotateMerge(OpenApi.annotations({ title: "Tenant Test API", version: "1.0.0" }));
 const makeTenantOpenApiSourcePayload = (
-  targetScope: ScopeId,
   namespace: string,
-  options: Omit<
+  options: Omit<Parameters<typeof makeOpenApiHttpApiTestAddSpecPayload>[1], "namespace"> = {},
-    Parameters<typeof makeOpenApiHttpApiTestAddSpecPayload>[1],
-    "targetScope" | "namespace"
-  > = {},
 ) =>
   makeOpenApiHttpApiTestAddSpecPayload(TenantIsolationApi, {
-    targetScope,
     namespace,
     ...options,
   });
       yield* asOrg(orgA, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgA) },
-          payload: makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespaceA),
+          payload: makeTenantOpenApiSourcePayload(namespaceA),
         }),
       );
       yield* asOrg(orgA, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgA) },
-          payload: makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespaceA),
+          payload: makeTenantOpenApiSourcePayload(namespaceA),
         }),
       );
       yield* asOrg(orgA, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgA) },
-          payload: makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespaceA),
+          payload: makeTenantOpenApiSourcePayload(namespaceA),
         }),
       );
           yield* client.openapi.addSpec({
             params: { scopeId: ScopeId.make(orgA) },
             payload: {
-              ...makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespaceA),
+              ...makeTenantOpenApiSourcePayload(namespaceA),
               headers: {
                 Authorization: {
-                  kind: "binding",
+                  kind: "secret",
-                  slot: "auth:token",
                   prefix: "Bearer ",
                 },
               },
               sourceId: namespaceA,
               sourceScope: ScopeId.make(orgA),
               scope: ScopeId.make(orgA),
-              slot: "auth:token",
+              slot: "header:authorization",
               value: { kind: "secret", secretId: secretIdA },
             },
           });
         Effect.gen(function* () {
           yield* client.openapi.addSpec({
             params: { scopeId: ScopeId.make(orgA) },
-            payload: {
+            payload: makeTenantOpenApiSourcePayload(namespaceA),
-              ...makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespaceA),
-              headers: {
-                Authorization: {
-                  kind: "binding",
-                  slot: "auth:conn",
-                  prefix: "Bearer ",
-                },
-              },
-            },
           });
           yield* client.openapi.setSourceBinding({
             params: { scopeId: ScopeId.make(orgA) },
       yield* asOrg(orgA, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgA) },
-          payload: makeTenantOpenApiSourcePayload(ScopeId.make(orgA), namespace, {
+          payload: makeTenantOpenApiSourcePayload(namespace, {
             name: "Org A API",
             baseUrl: "https://org-a.example.com",
           }),
       yield* asOrg(orgB, (client) =>
         client.openapi.addSpec({
           params: { scopeId: ScopeId.make(orgB) },
-          payload: makeTenantOpenApiSourcePayload(ScopeId.make(orgB), namespace, {
+          payload: makeTenantOpenApiSourcePayload(namespace, {
             name: "Org B API",
             baseUrl: "https://org-b.example.com",
           }),

apps/marketing/src/pages/api/detect.ts+3−1

         // Add source to register its tools (Google Discovery needs auth so skip)
         if (match.kind === "openapi") {
           yield* executor.openapi.addSpec({
-            spec: match.endpoint,
+            spec: { kind: "url", url: match.endpoint },
+            name: match.name,
             namespace: match.namespace,
+            baseUrl: match.endpoint,
             scope: "test-scope",
           });
         } else if (match.kind === "graphql") {

examples/all-plugins/src/main.ts+2−1

   console.log("-".repeat(72));
   const addSpecResult = yield* executor.openapi.addSpec({
-    spec: exampleOpenApiSpec,
+    spec: { kind: "blob", value: exampleOpenApiSpec },
     namespace: "example-api",
+    name: "Example API",
     baseUrl: "https://example.com/api",
     scope: "example-scope",
   });

examples/docs-sdk-quickstart/src/main.ts+6−1

 await executor.openapi.addSpec({
   namespace: "inventory",
   scope: "docs-workspace",
-  spec: JSON.stringify(inventoryApi),
+  name: "Inventory API",
+  baseUrl: "https://inventory.example.com",
+  spec: {
+    kind: "blob",
+    value: JSON.stringify(inventoryApi),
+  },
 });
 // docs:end add-source

examples/promise-sdk/src/main.ts+6−1

 // ---------------------------------------------------------------------------
 await executor.openapi.addSpec({
-  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+  spec: {
+    kind: "url",
+    url: "https://petstore3.swagger.io/api/v3/openapi.json",
+  },
   namespace: "petstore",
   scope: "my-app",
+  name: "Petstore",
+  baseUrl: "https://petstore3.swagger.io/api/v3",
 });
 // With auth headers (static or secret-backed)

notes/openapi-add-source-api-cleanup.md+316−0

@@ -0,0 +1,316 @@
	1	# OpenAPI Add Source API Cleanup Notes
	2
	3	Date: 2026-05-17
	4	Status: planning
	5
	6	## Summary
	7
	8	The current OpenAPI add-source API mixes source ownership, source shape, and
	9	credential binding values in one payload. That makes the common org-shared
	10	source with per-user credentials hard to reason about. We want the immediate
	11	cleanup to make the OpenAPI add endpoint explicit and remove duplicated scope
	12	fields, without solving the larger per-user source/tool discovery model yet.
	13
	14	The product model for this pass is:
	15
	16	- OpenAPI source rows and tool definitions are shared at the org/workspace
	17	level in the web UI.
	18	- Runtime credential values can vary by user or org, but they must match the
	19	shared source credential shape.
	20	- Spec fetch credentials are source-definition credentials. If the shared spec
	21	URL requires auth, those credentials are part of maintaining the shared tool
	22	surface.
	23	- Different auth structures should be different source instances, not
	24	different per-user modes inside one source.
	25
	26	## Current Problems
	27
	28	`POST /scopes/:scopeId/openapi/specs` currently accepts `targetScope` in the
	29	payload, duplicating the URL `scopeId` for web usage. The endpoint handler maps
	30	`payload.targetScope` to SDK `scope`.
	31
	32	The payload also accepts `credentialTargetScope`, which is a fallback for direct
	33	secret inputs that do not carry their own binding scope. This is especially
	34	visible in `specFetchCredentials`, where the UI currently serializes direct
	35	secret refs without per-entry scope.
	36
	37	`spec` is a plain string that can mean either:
	38
	39	- an HTTP URL to fetch, or
	40	- raw OpenAPI JSON/YAML text.
	41
	42	`name`, `namespace`, and `baseUrl` are optional in the SDK because they can be
	43	derived from the spec. That is convenient for internal/programmatic callers, but
	44	the web/API boundary already has explicit user-facing values after preview.
	45
	46	## Immediate Endpoint Direction
	47
	48	For the HTTP/web add endpoint:
	49
	50	```txt
	51	POST /scopes/:scopeId/openapi/specs
	52	```
	53
	54	`scopeId` should be the source owner scope. Remove payload `targetScope`.
	55
	56	Make the identity and request base explicit:
	57
	58	```ts
	59	{
	60	spec: OpenApiSpecInput;
	61	name: string;
	62	namespace: string;
	63	baseUrl: string;
	64	// source shape fields...
	65	}
	66	```
	67
	68	Use a discriminated spec input instead of a string that guesses:
	69
	70	```ts
	71	type OpenApiSpecInput = { kind: "url"; url: string } \| { kind: "blob"; value: string };
	72	```
	73
	74	Remove `credentialTargetScope` from the HTTP payload. Scope should always be
	75	explicit anywhere a concrete secret or connection value is written.
	76
	77	Keep SDK-level `scope` on `OpenApiSpecConfig`; non-HTTP callers still need to
	78	choose where a source is added.
	79
	80	## Source Shape vs Values
	81
	82	The source shape is shared. Values can be bound per scope.
	83
	84	Source shape examples:
	85
	86	```ts
	87	headers: {
	88	Authorization: {
	89	kind: "secret",
	90	prefix: "Bearer ",
	91	},
	92	},
	93	queryParams: {
	94	api_version: "2026-05-17",
	95	}
	96	```
	97
	98	This declares:
	99
	100	- every user of the source uses an `Authorization` header with a bearer prefix;
	101	- the concrete token value is supplied separately;
	102	- `api_version` is a shared literal source config value.
	103
	104	Under the hood, secret-shaped headers/query params still normalize to internal
	105	source bindings:
	106
	107	```ts
	108	headers: {
	109	Authorization: {
	110	kind: "binding",
	111	slot: "header:authorization",
	112	prefix: "Bearer ",
	113	},
	114	}
	115	```
	116
	117	Plain text values are not credentials. They can stay directly in source config.
	118
	119	Concrete values should be set through source value binding APIs. The existing
	120	low-level operation is `setSourceBinding`; a later cleanup can add domain-level
	121	wrappers such as `setHeaderValue` or `setQueryParamValue`.
	122
	123	## Example: Org Default With One User Override
	124
	125	```ts
	126	const orgScope = ScopeId.make("org_123");
	127	const aliceScope = ScopeId.make("user-org:alice:org_123");
	128
	129	const source = await executor.openapi.addSpec({
	130	scope: orgScope,
	131	spec: {
	132	kind: "url",
	133	url: "https://api.example.com/openapi.json",
	134	},
	135	name: "Example API",
	136	namespace: "example",
	137	baseUrl: "https://api.example.com",
	138	headers: {
	139	Authorization: {
	140	kind: "secret",
	141	prefix: "Bearer ",
	142	},
	143	},
	144	queryParams: {
	145	api_version: "2026-05-17",
	146	},
	147	});
	148
	149	await executor.secrets.set({
	150	id: SecretId.make("example-org-token"),
	151	scope: orgScope,
	152	name: "Example org token",
	153	value: process.env.EXAMPLE_ORG_TOKEN!,
	154	});
	155
	156	await executor.openapi.setHeaderValue({
	157	source,
	158	scope: orgScope,
	159	name: "Authorization",
	160	value: {
	161	kind: "secret",
	162	secretId: SecretId.make("example-org-token"),
	163	secretScope: orgScope,
	164	},
	165	});
	166
	167	await executor.secrets.set({
	168	id: SecretId.make("alice-example-token"),
	169	scope: aliceScope,
	170	name: "Alice Example token",
	171	value: process.env.ALICE_EXAMPLE_TOKEN!,
	172	});
	173
	174	await executor.openapi.setHeaderValue({
	175	source,
	176	scope: aliceScope,
	177	name: "Authorization",
	178	value: {
	179	kind: "secret",
	180	secretId: SecretId.make("alice-example-token"),
	181	secretScope: aliceScope,
	182	},
	183	});
	184	```
	185
	186	Resolution:
	187
	188	- Alice gets `Authorization: Bearer <alice token>`.
	189	- Other users fall back to `Authorization: Bearer <org token>`.
	190	- The source/tool definition remains org-scoped and shared.
	191
	192	## OAuth Shape
	193
	194	OAuth follows the same split. The source declares shared OAuth metadata:
	195
	196	- security scheme name;
	197	- flow;
	198	- authorization/token URLs;
	199	- scopes;
	200	- where client id/client secret/connection values are expected.
	201
	202	Then values are bound separately:
	203
	204	- OAuth app client id/secret can be org-level values.
	205	- OAuth access/refresh token connection is commonly per user.
	206
	207	Conceptually:
	208
	209	```ts
	210	const source = await executor.openapi.addSpec({
	211	scope: orgScope,
	212	spec: { kind: "url", url: "https://api.example.com/openapi.json" },
	213	name: "Example API",
	214	namespace: "example",
	215	baseUrl: "https://api.example.com",
	216	oauth2: {
	217	securitySchemeName: "oauth2",
	218	flow: "authorizationCode",
	219	authorizationUrl: "https://api.example.com/oauth/authorize",
	220	tokenUrl: "https://api.example.com/oauth/token",
	221	scopes: ["read", "write"],
	222	},
	223	});
	224
	225	await executor.openapi.setOAuthClientCredentials({
	226	source,
	227	scope: orgScope,
	228	clientId: { kind: "secret", secretId: "client-id", secretScope: orgScope },
	229	clientSecret: { kind: "secret", secretId: "client-secret", secretScope: orgScope },
	230	});
	231
	232	await executor.openapi.setOAuthConnection({
	233	source,
	234	scope: aliceScope,
	235	connectionId: aliceConnection.id,
	236	});
	237	```
	238
	239	The current implementation can continue using internal OAuth slots. The public
	240	SDK does not need to expose those slots for the simple flow.
	241
	242	## Spec Fetch Credentials
	243
	244	Spec fetch credentials differ from runtime credentials because they may be
	245	needed before the source exists.
	246
	247	For this immediate pass:
	248
	249	- keep spec fetch credentials on `addSpec`;
	250	- treat them as source-definition credentials;
	251	- make the UI use the same secret scope selection semantics as other secret
	252	inputs;
	253	- remove `credentialTargetScope` by making any concrete spec fetch secret refs
	254	carry explicit scope information.
	255
	256	Longer term, if we want all persisted values to use bindings only, preview may
	257	need either request-only credentials or callers must fetch private specs
	258	themselves and pass `{ kind: "blob", value }`.
	259
	260	## Sharing Boundary
	261
	262	One source has one shared credential structure. Users can provide different
	263	values for that structure, but they cannot change the structure per user.
	264
	265	Supported:
	266
	267	```txt
	268	Source shape: Authorization header with Bearer prefix
	269	Org value: shared token
	270	Alice value: Alice token override
	271	Bob value: Bob token override
	272	```
	273
	274	Not supported as one source:
	275
	276	```txt
	277	Alice uses Authorization: Bearer <token>
	278	Bob uses X-API-Key: <key>
	279	Carol uses OAuth
	280	```
	281
	282	Those are different source instances, even if they point at the same OpenAPI
	283	spec and base URL.
	284
	285	## MCP and Per-User Tool Discovery
	286
	287	MCP exposes a larger issue: some servers may return different tools or tool
	288	descriptions based on the authenticated user. That means auth can affect
	289	discovery, not just invocation.
	290
	291	This does not need to be solved in the OpenAPI add-source cleanup. Defer:
	292
	293	- per-user source rows;
	294	- per-user tool discovery;
	295	- MCP auth-dependent tool descriptions;
	296	- template/materialization flows for user-bound discovery sources.
	297
	298	For now, keep OpenAPI on the stable shared tool surface model.
	299
	300	## Deferred API Cleanup
	301
	302	Leave `setSourceBinding` in place for edit/override flows for now. It is a
	303	lower-level source value binding API and already supports text, secret, and
	304	connection values.
	305
	306	A later public SDK cleanup can add domain-level wrappers:
	307
	308	- `setHeaderValue`;
	309	- `setQueryParamValue`;
	310	- `setSpecFetchHeaderValue`;
	311	- `setSpecFetchQueryParamValue`;
	312	- `setOAuthClientCredentials`;
	313	- `setOAuthConnection`.
	314
	315	Those wrappers can map to internal binding slots without exposing slots to the
	316	consumer-facing simple flow.

notes/openapi-sdk-credential-configuration.md+509−0

@@ -0,0 +1,509 @@
	1	# OpenAPI SDK Credential Configuration Notes
	2
	3	Date: 2026-05-17
	4	Status: planning
	5
	6	## Summary
	7
	8	The SDK should present OpenAPI source onboarding as two explicit phases:
	9
	10	1. Add/import a shared source shape.
	11	2. Configure scoped credential values for that source.
	12
	13	The internal implementation can still use source slots and scoped bindings,
	14	but normal SDK callers should not need to think about `setSourceBinding`,
	15	`connectionSlot`, `clientIdSlot`, `credentialTargetScope`, or plugin-specific
	16	binding row shapes.
	17
	18	The product flow we want to preserve is:
	19
	20	```txt
	21	Admin adds Stripe/Linear/GitHub once at org scope.
	22	Org may set default credentials.
	23	Each user can sign in or provide their own token.
	24	The source and tools stay shared.
	25	Credentials remain scoped and overridable.
	26	```
	27
	28	## Core Vocabulary
	29
	30	Source shape is the shared definition:
	31
	32	- OpenAPI spec and extracted operations.
	33	- Base URL.
	34	- Declared headers and query params the source knows how to send.
	35	- Selected OAuth method, if any.
	36	- OAuth flow metadata such as authorization URL, token URL, and scopes.
	37
	38	Scoped credential values are the concrete values attached later:
	39
	40	- Bearer/API key token values.
	41	- Header/query param text values.
	42	- OAuth client ID and client secret.
	43	- OAuth connection IDs.
	44	- Spec-fetch credential values.
	45
	46	Source shape belongs to the source owner scope. Credential values belong to
	47	the scope where they are configured and can inherit/override through the scope
	48	stack.
	49
	50	## Public SDK Shape
	51
	52	The common bearer token flow should read like this:
	53
	54	```ts
	55	const org = ScopeId.make("org_acme");
	56	const user = ScopeId.make("user_rhys");
	57
	58	const source = await executor.openapi.addSpec({
	59	scope: org,
	60	name: "Stripe",
	61	namespace: "stripe",
	62	baseUrl: "https://api.stripe.com",
	63	spec: {
	64	kind: "url",
	65	url: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
	66	},
	67
	68	headers: {
	69	Authorization: {
	70	prefix: "Bearer ",
	71	},
	72	},
	73	});
	74
	75	await executor.openapi.configure(source, {
	76	scope: user,
	77	headers: {
	78	Authorization: SecretId.make("stripe_api_key"),
	79	},
	80	});
	81	```
	82
	83	The caller should not pass:
	84
	85	```ts
	86	kind: "binding";
	87	slot: "header:authorization";
	88	credentialTargetScope: user;
	89	```
	90
	91	Those are internal implementation details.
	92
	93	## Strict Configure Semantics
	94
	95	`configure` fills declared holes in an existing source shape. It should not
	96	create new source shape.
	97
	98	If the source was imported with:
	99
	100	```ts
	101	headers: {
	102	Authorization: {
	103	prefix: "Bearer ",
	104	},
	105	}
	106	```
	107
	108	then this is valid:
	109
	110	```ts
	111	await executor.openapi.configure(source, {
	112	scope: user,
	113	headers: {
	114	Authorization: SecretId.make("stripe_api_key"),
	115	},
	116	});
	117	```
	118
	119	This should fail:
	120
	121	```ts
	122	await executor.openapi.configure(source, {
	123	scope: user,
	124	headers: {
	125	Username: SecretId.make("stripe_api_key"),
	126	},
	127	});
	128	```
	129
	130	because `Username` was not declared on the source. Allowing this would silently
	131	write a binding for a value the source never sends.
	132
	133	Suggested error:
	134
	135	```txt
	136	Unknown header "Username" for OpenAPI source "stripe".
	137	Declared headers: Authorization.
	138	```
	139
	140	The same rule applies to query params:
	141
	142	```ts
	143	await executor.openapi.configure(source, {
	144	scope: user,
	145	queryParams: {
	146	api_key: SecretId.make("example_api_key"),
	147	},
	148	});
	149	```
	150
	151	should only succeed if `api_key` was declared in the source shape.
	152
	153	Adding or changing source shape should be a different operation:
	154
	155	```ts
	156	await executor.openapi.updateSource(source, {
	157	headers: {
	158	Authorization: { prefix: "Bearer " },
	159	Username: {},
	160	},
	161	});
	162
	163	await executor.openapi.configure(source, {
	164	scope: user,
	165	headers: {
	166	Username: SecretId.make("basic_username"),
	167	},
	168	});
	169	```
	170
	171	## Values Accepted By Configure
	172
	173	`configure` should accept ergonomic value inputs and normalize them to binding
	174	values internally.
	175
	176	```ts
	177	type OpenApiConfiguredCredentialValue =
	178	\| string
	179	\| SecretId
	180	\| {
	181	kind: "secret";
	182	secretId: SecretId;
	183	secretScope?: ScopeId;
	184	}
	185	\| {
	186	kind: "text";
	187	text: string;
	188	};
	189	```
	190
	191	Examples:
	192
	193	```ts
	194	await executor.openapi.configure(source, {
	195	scope: user,
	196	headers: {
	197	Authorization: SecretId.make("stripe_api_key"),
	198	"X-Workspace": "acme",
	199	},
	200	queryParams: {
	201	version: "2026-05-17",
	202	},
	203	});
	204	```
	205
	206	Internal binding writes:
	207
	208	```ts
	209	setBinding({
	210	source: { pluginId: "openapi", id: "stripe", scope: org },
	211	scope: user,
	212	slot: "header:authorization",
	213	value: { kind: "secret", secretId: SecretId.make("stripe_api_key") },
	214	});
	215
	216	setBinding({
	217	source: { pluginId: "openapi", id: "stripe", scope: org },
	218	scope: user,
	219	slot: "header:x-workspace",
	220	value: { kind: "text", text: "acme" },
	221	});
	222
	223	setBinding({
	224	source: { pluginId: "openapi", id: "stripe", scope: org },
	225	scope: user,
	226	slot: "query_param:version",
	227	value: { kind: "text", text: "2026-05-17" },
	228	});
	229	```
	230
	231	## Org Default With User Override
	232
	233	```ts
	234	const source = await executor.openapi.addSpec({
	235	scope: org,
	236	name: "Example API",
	237	namespace: "example",
	238	baseUrl: "https://api.example.com",
	239	spec: {
	240	kind: "url",
	241	url: "https://api.example.com/openapi.json",
	242	},
	243	headers: {
	244	Authorization: {
	245	prefix: "Bearer ",
	246	},
	247	},
	248	});
	249
	250	await executor.openapi.configure(source, {
	251	scope: org,
	252	headers: {
	253	Authorization: SecretId.make("example_org_token"),
	254	},
	255	});
	256
	257	await executor.openapi.configure(source, {
	258	scope: user,
	259	headers: {
	260	Authorization: SecretId.make("example_user_token"),
	261	},
	262	});
	263	```
	264
	265	Resolution:
	266
	267	```txt
	268	User with user binding:
	269	Authorization: Bearer <example_user_token>
	270
	271	User without user binding:
	272	Authorization: Bearer <example_org_token>
	273	```
	274
	275	The source and tools remain org-scoped. Only values vary by scope.
	276
	277	## OAuth Is Not Just A Header
	278
	279	OAuth eventually produces an `Authorization` header, but the setup is not just
	280	"set the Authorization header value." OAuth has distinct source shape and
	281	credential value concerns:
	282
	283	- The selected OpenAPI security scheme.
	284	- OAuth flow.
	285	- Authorization URL.
	286	- Token URL.
	287	- Issuer URL when relevant.
	288	- Scopes.
	289	- Client ID.
	290	- Client secret.
	291	- Connection ID.
	292	- Token refresh lifecycle.
	293
	294	The source should choose one OAuth configuration at import time. After that,
	295	credential operations should not ask the caller to repeat the security scheme
	296	name in the common case.
	297
	298	## Current OpenAPI OAuth Model
	299
	300	Today preview returns `oauth2Presets`, one per supported OAuth option derived
	301	from the spec. The add UI chooses one preset and persists one
	302	`OAuth2SourceConfig` on the source:
	303
	304	```ts
	305	oauth2: {
	306	kind: "oauth2",
	307	securitySchemeName: selectedOAuth2Preset.securitySchemeName,
	308	flow: selectedOAuth2Preset.flow,
	309	authorizationUrl: selectedOAuth2Preset.authorizationUrl,
	310	tokenUrl: selectedOAuth2Preset.tokenUrl,
	311	issuerUrl: selectedOAuth2Preset.issuerUrl ?? null,
	312	clientIdSlot: oauth2ClientIdSlot(selectedOAuth2Preset.securitySchemeName),
	313	clientSecretSlot: oauth2ClientSecretSlot(selectedOAuth2Preset.securitySchemeName),
	314	connectionSlot: oauth2ConnectionSlot(selectedOAuth2Preset.securitySchemeName),
	315	scopes: [...oauth2SelectedScopes],
	316	}
	317	```
	318
	319	Client ID and client secret are stored as scoped bindings:
	320
	321	```ts
	322	setBinding({
	323	slot: oauth2.clientIdSlot,
	324	scope: org,
	325	value: {
	326	kind: "secret",
	327	secretId: SecretId.make("linear_client_id"),
	328	},
	329	});
	330
	331	setBinding({
	332	slot: oauth2.clientSecretSlot,
	333	scope: org,
	334	value: {
	335	kind: "secret",
	336	secretId: SecretId.make("linear_client_secret"),
	337	},
	338	});
	339	```
	340
	341	The user connection is also stored as a scoped binding:
	342
	343	```ts
	344	setBinding({
	345	slot: oauth2.connectionSlot,
	346	scope: user,
	347	value: {
	348	kind: "connection",
	349	connectionId: ConnectionId.make("linear_user_connection"),
	350	},
	351	});
	352	```
	353
	354	That underlying model is sound. The clunky part is exposing the slot names and
	355	raw binding operations as the normal SDK path.
	356
	357	## Proposed OAuth SDK Flow
	358
	359	If the spec has exactly one supported OAuth option, `addSpec` can infer it. If
	360	there are multiple supported OAuth options, `addSpec` should require an
	361	import-time selection.
	362
	363	Single OAuth option:
	364
	365	```ts
	366	const source = await executor.openapi.addSpec({
	367	scope: org,
	368	name: "Linear",
	369	namespace: "linear",
	370	baseUrl: "https://api.linear.app",
	371	spec: {
	372	kind: "url",
	373	url: "https://example.com/linear-openapi.json",
	374	},
	375	oauth: true,
	376	});
	377	```
	378
	379	Multiple OAuth options:
	380
	381	```ts
	382	const source = await executor.openapi.addSpec({
	383	scope: org,
	384	name: "Linear",
	385	namespace: "linear",
	386	baseUrl: "https://api.linear.app",
	387	spec: {
	388	kind: "url",
	389	url: "https://example.com/linear-openapi.json",
	390	},
	391	oauth: {
	392	securityScheme: "linearOAuth",
	393	},
	394	});
	395	```
	396
	397	Configure app credentials:
	398
	399	```ts
	400	await executor.openapi.configure(source, {
	401	scope: org,
	402	oauth: {
	403	clientId: SecretId.make("linear_client_id"),
	404	clientSecret: SecretId.make("linear_client_secret"),
	405	},
	406	});
	407	```
	408
	409	Connect a user:
	410
	411	```ts
	412	await executor.openapi.connect(source, {
	413	scope: user,
	414	});
	415	```
	416
	417	Client credentials flow should use the same public concepts:
	418
	419	```ts
	420	await executor.openapi.configure(source, {
	421	scope: org,
	422	oauth: {
	423	clientId: SecretId.make("service_client_id"),
	424	clientSecret: SecretId.make("service_client_secret"),
	425	},
	426	});
	427
	428	await executor.openapi.connect(source, {
	429	scope: org,
	430	});
	431	```
	432
	433	Internally this still writes:
	434
	435	```txt
	436	oauth2:<selected-security-scheme>:client-id
	437	oauth2:<selected-security-scheme>:client-secret
	438	oauth2:<selected-security-scheme>:connection
	439	```
	440
	441	but SDK callers do not see those slots.
	442
	443	## OAuth Validation
	444
	445	`configure(source, { oauth: ... })` should fail if the source has no selected
	446	OAuth config:
	447
	448	```txt
	449	OpenAPI source "stripe" does not declare OAuth credentials.
	450	```
	451
	452	`connect(source, { scope })` should fail if the source has no selected OAuth
	453	config:
	454
	455	```txt
	456	OpenAPI source "stripe" does not support OAuth connect.
	457	```
	458
	459	`connect` should validate required client credentials before starting OAuth:
	460
	461	```txt
	462	Client ID must be configured before connecting.
	463	Client secret must be configured before connecting.
	464	```
	465
	466	For authorization-code flows, client secret may be optional for public PKCE
	467	clients. For client-credentials flows, client secret is required.
	468
	469	## Configure Should Be A Facade
	470
	471	The public OpenAPI SDK can expose:
	472
	473	```ts
	474	executor.openapi.addSpec(...)
	475	executor.openapi.configure(...)
	476	executor.openapi.connect(...)
	477	```
	478
	479	The lower-level core API can still expose generic bindings for advanced or UI
	480	infrastructure cases:
	481
	482	```ts
	483	executor.sources.setBinding(...)
	484	executor.sources.listBindings(...)
	485	executor.sources.removeBinding(...)
	486	executor.sources.getSlotManifest(...)
	487	```
	488
	489	But the common OpenAPI SDK path should not require users to manually map:
	490
	491	```txt
	492	Authorization -> header:authorization
	493	OAuth client ID -> oauth2:<scheme>:client-id
	494	OAuth connection -> oauth2:<scheme>:connection
	495	```
	496
	497	The SDK should derive that mapping from the selected source shape.
	498
	499	## Design Rule
	500
	501	`addSpec` defines what this source can use.
	502
	503	`configure` assigns values to things this source already declared.
	504
	505	`connect` creates or refreshes OAuth connection values for the selected OAuth
	506	configuration.
	507
	508	Bindings and slots are the internal storage/resolution mechanism behind those
	509	operations.

notes/source-binding-consolidation.md+209−0

@@ -0,0 +1,209 @@
	1	# Source Binding Consolidation Notes
	2
	3	Date: 2026-05-17
	4	Status: exploring
	5
	6	## Context
	7
	8	The branch `codex/fix-openapi-add-flow` shipped a focused cleanup of the
	9	OpenAPI add-source API (see `openapi-add-source-api-cleanup.md`). Looking
	10	across the OpenAPI, GraphQL, and MCP plugins while reviewing that work
	11	turned up a much larger duplication problem. This note captures the
	12	direction we're considering before drafting a real plan.
	13
	14	## What's duplicated today
	15
	16	Each of OpenAPI, GraphQL, and MCP independently reimplements the same
	17	source-binding machinery on top of the core `credential_binding` table:
	18
	19	- A plugin-specific `SourceBindingInput` / `SourceBindingRef` type that
	20	is a thin re-skin of core `CredentialBindingInput` / `CredentialBindingRef`.
	21	- A `resolve*SourceBinding` helper that filters bindings by
	22	`slotKey === slot` and picks the innermost-visible binding whose scope
	23	rank ≤ the source's owner-scope rank. Identical across plugins.
	24	- A `list*SourceBindings` helper applying the same scope-ceiling filter.
	25	- A `validate*BindingTarget` helper that re-checks the same outer-scope
	26	rule core's `assertCredentialBindingTargetNotOuter` already enforces.
	27	- A `coreBindingToXxxBinding` adapter that exists only because the
	28	per-plugin Ref type is a re-skin.
	29	- Per-plugin HTTP endpoints: `setSourceBinding`, `listSourceBindings`,
	30	`removeSourceBinding`. Same payloads, same semantics, mounted under
	31	different paths.
	32	- A `canonicalizeCredentialMap` / `canonicalizeAuth` that splits an input
	33	"shape with secret refs" into a stored shape (with binding sentinels)
	34	plus a list of bindings to write. Same algorithm per plugin.
	35	- React glue: each plugin re-wires `secret-header-auth`,
	36	`credential-target-scope`, and `oauth-sign-in` into its own add flow.
	37
	38	Storage-side, each plugin owns nearly-identical child tables:
	39
	40	- OpenAPI: `openapi_source_header`, `openapi_source_query_param`,
	41	`openapi_source_spec_fetch_header`,
	42	`openapi_source_spec_fetch_query_param`.
	43	- GraphQL: `graphql_source_header`, `graphql_source_query_param`.
	44	- MCP: `mcp_source_header`, `mcp_source_query_param`.
	45
	46	All eight tables share the exact same columns:
	47	`(source_id, scope_id, name, kind, text_value, slot_key, prefix)`.
	48	They're discriminated only by which logical compartment the plugin is
	49	modeling. They're written and read wholesale per source (bulk delete +
	50	bulk insert; bulk findMany). No query filters by `name`, `slot_key`,
	51	`kind`, or `prefix`. No join uses them. The Drizzle mirrors in
	52	`apps/cloud` and `apps/local` are the only non-store consumers.
	53
	54	## The arbitrary-source-types constraint
	55
	56	We expect to support source types beyond HTTP-ish protocols: CLI
	57	sources (argv + env), database connection strings (templated URIs like
	58	`mysql://user:{{password_slot}}@host/db`), and others we haven't named.
	59
	60	That changes the design center of any shared abstraction:
	61
	62	- The HTTP-flavored vocabulary baked into the current shared bits
	63	(`header:`, `query_param:`, `prefix`) doesn't generalize.
	64	- A DB source doesn't have headers; a CLI source doesn't have query
	65	params. The notion of "compartment" is plugin-specific.
	66	- A connection-string source needs interpolation, not just whole-field
	67	substitution. `prefix` is a degenerate one-hole template; argv and
	68	URIs want full templating.
	69
	70	The only protocol-agnostic primitive is: _"named slot at
	71	(plugin, source, source_scope, scope) resolving to a value of kind
	72	text \| secret \| connection."_ That's already what core
	73	`credential_binding` provides.
	74
	75	## Revised consolidation thesis
	76
	77	Core should own the binding primitive, not just the storage.
	78
	79	Core owns:
	80
	81	- The `credential_binding` table (today).
	82	- The resolver: given `(pluginId, sourceId, sourceScope, slot, scope)`,
	83	return the innermost-visible binding subject to the source-scope
	84	ceiling. Today this is duplicated per plugin.
	85	- Validation: scope-stack membership, "binding target not outer than
	86	source," secret/connection reachability. The facade already has the
	87	inner checks; the plugin-side `validate*BindingTarget` helpers can go.
	88	- HTTP endpoints for `setBinding` / `listBindings` / `removeBinding`,
	89	parameterised by `pluginId` in the path (or payload).
	90	- A small _slot manifest_ concept: each plugin declares, for a given
	91	source, which slot keys exist, their human-readable labels, expected
	92	value kind, required/optional, and any rendering hints. The UI uses
	93	this to render a credential editor for any plugin without bespoke
	94	React code.
	95
	96	Plugins own:
	97
	98	- Their source-shape storage. Whatever's plugin-specific (OpenAPI:
	99	spec/baseUrl/operations; GraphQL: endpoint/operations; MCP:
	100	transport/config; DB: connection-string template; CLI: argv/env).
	101	The nearly-identical child tables go away; shape moves to JSON on
	102	the source row or whatever structural columns the plugin actually
	103	needs.
	104	- The wire-format glue: how a resolved slot value becomes an HTTP
	105	header, an MCP transport handshake parameter, a DB connection
	106	string, a CLI argv entry.
	107	- Their slot manifest content. OpenAPI generates it from the parsed
	108	spec; MCP from connect-time metadata; DB from the URI template's
	109	holes.
	110
	111	Plugins do not own:
	112
	113	- Re-skinned binding types.
	114	- Their own resolver / lister / validator.
	115	- Their own `setSourceBinding` HTTP endpoint.
	116	- Hand-written credential-editor React glue, beyond plugin-specific
	117	manifest hints.
	118
	119	## What this changes vs the current plan
	120
	121	The existing `openapi-add-source-api-cleanup.md` proposes deferred
	122	domain wrappers (`setHeaderValue`, `setQueryParamValue`,
	123	`setOAuthClientCredentials`, `setOAuthConnection`). Under the
	124	consolidated model those wrappers stop making sense — they pre-suppose
	125	HTTP-ish compartments. The consumer-facing API becomes "set this slot
	126	on this source," parameterised by a slot key the plugin's manifest
	127	defines. UX affordances like header preset pickers move into the UI
	128	layer, driven by the manifest.
	129
	130	The plan note's "source shape vs values" split is still right; it just
	131	applies more aggressively. Shape lives in plugin source config (JSON
	132	or columns the plugin actually queries on); values live in core
	133	bindings.
	134
	135	## On `prefix`
	136
	137	`prefix` is a UI/UX affordance for the `Authorization: Bearer <token>`
	138	pattern, generalised to "any prepended literal string." It is stored
	139	in three places (core `ConfiguredCredentialBinding`,
	140	`ScopedSecretCredentialInput`, plugin child-table columns) and
	141	consumed at exactly one site per plugin:
	142
	143	```ts
	144	resolved[name] = value.prefix ? `${value.prefix}${secret}` : secret;
	145	```
	146
	147	No escaping, no suffix, no conditional logic. It exists so the secret
	148	itself doesn't have to bake `Bearer ` into the value and so the UI can
	149	render a separate prefix input next to the secret picker.
	150
	151	It does not generalise to connection strings or argv. The right move
	152	is to drop `prefix` from core entirely and either:
	153
	154	1. Have it live in the plugin's slot manifest as a pure UI hint, with
	155	the resolver still returning the raw secret value and the plugin
	156	doing the concatenation in its wire-format layer; or
	157	2. Subsume it into a plugin-owned template ("this slot's value is
	158	interpolated into this string"), which is the same idea generalised
	159	to multi-hole shapes.
	160
	161	Either way the resolver stops doing string concatenation.
	162
	163	## On the OpenAPI normalized child tables
	164
	165	In the local-cleanup framing they look wrong because the same four
	166	columns are duplicated four times. In the arbitrary-source-types
	167	framing they look wrong for a deeper reason: they bake HTTP
	168	compartment vocabulary into the schema. They should go away rather
	169	than be consolidated.
	170
	171	Two reasonable destinations:
	172
	173	- JSON on the source row. Same place OAuth2 config already lives.
	174	Access pattern (read all, replace all) already matches what a JSON
	175	blob gives you.
	176	- Plugin-owned structural columns where they matter. If a plugin
	177	truly benefits from a normalized shape table for its own queries,
	178	it can have one; OpenAPI/GraphQL/MCP currently don't.
	179
	180	## Open questions
	181
	182	1. Third-party plugins. Do we expect plugin authors outside this
	183	repo? That sets the stability bar for the slot manifest contract
	184	and the resolver API.
	185	2. Templating layer. Is there one core mini-template language
	186	(`{{slot}}`) that plugins opt into, or is interpolation strictly
	187	plugin-owned? Shared templating gives consistent UX (preview the
	188	resolved value in the UI, redact in logs uniformly); per-plugin
	189	templating gives more freedom but reinvents.
	190	3. Migration order. Sketch the core API first and prove it on
	191	OpenAPI as the proving ground, then port GraphQL and MCP in
	192	follow-ups. Each step independently mergeable.
	193	4. Existing PR. Land or shelve `codex/fix-openapi-add-flow` as-is
	194	before the bigger consolidation opens; do not swallow the focused
	195	cleanup into the larger refactor.
	196
	197	## Suggested next steps
	198
	199	- Close out the existing PR.
	200	- Draft a real plan note that specifies the core API surface (resolver
	201	signature, manifest shape, HTTP endpoints) before touching code.
	202	- Once the shape is agreed, port OpenAPI first: delete the four child
	203	tables, move shape to source-row storage, replace the plugin-level
	204	binding helpers with core calls, replace the plugin-level HTTP group
	205	with a core one.
	206	- Port GraphQL and MCP to match.
	207	- Pick the first arbitrary source type (likely DB connection string or
	208	CLI) as a forcing function to validate the abstraction works beyond
	209	HTTP-ish shapes.

packages/kernel/runtime-dynamic-worker/src/integration.test.ts+7−1

         plugins,
         onElicitation: "accept-all",
       });
-      yield* executor.openapi.addSpec({ spec, scope: TEST_SCOPE, namespace, baseUrl });
+      yield* executor.openapi.addSpec({
+        spec: { kind: "blob", value: spec },
+        scope: TEST_SCOPE,
+        namespace,
+        name: namespace,
+        baseUrl,
+      });
       const invoker = makeExecutorToolInvoker(executor, { invokeOptions: autoApprove });
       return { executor, invoker, captured: recording.captured, sql };
     }),

packages/plugins/openapi/src/api/group.ts+23−31

 import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Schema } from "effect";
-import {
+import { InternalError, ScopeId, SecretBackedValue } from "@executor-js/sdk/shared";
-  InternalError,
-  ScopeId,
-  ScopedSecretCredentialInput,
-  SecretBackedValue,
-} from "@executor-js/sdk/shared";
 import { OpenApiParseError, OpenApiExtractionError, OpenApiOAuthError } from "../sdk/errors";
 import { SpecPreview } from "../sdk/preview";
   sourceScopeId: ScopeId,
 };
-const SpecFetchCredentialsPayload = Schema.Struct({
+const OpenApiSpecInputPayload = Schema.Union([
+  Schema.Struct({ kind: Schema.Literal("url"), url: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("blob"), value: Schema.String }),
+]);
+const PreviewSpecFetchCredentialsPayload = Schema.Struct({
   headers: Schema.optional(Schema.Record(Schema.String, SecretBackedValue)),
   queryParams: Schema.optional(Schema.Record(Schema.String, SecretBackedValue)),
 });
-const ConfiguredCredentialBindingPayload = Schema.Struct({
+const OpenApiSecretShapePayload = Schema.Struct({
-  kind: Schema.Literal("binding"),
+  kind: Schema.Literal("secret"),
-  slot: Schema.String,
   prefix: Schema.optional(Schema.String),
 });
-const ConfiguredCredentialValuePayload = Schema.Union([
+const OpenApiConfiguredValuePayload = Schema.Union([Schema.String, OpenApiSecretShapePayload]);
-  Schema.String,
-  ConfiguredCredentialBindingPayload,
-]);
-const OpenApiCredentialInputPayload = Schema.Union([
+const SpecFetchCredentialsPayload = Schema.Struct({
-  ScopedSecretCredentialInput,
+  headers: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
-  SecretBackedValue,
+  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
-  ConfiguredCredentialValuePayload,
+});
-]);
 // ---------------------------------------------------------------------------
 // Payloads
 // ---------------------------------------------------------------------------
 const AddSpecPayload = Schema.Struct({
-  targetScope: ScopeId,
+  spec: OpenApiSpecInputPayload,
-  credentialTargetScope: Schema.optional(ScopeId),
-  spec: Schema.String,
   specFetchCredentials: Schema.optional(SpecFetchCredentialsPayload),
-  name: Schema.optional(Schema.String),
+  name: Schema.String,
-  baseUrl: Schema.optional(Schema.String),
+  baseUrl: Schema.String,
-  namespace: Schema.optional(Schema.String),
+  namespace: Schema.String,
-  headers: Schema.optional(Schema.Record(Schema.String, OpenApiCredentialInputPayload)),
+  headers: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
-  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiCredentialInputPayload)),
+  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
   oauth2: Schema.optional(OAuth2SourceConfig),
 });
 const PreviewSpecPayload = Schema.Struct({
   spec: Schema.String,
-  specFetchCredentials: Schema.optional(SpecFetchCredentialsPayload),
+  specFetchCredentials: Schema.optional(PreviewSpecFetchCredentialsPayload),
 });
 const UpdateSourcePayload = Schema.Struct({
   sourceScope: ScopeId,
   name: Schema.optional(Schema.String),
   baseUrl: Schema.optional(Schema.String),
-  headers: Schema.optional(Schema.Record(Schema.String, OpenApiCredentialInputPayload)),
+  headers: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
-  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiCredentialInputPayload)),
+  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValuePayload)),
-  credentialTargetScope: Schema.optional(ScopeId),
   // Set after a successful re-authenticate to refresh the source's
   // stored OAuth2 metadata.
   oauth2: Schema.optional(OAuth2SourceConfig),

packages/plugins/openapi/src/api/handlers.ts+11−14

 import { addGroup, capture } from "@executor-js/api";
 import type {
-  ConfiguredHeaderValue,
+  OpenApiConfiguredValueInput,
   OpenApiPluginExtension,
-  HeaderValue,
+  OpenApiPreviewSpecFetchCredentialsInput,
-  OpenApiCredentialInput,
   OpenApiSpecFetchCredentialsInput,
   OpenApiUpdateSourceInput,
 } from "../sdk/plugin";
           return yield* ext.previewSpec({
             spec: payload.spec,
             specFetchCredentials: payload.specFetchCredentials as
-              | OpenApiSpecFetchCredentialsInput
+              | OpenApiPreviewSpecFetchCredentialsInput
               | undefined,
           });
         }),
       ),
     )
-    .handle("addSpec", ({ payload }) =>
+    .handle("addSpec", ({ params: path, payload }) =>
       capture(
         Effect.gen(function* () {
           const ext = yield* OpenApiExtensionService;
             specFetchCredentials: payload.specFetchCredentials as
               | OpenApiSpecFetchCredentialsInput
               | undefined,
-            scope: payload.targetScope,
+            scope: path.scopeId,
             name: payload.name,
             baseUrl: payload.baseUrl,
             namespace: payload.namespace,
-            credentialTargetScope: payload.credentialTargetScope,
+            headers: payload.headers as Record<string, OpenApiConfiguredValueInput> | undefined,
-            headers: payload.headers as
+            queryParams: payload.queryParams as
-              | Record<string, HeaderValue | ConfiguredHeaderValue>
+              | Record<string, OpenApiConfiguredValueInput>
               | undefined,
-            queryParams: payload.queryParams as Record<string, OpenApiCredentialInput> | undefined,
             oauth2: payload.oauth2,
           });
           return {
           yield* ext.updateSource(path.namespace, payload.sourceScope, {
             name: payload.name,
             baseUrl: payload.baseUrl,
-            headers: payload.headers as
+            headers: payload.headers as Record<string, OpenApiConfiguredValueInput> | undefined,
-              | Record<string, HeaderValue | ConfiguredHeaderValue>
+            queryParams: payload.queryParams as
+              | Record<string, OpenApiConfiguredValueInput>
               | undefined,
-            queryParams: payload.queryParams as Record<string, OpenApiCredentialInput> | undefined,
-            credentialTargetScope: payload.credentialTargetScope,
             oauth2: payload.oauth2,
           } as OpenApiUpdateSourceInput);
           return { updated: true };

packages/plugins/openapi/src/react/AddOpenApiSource.tsx+143−110

@@ -1,5 +1,6 @@
1	import { useCallback, useEffect, useMemo, useRef, useState } from "react";	1	import { useCallback, useEffect, useMemo, useRef, useState } from "react";
2	import { useAtomSet } from "@effect/atom-react";	2	import { useAtomSet } from "@effect/atom-react";
		3	import * as Effect from "effect/Effect";
3	import * as Exit from "effect/Exit";	4	import * as Exit from "effect/Exit";
4	import * as Match from "effect/Match";	5	import * as Match from "effect/Match";
5	import * as Option from "effect/Option";	6	import * as Option from "effect/Option";
@@ -66,13 +67,10 @@ import { · 60 unmodified lines
66	oauth2ClientSecretSlot,	67	oauth2ClientSecretSlot,
67	oauth2ConnectionSlot,	68	oauth2ConnectionSlot,
68	queryParamBindingSlot,	69	queryParamBindingSlot,
		70	specFetchHeaderBindingSlot,
		71	specFetchQueryParamBindingSlot,
69	} from "../sdk/source-contracts";	72	} from "../sdk/source-contracts";
70	import {	73	import { OAuth2SourceConfig, OpenApiSourceBindingInput, type ServerInfo } from "../sdk/types";
71	ConfiguredHeaderBinding,
72	OAuth2SourceConfig,
73	OpenApiSourceBindingInput,
74	type ServerInfo,
75	} from "../sdk/types";
76	import { expandServerUrlOptions } from "../sdk/openapi-utils";	74	import { expandServerUrlOptions } from "../sdk/openapi-utils";
77		75
78	export const OPENAPI_OAUTH_POPUP_NAME = "openapi-oauth";	76	export const OPENAPI_OAUTH_POPUP_NAME = "openapi-oauth";
@@ -128,6 +126,19 @@ export function inferOAuthIssuerUrl(authorizationUrl: string): string \| null { · 49 unmodified lines
128	}	126	}
129	}	127	}
130		128
		129	const specInputForAdd = (input: string) => {
		130	const value = input.trim();
		131	const parsed = Effect.runSyncExit(
		132	Effect.try({
		133	try: () => new URL(value),
		134	catch: () => null,
		135	}),
		136	);
		137	return Exit.isSuccess(parsed)
		138	? { kind: "url" as const, url: value }
		139	: { kind: "blob" as const, value };
		140	};
		141
131	type StrategySelection =	142	type StrategySelection =
132	\| { readonly kind: "none" }	143	\| { readonly kind: "none" }
133	\| { readonly kind: "custom" }	144	\| { readonly kind: "custom" }
@@ -256,35 +267,19 @@ export default function AddOpenApiSource(props: { · 122 unmodified lines
256	})),	267	})),
257	[scopeStack],	268	[scopeStack],
258	);	269	);
259	const defaultCredentialTargetScope =
260	credentialScopeOptions[credentialScopeOptions.length - 1]?.scopeId ?? scopeId;
261	const defaultOAuthTokenTargetScope = credentialScopeOptions[0]?.scopeId ?? scopeId;	270	const defaultOAuthTokenTargetScope = credentialScopeOptions[0]?.scopeId ?? scopeId;
262	const [credentialTargetScope, setCredentialTargetScope] = useState<ScopeId>(
263	defaultCredentialTargetScope,
264	);
265	const [oauthTokenTargetScope, setOAuthTokenTargetScope] = useState<ScopeId>(	271	const [oauthTokenTargetScope, setOAuthTokenTargetScope] = useState<ScopeId>(
266	defaultOAuthTokenTargetScope,	272	defaultOAuthTokenTargetScope,
267	);	273	);
268	const bindingScopeOptions = useMemo(	274	const sourceCredentialScopeOptions = useMemo(
269	() => credentialScopeOptions.map((option) => ({ ...option })),	275	() => credentialScopeOptions.filter((option) => option.scopeId === scopeId),
270	[credentialScopeOptions],	276	[credentialScopeOptions, scopeId],
271	);	277	);
272	useEffect(() => {
273	if (!credentialScopeOptions.some((option) => option.scopeId === credentialTargetScope)) {
274	setCredentialTargetScope(defaultCredentialTargetScope);
275	}
276	}, [credentialScopeOptions, credentialTargetScope, defaultCredentialTargetScope]);
277	useEffect(() => {	278	useEffect(() => {
278	if (!credentialScopeOptions.some((option) => option.scopeId === oauthTokenTargetScope)) {	279	if (!credentialScopeOptions.some((option) => option.scopeId === oauthTokenTargetScope)) {
279	setOAuthTokenTargetScope(defaultOAuthTokenTargetScope);	280	setOAuthTokenTargetScope(defaultOAuthTokenTargetScope);
280	}	281	}
281	}, [credentialScopeOptions, defaultOAuthTokenTargetScope, oauthTokenTargetScope]);	282	}, [credentialScopeOptions, defaultOAuthTokenTargetScope, oauthTokenTargetScope]);
282	const initialCredentialScopeOption =
283	credentialScopeOptions.find((option) => option.scopeId === credentialTargetScope) ??
284	credentialScopeOptions[0];
285	const initialCredentialScopeOptions = initialCredentialScopeOption
286	? [initialCredentialScopeOption]
287	: [];
288	const doPreview = useAtomSet(previewOpenApiSpec, { mode: "promiseExit" });	283	const doPreview = useAtomSet(previewOpenApiSpec, { mode: "promiseExit" });
289	const doAdd = useAtomSet(addOpenApiSpecOptimistic(scopeId), {	284	const doAdd = useAtomSet(addOpenApiSpecOptimistic(scopeId), {
290	mode: "promiseExit",	285	mode: "promiseExit",
@@ -294,9 +289,9 @@ export default function AddOpenApiSource(props: { · 3 unmodified lines
294	mode: "promiseExit",	289	mode: "promiseExit",
295	});	290	});
296	const secretList = useSecretPickerSecrets();	291	const secretList = useSecretPickerSecrets();
297	const initialCredentialSecrets = useMemo(	292	const sourceCredentialSecrets = useMemo(
298	() => secretList.filter((secret) => secret.scopeId === String(credentialTargetScope)),	293	() => secretList.filter((secret) => secret.scopeId === String(scopeId)),
299	[credentialTargetScope, secretList],	294	[scopeId, secretList],
300	);	295	);
301	const oauth = useOAuthPopupFlow<OAuthCompletionPayload>({	296	const oauth = useOAuthPopupFlow<OAuthCompletionPayload>({
302	popupName: OPENAPI_OAUTH_POPUP_NAME,	297	popupName: OPENAPI_OAUTH_POPUP_NAME,
@@ -336,35 +331,29 @@ export default function AddOpenApiSource(props: { · 33 unmodified lines
336	);	331	);
337		332
338	const resolvedBaseUrl = baseUrl.trim();	333	const resolvedBaseUrl = baseUrl.trim();
		334	const sourceScope = ScopeId.make(scopeId);
339		335
340	const configuredHeaders: Record<string, ConfiguredHeaderBinding> = {};	336	type PendingSecretBinding = {
341	const headerBindings: Array<{	337	readonly slot: string;
342	slot: string;	338	readonly secretId: string;
343	secretId: string;	339	readonly scope: ScopeId;
344	scope: ScopeId;	340	readonly secretScope: ScopeId;
345	secretScope: ScopeId;	341	};
346	}> = [];	342
347	const configuredQueryParams: Record<string, string \| ConfiguredHeaderBinding> = {};	343	const configuredHeaders: Record<string, { kind: "secret"; prefix?: string }> = {};
348	const queryParamBindings: Array<{	344	const headerBindings: PendingSecretBinding[] = [];
349	slot: string;	345	const configuredQueryParams: Record<string, string \| { kind: "secret"; prefix?: string }> = {};
350	secretId: string;	346	const queryParamBindings: PendingSecretBinding[] = [];
351	scope: ScopeId;
352	secretScope: ScopeId;
353	}> = [];
354	for (const ch of customHeaders) {	347	for (const ch of customHeaders) {
355	if (!ch.name.trim()) continue;	348	if (!ch.name.trim()) continue;
356	const slot = headerBindingSlot(ch.name.trim());	349	const slot = headerBindingSlot(ch.name.trim());
357	configuredHeaders[ch.name.trim()] = ConfiguredHeaderBinding.make({	350	configuredHeaders[ch.name.trim()] = { kind: "secret", prefix: ch.prefix };
358	kind: "binding",
359	slot,
360	prefix: ch.prefix,
361	});
362	if (ch.secretId) {	351	if (ch.secretId) {
363	headerBindings.push({	352	headerBindings.push({
364	slot,	353	slot,
365	secretId: ch.secretId,	354	secretId: ch.secretId,
366	scope: ch.targetScope ?? credentialTargetScope,	355	scope: sourceScope,
367	secretScope: ch.secretScope ?? ch.targetScope ?? credentialTargetScope,	356	secretScope: ch.secretScope ?? sourceScope,
368	});	357	});
369	}	358	}
370	}	359	}
@@ -373,16 +362,12 @@ export default function AddOpenApiSource(props: { · 2 unmodified lines
373	if (!name) continue;	362	if (!name) continue;
374	if (param.secretId) {	363	if (param.secretId) {
375	const slot = queryParamBindingSlot(name);	364	const slot = queryParamBindingSlot(name);
376	configuredQueryParams[name] = ConfiguredHeaderBinding.make({	365	configuredQueryParams[name] = { kind: "secret", prefix: param.prefix };
377	kind: "binding",
378	slot,
379	prefix: param.prefix,
380	});
381	queryParamBindings.push({	366	queryParamBindings.push({
382	slot,	367	slot,
383	secretId: param.secretId,	368	secretId: param.secretId,
384	scope: param.targetScope ?? credentialTargetScope,	369	scope: sourceScope,
385	secretScope: param.secretScope ?? param.targetScope ?? credentialTargetScope,	370	secretScope: param.secretScope ?? sourceScope,
386	});	371	});
387	continue;	372	continue;
388	}	373	}
@@ -390,6 +375,52 @@ export default function AddOpenApiSource(props: { · 1 unmodified line
390	configuredQueryParams[name] = param.literalValue.trim();	375	configuredQueryParams[name] = param.literalValue.trim();
391	}	376	}
392	}	377	}
		378	const configuredSpecFetchHeaders: Record<string, { kind: "secret"; prefix?: string }> = {};
		379	const configuredSpecFetchQueryParams: Record<
		380	string,
		381	string \| { kind: "secret"; prefix?: string }
		382	> = {};
		383	const specFetchBindings: PendingSecretBinding[] = [];
		384	for (const header of specFetchCredentials.headers) {
		385	const name = header.name.trim();
		386	if (!name \|\| !header.secretId) continue;
		387	configuredSpecFetchHeaders[name] = { kind: "secret", prefix: header.prefix };
		388	specFetchBindings.push({
		389	slot: specFetchHeaderBindingSlot(name),
		390	secretId: header.secretId,
		391	scope: sourceScope,
		392	secretScope: header.secretScope ?? sourceScope,
		393	});
		394	}
		395	for (const param of specFetchCredentials.queryParams) {
		396	const name = param.name.trim();
		397	if (!name) continue;
		398	if (param.secretId) {
		399	configuredSpecFetchQueryParams[name] = { kind: "secret", prefix: param.prefix };
		400	specFetchBindings.push({
		401	slot: specFetchQueryParamBindingSlot(name),
		402	secretId: param.secretId,
		403	scope: sourceScope,
		404	secretScope: param.secretScope ?? sourceScope,
		405	});
		406	continue;
		407	}
		408	if (param.literalValue?.trim()) {
		409	configuredSpecFetchQueryParams[name] = param.literalValue.trim();
		410	}
		411	}
		412	const configuredSpecFetchCredentials =
		413	Object.keys(configuredSpecFetchHeaders).length > 0 \|\|
		414	Object.keys(configuredSpecFetchQueryParams).length > 0
		415	? {
		416	...(Object.keys(configuredSpecFetchHeaders).length > 0
		417	? { headers: configuredSpecFetchHeaders }
		418	: {}),
		419	...(Object.keys(configuredSpecFetchQueryParams).length > 0
		420	? { queryParams: configuredSpecFetchQueryParams }
		421	: {}),
		422	}
		423	: null;
393		424
394	const oauth2Presets: readonly OAuth2Preset[] = preview?.oauth2Presets ?? [];	425	const oauth2Presets: readonly OAuth2Preset[] = preview?.oauth2Presets ?? [];
395	const oauth2RedirectUrl = oauthCallbackUrl(OPENAPI_OAUTH_CALLBACK_PATH);	426	const oauth2RedirectUrl = oauthCallbackUrl(OPENAPI_OAUTH_CALLBACK_PATH);
@@ -447,8 +478,14 @@ export default function AddOpenApiSource(props: { · 51 unmodified lines
447	const hasIncompleteQueryCredentials = runtimeCredentials.queryParams.some(	478	const hasIncompleteQueryCredentials = runtimeCredentials.queryParams.some(
448	(param) => param.name.trim() && !param.secretId && !param.literalValue?.trim(),	479	(param) => param.name.trim() && !param.secretId && !param.literalValue?.trim(),
449	);	480	);
		481	const hasIncompleteSpecFetchCredentials =
		482	specFetchCredentials.headers.some((header) => header.name.trim() && !header.secretId) \|\|
		483	specFetchCredentials.queryParams.some(
		484	(param) => param.name.trim() && !param.secretId && !param.literalValue?.trim(),
		485	);
450	const willAddWithoutInitialCredentials =	486	const willAddWithoutInitialCredentials =
451	Boolean(selectedOAuth2Preset && !oauth2Auth) \|\|	487	Boolean(selectedOAuth2Preset && !oauth2Auth) \|\|
		488	hasIncompleteSpecFetchCredentials \|\|
452	hasIncompleteHeaderCredentials \|\|	489	hasIncompleteHeaderCredentials \|\|
453	hasIncompleteQueryCredentials;	490	hasIncompleteQueryCredentials;
454		491
@@ -539,24 +576,6 @@ export default function AddOpenApiSource(props: { · 84 unmodified lines
539	}	576	}
540	};	577	};
541		578
542	const setInitialCredentialScope = (targetScope: ScopeId) => {
543	setCredentialTargetScope(targetScope);
544	setCustomHeaders((headers) =>
545	headers.map((header) => ({
546	...header,
547	targetScope,
548	...(header.secretScope && header.secretScope !== targetScope
549	? { secretId: null, secretScope: undefined }
550	: {}),
551	})),
552	);
553	setOauth2ClientIdSecretId(null);
554	setOauth2ClientSecretSecretId(null);
555	setOauth2ClientIdScope(null);
556	setOauth2ClientSecretScope(null);
557	setOauth2AuthState(null);
558	};
559
560	const toggleOAuth2Scope = (scope: string) => {	579	const toggleOAuth2Scope = (scope: string) => {
561	setOauth2SelectedScopes((prev) => {	580	setOauth2SelectedScopes((prev) => {
562	const copy = new Set(prev);	581	const copy = new Set(prev);
@@ -709,13 +728,13 @@ export default function AddOpenApiSource(props: { · 146 unmodified lines
709	const exit = await doAdd({	728	const exit = await doAdd({
710	params: { scopeId },	729	params: { scopeId },
711	payload: {	730	payload: {
712	targetScope: scopeId,	731	spec: specInputForAdd(specUrl),
713	credentialTargetScope,
714	spec: specUrl,
715	specFetchCredentials: serializeHttpCredentials(specFetchCredentials),
716	name: displayName,	732	name: displayName,
717	namespace,	733	namespace,
718	baseUrl: resolvedBaseUrl \|\| undefined,	734	baseUrl: resolvedBaseUrl,
		735	...(configuredSpecFetchCredentials
		736	? { specFetchCredentials: configuredSpecFetchCredentials }
		737	: {}),
719	...(hasHeaders ? { headers: configuredHeaders } : {}),	738	...(hasHeaders ? { headers: configuredHeaders } : {}),
720	...(Object.keys(configuredQueryParams).length > 0	739	...(Object.keys(configuredQueryParams).length > 0
721	? { queryParams: configuredQueryParams }	740	? { queryParams: configuredQueryParams }
@@ -731,11 +750,9 @@ export default function AddOpenApiSource(props: { · 9 unmodified lines
731	}	750	}
732		751
733	const sourceId = exit.value.namespace;	752	const sourceId = exit.value.namespace;
734	const sourceScope = ScopeId.make(scopeId);
735	const bindingScope = ScopeId.make(credentialTargetScope);
736	const oauthTokenBindingScope = ScopeId.make(oauthTokenTargetScope);	753	const oauthTokenBindingScope = ScopeId.make(oauthTokenTargetScope);
737	const clientIdSecretScope = oauth2ClientIdScope ?? bindingScope;	754	const clientIdSecretScope = oauth2ClientIdScope ?? sourceScope;
738	const clientSecretSecretScope = oauth2ClientSecretScope ?? bindingScope;	755	const clientSecretSecretScope = oauth2ClientSecretScope ?? sourceScope;
739		756
740	for (const binding of headerBindings) {	757	for (const binding of headerBindings) {
741	const bindingExit = await doSetBinding({	758	const bindingExit = await doSetBinding({
@@ -783,13 +800,36 @@ export default function AddOpenApiSource(props: { · 41 unmodified lines
783	}	800	}
784	}	801	}
785		802
		803	for (const binding of specFetchBindings) {
		804	const bindingExit = await doSetBinding({
		805	params: { scopeId },
		806	payload: OpenApiSourceBindingInput.make({
		807	sourceId,
		808	sourceScope,
		809	scope: binding.scope,
		810	slot: binding.slot,
		811	value: {
		812	kind: "secret",
		813	secretId: SecretId.make(binding.secretId),
		814	secretScopeId: binding.secretScope,
		815	},
		816	}),
		817	reactivityKeys: bindingWriteKeys,
		818	});
		819	if (Exit.isFailure(bindingExit)) {
		820	setAddError(errorMessageFromExit(bindingExit, "Failed to add source"));
		821	setAdding(false);
		822	return;
		823	}
		824	}
		825
786	if (configuredOAuth2 && oauth2ClientIdSecretId) {	826	if (configuredOAuth2 && oauth2ClientIdSecretId) {
787	const bindingExit = await doSetBinding({	827	const bindingExit = await doSetBinding({
788	params: { scopeId },	828	params: { scopeId },
789	payload: OpenApiSourceBindingInput.make({	829	payload: OpenApiSourceBindingInput.make({
790	sourceId,	830	sourceId,
791	sourceScope,	831	sourceScope,
792	scope: bindingScope,	832	scope: sourceScope,
793	slot: configuredOAuth2.clientIdSlot,	833	slot: configuredOAuth2.clientIdSlot,
794	value: {	834	value: {
795	kind: "secret",	835	kind: "secret",
@@ -812,7 +852,7 @@ export default function AddOpenApiSource(props: { · 16 unmodified lines
812	payload: OpenApiSourceBindingInput.make({	852	payload: OpenApiSourceBindingInput.make({
813	sourceId,	853	sourceId,
814	sourceScope,	854	sourceScope,
815	scope: bindingScope,	855	scope: sourceScope,
816	slot: configuredOAuth2.clientSecretSlot,	856	slot: configuredOAuth2.clientSecretSlot,
817	value: {	857	value: {
818	kind: "secret",	858	kind: "secret",
@@ -908,7 +948,10 @@ export default function AddOpenApiSource(props: { · 89 unmodified lines
908	onChange={setSpecFetchCredentials}	948	onChange={setSpecFetchCredentials}
909	existingSecrets={secretList}	949	existingSecrets={secretList}
910	sourceName={identity.name}	950	sourceName={identity.name}
911	targetScope={credentialTargetScope}	951	targetScope={sourceScope}
		952	credentialScopeOptions={sourceCredentialScopeOptions}
		953	bindingScopeOptions={sourceCredentialScopeOptions}
		954	restrictSecretsToTargetScope
912	labels={{	955	labels={{
913	headers: "Spec fetch headers",	956	headers: "Spec fetch headers",
914	queryParams: "Spec fetch query parameters",	957	queryParams: "Spec fetch query parameters",
@@ -1044,9 +1087,9 @@ export default function AddOpenApiSource(props: { · 129 unmodified lines
1044	onHeadersChange={handleHeadersChange}	1087	onHeadersChange={handleHeadersChange}
1045	existingSecrets={secretList}	1088	existingSecrets={secretList}
1046	sourceName={identity.name}	1089	sourceName={identity.name}
1047	targetScope={credentialTargetScope}	1090	targetScope={sourceScope}
1048	credentialScopeOptions={initialCredentialScopeOptions}	1091	credentialScopeOptions={sourceCredentialScopeOptions}
1049	bindingScopeOptions={bindingScopeOptions}	1092	bindingScopeOptions={sourceCredentialScopeOptions}
1050	restrictSecretsToTargetScope	1093	restrictSecretsToTargetScope
1051	emptyLabel="No credentials yet. Add the header value this method should use."	1094	emptyLabel="No credentials yet. Add the header value this method should use."
1052	/>	1095	/>
@@ -1058,9 +1101,9 @@ export default function AddOpenApiSource(props: { · 5 unmodified lines
1058	onChange={setRuntimeCredentials}	1101	onChange={setRuntimeCredentials}
1059	existingSecrets={secretList}	1102	existingSecrets={secretList}
1060	sourceName={identity.name}	1103	sourceName={identity.name}
1061	targetScope={credentialTargetScope}	1104	targetScope={sourceScope}
1062	credentialScopeOptions={initialCredentialScopeOptions}	1105	credentialScopeOptions={sourceCredentialScopeOptions}
1063	bindingScopeOptions={bindingScopeOptions}	1106	bindingScopeOptions={sourceCredentialScopeOptions}
1064	restrictSecretsToTargetScope	1107	restrictSecretsToTargetScope
1065	sections={{ headers: false, queryParams: true }}	1108	sections={{ headers: false, queryParams: true }}
1066	labels={{ queryParams: "Runtime query parameters" }}	1109	labels={{ queryParams: "Runtime query parameters" }}
@@ -1096,22 +1139,17 @@ export default function AddOpenApiSource(props: { · 29 unmodified lines
1096	value={oauth2ClientIdSecretId}	1139	value={oauth2ClientIdSecretId}
1097	onSelect={(id: string, secretScopeId?: ScopeId) => {	1140	onSelect={(id: string, secretScopeId?: ScopeId) => {
1098	setOauth2ClientIdSecretId(id);	1141	setOauth2ClientIdSecretId(id);
1099	setOauth2ClientIdScope(secretScopeId ?? credentialTargetScope);	1142	setOauth2ClientIdScope(secretScopeId ?? sourceScope);
1100	setOauth2AuthState(null);	1143	setOauth2AuthState(null);
1101	}}	1144	}}
1102	secrets={initialCredentialSecrets}	1145	secrets={sourceCredentialSecrets}
1103	sourceName={identity.name}	1146	sourceName={identity.name}
1104	secretLabel="Client ID"	1147	secretLabel="Client ID"
1105	targetScope={oauth2ClientIdScope ?? credentialTargetScope}	1148	targetScope={oauth2ClientIdScope ?? sourceScope}
1106	credentialScopeOptions={initialCredentialScopeOptions}	1149	credentialScopeOptions={sourceCredentialScopeOptions}
1107	onCreatedScope={setOauth2ClientIdScope}	1150	onCreatedScope={setOauth2ClientIdScope}
1108	/>	1151	/>
1109	</div>	1152	</div>
1110	<CredentialScopeDropdown
1111	value={credentialTargetScope}
1112	options={bindingScopeOptions}
1113	onChange={setInitialCredentialScope}
1114	/>
1115	</div>	1153	</div>
1116	</div>	1154	</div>
1117	<div className="space-y-1.5">	1155	<div className="space-y-1.5">
@@ -1133,22 +1171,17 @@ export default function AddOpenApiSource(props: { · 15 unmodified lines
1133	value={oauth2ClientSecretSecretId}	1171	value={oauth2ClientSecretSecretId}
1134	onSelect={(id: string, secretScopeId?: ScopeId) => {	1172	onSelect={(id: string, secretScopeId?: ScopeId) => {
1135	setOauth2ClientSecretSecretId(id);	1173	setOauth2ClientSecretSecretId(id);
1136	setOauth2ClientSecretScope(secretScopeId ?? credentialTargetScope);	1174	setOauth2ClientSecretScope(secretScopeId ?? sourceScope);
1137	setOauth2AuthState(null);	1175	setOauth2AuthState(null);
1138	}}	1176	}}
1139	secrets={initialCredentialSecrets}	1177	secrets={sourceCredentialSecrets}
1140	sourceName={identity.name}	1178	sourceName={identity.name}
1141	secretLabel="Client Secret"	1179	secretLabel="Client Secret"
1142	targetScope={oauth2ClientSecretScope ?? credentialTargetScope}	1180	targetScope={oauth2ClientSecretScope ?? sourceScope}
1143	credentialScopeOptions={initialCredentialScopeOptions}	1181	credentialScopeOptions={sourceCredentialScopeOptions}
1144	onCreatedScope={setOauth2ClientSecretScope}	1182	onCreatedScope={setOauth2ClientSecretScope}
1145	/>	1183	/>
1146	</div>	1184	</div>
1147	<CredentialScopeDropdown
1148	value={credentialTargetScope}
1149	options={bindingScopeOptions}
1150	onChange={setInitialCredentialScope}
1151	/>
1152	</div>	1185	</div>
1153	</div>	1186	</div>
1154	<div className="space-y-1.5">	1187	<div className="space-y-1.5">

packages/plugins/openapi/src/react/atoms.ts+1−1

@@ -43,7 +43,7 @@ export const addOpenApiSpecOptimistic = Atom.family((scopeId: ScopeId) => · 42 unmodified lines
43	const id = arg.payload.namespace ?? `pending-${Math.random().toString(36).slice(2)}`;	43	const id = arg.payload.namespace ?? `pending-${Math.random().toString(36).slice(2)}`;
44	const source = {	44	const source = {
45	id,	45	id,
46	scopeId: arg.payload.targetScope,	46	scopeId,
47	kind: "openapi",	47	kind: "openapi",
48	pluginId: "openapi",	48	pluginId: "openapi",
49	name: arg.payload.name ?? id,	49	name: arg.payload.name ?? id,

packages/plugins/openapi/src/sdk/plugin.test.ts+66−44

     ...options,
   });
-const testApiSpec = () => testApiSourceConfig().spec;
+const testApiSpec = () => {
+  const spec = testApiSourceConfig().spec;
+  return spec.kind === "blob" ? spec.value : spec.url;
+};
 // ---------------------------------------------------------------------------
 // Implement handlers
       Effect.sync(() => {
         state.requests++;
         state.lastToken = request.headers["x-spec-token"] ?? null;
+        if (state.requests === 1) {
+          return null;
+        }
         if (state.lastToken !== "org-token") {
           return HttpServerResponse.jsonUnsafe({ error: "missing token" }, { status: 401 });
         }
       expect(schema).not.toBeNull();
       expect(schema!.inputTypeScript).toContain("scope: string");
-      expect(schema!.inputTypeScript).toContain("spec: string");
+      expect(schema!.inputTypeScript).toContain('kind: "url"');
       expect(
         (schema!.inputSchema as { properties?: Record<string, unknown> }).properties,
-      ).toHaveProperty("credentialTargetScope");
+      ).not.toHaveProperty("credentialTargetScope");
       expect(schema!.inputTypeScript).not.toBe("Record<string, unknown>");
     }),
   );
       const input = testApiSourceConfig({
         scope: String(orgScope),
         namespace: "org_direct_user_credential",
-        queryParams: { token: { secretId: "user-query-token" } },
+        queryParams: { token: { kind: "secret" } },
-        credentialTargetScope: String(userScope),
       });
       yield* executor.openapi.addSpec(input);
         "org_direct_user_credential",
         String(orgScope),
       );
-      expect(bindings).toHaveLength(1);
+      expect(bindings).toEqual([]);
-      expect(bindings[0]).toMatchObject({
-        scopeId: userScope,
-        slot: "query_param:token",
-        value: {
-          kind: "secret",
-          secretId: SecretId.make("user-query-token"),
-        },
-      });
     }),
   );
         testApiSourceConfig({
           namespace: "stale_binding",
           baseUrl: "",
-          credentialTargetScope: TEST_SCOPE,
           headers: {
-            "X-Old": { secretId: "old-token" },
+            "X-Old": { kind: "secret" },
           },
         }),
       );
+      yield* executor.openapi.setSourceBinding(
+        OpenApiSourceBindingInput.make({
+          sourceId: "stale_binding",
+          sourceScope: ScopeId.make(TEST_SCOPE),
+          scope: ScopeId.make(TEST_SCOPE),
+          slot: "header:x-old",
+          value: { kind: "secret", secretId: SecretId.make("old-token") },
+        }),
+      );
       yield* executor.openapi.updateSource("stale_binding", TEST_SCOPE, {
         headers: {},
         yield* addOpenApiTestSource(executor, server, {
           scope: TEST_SCOPE,
           namespace: "authed",
-          credentialTargetScope: TEST_SCOPE,
           headers: {
-            Authorization: { secretId: "test-api-token", prefix: "Bearer " },
+            Authorization: { kind: "secret", prefix: "Bearer " },
             "X-Static": "hello",
           },
         });
+        yield* executor.openapi.setSourceBinding(
+          OpenApiSourceBindingInput.make({
+            sourceId: "authed",
+            sourceScope: ScopeId.make(TEST_SCOPE),
+            scope: ScopeId.make(TEST_SCOPE),
+            slot: "header:authorization",
+            value: { kind: "secret", secretId: SecretId.make("test-api-token") },
+          }),
+        );
         const result = unwrapInvocation(
           yield* executor.tools.invoke("authed.items.echoHeaders", {}, autoApprove),
     ),
   );
-  it.effect("addSpec without credentialTargetScope defaults to the source's scope", () =>
+  it.effect("addSpec declares secret-backed header shape without a credential value", () =>
-    // Regression: config-sync calls addSpec without ever setting
-    // credentialTargetScope. Before the fix, any source with a
-    // header secret in executor.jsonc errored with
-    // "credentialTargetScope is required when adding direct OpenAPI
-    // credentials" the moment the daemon started.
     Effect.gen(function* () {
       const clientLayer = FetchHttpClient.layer;
           baseUrl: "",
           headers: {
             Authorization: {
-              secretId: "config-sync-token",
+              kind: "secret",
               prefix: "Bearer ",
             },
           },
         "default_target_scope",
         TEST_SCOPE,
       );
-      expect(bindings).toHaveLength(1);
+      expect(bindings).toEqual([]);
-      expect(bindings[0]).toMatchObject({
-        scopeId: ScopeId.make(TEST_SCOPE),
-        slot: "header:authorization",
-        value: {
-          kind: "secret",
-          secretId: SecretId.make("config-sync-token"),
-        },
-      });
     }),
   );
         testApiSourceConfig({
           scope: String(USER_SCOPE),
           namespace: "shared",
+          baseUrl: null,
           name: "User Source",
         }),
       );
         testApiSourceConfig({
           scope: String(USER_SCOPE),
           namespace: "shared",
+          baseUrl: null,
           name: "User Source",
         }),
       );
         testApiSourceConfig({
           scope: String(USER_SCOPE),
           namespace: "shared",
-          baseUrl: "",
+          baseUrl: null,
           name: "User Source",
         }),
       );
         testApiSourceConfig({
           scope: String(USER_SCOPE),
           namespace: "shared",
+          baseUrl: null,
           name: "User Source",
         }),
       );
         );
         yield* executor.openapi.addSpec({
-          spec: server.specJson,
+          spec: { kind: "blob", value: server.specJson },
           scope: String(ORG_SCOPE),
+          name: "Shadow Auth",
           namespace: "shadow_auth",
           baseUrl: "https://org.example.com",
-          credentialTargetScope: String(ORG_SCOPE),
           headers: {
-            Authorization: { secretId: "org-api-token", prefix: "Bearer " },
+            Authorization: { kind: "secret", prefix: "Bearer " },
           },
         });
         const addResult = yield* executor.openapi
           .addSpec({
-            spec: server.specJson,
+            spec: { kind: "blob", value: server.specJson },
             scope: String(USER_SCOPE),
             namespace: "shadow_auth",
             baseUrl: server.baseUrl,
           );
           yield* executor.openapi.addSpec({
-            spec: server.specUrl,
+            spec: { kind: "url", url: server.specUrl },
             scope: String(ORG_SCOPE),
+            name: "Shared Spec Fetch",
             namespace: "shared_spec_fetch",
-            credentialTargetScope: String(ORG_SCOPE),
+            baseUrl: "https://api.example.test",
             specFetchCredentials: {
               headers: {
-                "X-Spec-Token": { secretId: "org-spec-token" },
+                "X-Spec-Token": { kind: "secret" },
               },
             },
           });
+          yield* executor.openapi.setSourceBinding(
+            OpenApiSourceBindingInput.make({
+              sourceId: "shared_spec_fetch",
+              sourceScope: ORG_SCOPE,
+              scope: ORG_SCOPE,
+              slot: "spec_fetch_header:x-spec-token",
+              value: { kind: "secret", secretId: SecretId.make("org-spec-token") },
+            }),
+          );
           yield* executor.openapi.addSpec(
             testApiSourceConfig({
               scope: String(USER_SCOPE),
               namespace: "shared_spec_fetch",
+              baseUrl: null,
               name: "User Shadow",
             }),
           );
         testApiSourceConfig({
           namespace: "with_secret",
           baseUrl: "http://example.com",
-          credentialTargetScope: TEST_SCOPE,
+          queryParams: { token: { kind: "secret" } },
-          queryParams: { token: { secretId: "api-key" } },
+        }),
+      );
+      yield* executor.openapi.setSourceBinding(
+        OpenApiSourceBindingInput.make({
+          sourceId: "with_secret",
+          sourceScope: ScopeId.make(TEST_SCOPE),
+          scope: ScopeId.make(TEST_SCOPE),
+          slot: "query_param:token",
+          value: { kind: "secret", secretId: SecretId.make("api-key") },
         }),
       );

packages/plugins/openapi/src/sdk/plugin.ts+76−177

 import {
   ScopeId,
-  SecretId,
   SourceDetectionResult,
   StorageError,
   ToolResult,
 import { extract } from "./extract";
 import { compileToolDefinitions, type ToolDefinition } from "./definitions";
 import { annotationsForOperation, invokeWithLayer } from "./invoke";
-import { resolveBaseUrl } from "./openapi-utils";
 import { previewSpec, SpecPreview } from "./preview";
 import {
   makeDefaultOpenapiStore,
 } from "./store";
 import {
   HeaderValue as HeaderValueSchema,
-  ConfiguredHeaderValue as ConfiguredHeaderValueSchema,
   ConfiguredHeaderBinding,
   OAuth2SourceConfig,
-  OpenApiCredentialInput as OpenApiCredentialInputSchema,
   OpenApiSourceBindingInput,
   OpenApiSourceBindingRef,
-  type OpenApiCredentialInput as OpenApiCredentialInputValue,
   type OpenApiSourceBindingValue,
   OperationBinding,
   type ConfiguredHeaderValue as ConfiguredHeaderValueValue,
 export type HeaderValue = HeaderValueValue;
 export type ConfiguredHeaderValue = ConfiguredHeaderValueValue;
-export type OpenApiHeaderInput = HeaderValue | ConfiguredHeaderValue;
-export type OpenApiCredentialInput = OpenApiCredentialInputValue;
 export type OpenApiOAuthInput = OAuth2SourceConfig;
+export type OpenApiSpecInput = typeof OpenApiSpecInputSchema.Type;
+export type OpenApiSecretShapeInput = typeof OpenApiSecretShapeInputSchema.Type;
+export type OpenApiConfiguredValueInput =
+  | string
+  | OpenApiSecretShapeInput
+  | ConfiguredHeaderValueValue;
 export interface OpenApiSpecFetchCredentialsInput {
+  readonly headers?: Record<string, OpenApiConfiguredValueInput>;
+  readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
+}
+export interface OpenApiPreviewSpecFetchCredentialsInput {
   readonly headers?: Record<string, HeaderValue>;
   readonly queryParams?: Record<string, HeaderValue>;
 }
 export interface OpenApiPreviewInput {
   readonly spec: string;
-  readonly specFetchCredentials?: OpenApiSpecFetchCredentialsInput;
+  readonly specFetchCredentials?: OpenApiPreviewSpecFetchCredentialsInput;
 }
 export interface OpenApiSpecConfig {
-  readonly spec: string;
+  readonly spec: OpenApiSpecInput;
   readonly specFetchCredentials?: OpenApiSpecFetchCredentialsInput;
   /**
    * Executor scope id that owns this source row. Must be one of the
    * every inner (per-user) scope via fall-through reads.
    */
   readonly scope: string;
-  readonly name?: string;
+  readonly name: string;
-  readonly baseUrl?: string;
+  readonly baseUrl: string;
-  readonly namespace?: string;
+  readonly namespace: string;
-  readonly headers?: Record<string, OpenApiCredentialInput>;
+  readonly headers?: Record<string, OpenApiConfiguredValueInput>;
-  readonly queryParams?: Record<string, OpenApiCredentialInput>;
+  readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
   readonly oauth2?: OpenApiOAuthInput;
-  readonly credentialTargetScope?: string;
 }
 export interface OpenApiUpdateSourceInput {
   readonly name?: string;
   readonly baseUrl?: string;
-  readonly headers?: Record<string, OpenApiCredentialInput>;
+  readonly headers?: Record<string, OpenApiConfiguredValueInput>;
-  readonly queryParams?: Record<string, OpenApiCredentialInput>;
+  readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
-  readonly credentialTargetScope?: string;
   /** Refresh the source's stored OAuth2 metadata after a successful
    *  re-authenticate. */
   readonly oauth2?: OpenApiOAuthInput;
   ),
 });
-const OpenApiHeaderInputSchema = Schema.Union([HeaderValueSchema, ConfiguredHeaderValueSchema]);
+const OpenApiSpecInputSchema = Schema.Union([
+  Schema.Struct({ kind: Schema.Literal("url"), url: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("blob"), value: Schema.String }),
+]);
+const OpenApiSecretShapeInputSchema = Schema.Struct({
+  kind: Schema.Literal("secret"),
+  prefix: Schema.optional(Schema.String),
+});
+const OpenApiConfiguredValueInputSchema = Schema.Union([
+  Schema.String,
+  OpenApiSecretShapeInputSchema,
+]);
 const OpenApiOAuthInputSchema = OAuth2SourceConfig;
 const AddSourceInputSchema = Schema.Struct({
   scope: Schema.String,
-  spec: Schema.String,
+  spec: OpenApiSpecInputSchema,
-  name: Schema.optional(Schema.String),
+  name: Schema.String,
-  baseUrl: Schema.optional(Schema.String),
+  baseUrl: Schema.String,
-  namespace: Schema.optional(Schema.String),
+  namespace: Schema.String,
-  headers: Schema.optional(Schema.Record(Schema.String, OpenApiHeaderInputSchema)),
+  headers: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValueInputSchema)),
-  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiCredentialInputSchema)),
+  queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValueInputSchema)),
   oauth2: Schema.optional(OpenApiOAuthInputSchema),
-  credentialTargetScope: Schema.optional(Schema.String),
   specFetchCredentials: Schema.optional(
     Schema.Struct({
-      headers: Schema.optional(Schema.Record(Schema.String, HeaderValueSchema)),
+      headers: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValueInputSchema)),
-      queryParams: Schema.optional(Schema.Record(Schema.String, HeaderValueSchema)),
+      queryParams: Schema.optional(Schema.Record(Schema.String, OpenApiConfiguredValueInputSchema)),
     }),
   ),
 });
   `spec_fetch_query_param:${slotPart(name)}`;
 const canonicalizeHeaders = (
-  headers: Record<string, OpenApiCredentialInput> | undefined,
+  headers: Record<string, OpenApiConfiguredValueInput> | undefined,
 ): {
   readonly headers: Record<string, ConfiguredHeaderValue>;
-  readonly bindings: ReadonlyArray<{
-    readonly slot: string;
-    readonly value: OpenApiSourceBindingValue;
-    readonly targetScope?: string;
-  }>;
 } => {
   const nextHeaders: Record<string, ConfiguredHeaderValue> = {};
-  const bindings: Array<{
-    slot: string;
-    value: OpenApiSourceBindingValue;
-    targetScope?: string;
-  }> = [];
   for (const [name, value] of Object.entries(headers ?? {})) {
     if (typeof value === "string") {
       nextHeaders[name] = value;
       continue;
     }
-    if ("kind" in value) {
+    if (value.kind === "binding") {
       nextHeaders[name] = value;
       continue;
     }
       slot,
       prefix: value.prefix,
     });
-    bindings.push({
-      slot,
-      targetScope: "targetScope" in value ? value.targetScope : undefined,
-      value: {
-        kind: "secret",
-        secretId: SecretId.make(value.secretId),
-        ...("secretScopeId" in value && value.secretScopeId
-          ? { secretScopeId: value.secretScopeId }
-          : {}),
-      },
-    });
   }
-  return { headers: nextHeaders, bindings };
+  return { headers: nextHeaders };
 };
 const canonicalizeCredentialMap = (
-  values: Record<string, OpenApiCredentialInput> | undefined,
+  values: Record<string, OpenApiConfiguredValueInput> | undefined,
   slotForName: (name: string) => string,
 ): {
   readonly values: Record<string, ConfiguredHeaderValue>;
-  readonly bindings: ReadonlyArray<{
-    readonly slot: string;
-    readonly value: OpenApiSourceBindingValue;
-    readonly targetScope?: string;
-  }>;
 } => {
   const nextValues: Record<string, ConfiguredHeaderValue> = {};
-  const bindings: Array<{
-    slot: string;
-    value: OpenApiSourceBindingValue;
-    targetScope?: string;
-  }> = [];
   for (const [name, value] of Object.entries(values ?? {})) {
     if (typeof value === "string") {
       nextValues[name] = value;
       continue;
     }
-    if ("kind" in value) {
+    if (value.kind === "binding") {
       nextValues[name] = value;
       continue;
     }
       slot,
       prefix: value.prefix,
     });
-    bindings.push({
-      slot,
-      targetScope: "targetScope" in value ? value.targetScope : undefined,
-      value: {
-        kind: "secret",
-        secretId: SecretId.make(value.secretId),
-        ...("secretScopeId" in value && value.secretScopeId
-          ? { secretScopeId: value.secretScopeId }
-          : {}),
-      },
-    });
   }
-  return { values: nextValues, bindings };
+  return { values: nextValues };
 };
 const canonicalizeSpecFetchCredentials = (
   credentials:
     | {
-        readonly headers?: Record<string, OpenApiCredentialInput>;
+        readonly headers?: Record<string, OpenApiConfiguredValueInput>;
-        readonly queryParams?: Record<string, OpenApiCredentialInput>;
+        readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
       }
     | undefined,
 ): {
   readonly credentials?: SourceConfig["specFetchCredentials"];
-  readonly bindings: ReadonlyArray<{
-    readonly slot: string;
-    readonly value: OpenApiSourceBindingValue;
-    readonly targetScope?: string;
-  }>;
 } => {
   const headers = canonicalizeCredentialMap(credentials?.headers, specFetchHeaderSlotFromName);
   const queryParams = canonicalizeCredentialMap(
         };
   return {
     credentials: nextCredentials,
-    bindings: [...headers.bindings, ...queryParams.bindings],
   };
 };
     }
   });
-const targetScopeForBinding = (
-  fallbackTargetScope: string | undefined,
-  binding: { readonly slot: string; readonly targetScope?: string },
-): Effect.Effect<string, OpenApiOAuthError> => {
-  const targetScope = binding.targetScope ?? fallbackTargetScope;
-  if (targetScope) return Effect.succeed(targetScope);
-  return Effect.fail(
-    new OpenApiOAuthError({
-      message: "credentialTargetScope is required when adding direct OpenAPI credentials",
-    }),
-  );
-};
 const findOuterSource = (
   ctx: PluginCtx<OpenapiStore>,
   namespace: string,
 const resolveSpecFetchInputCredentials = (
   ctx: PluginCtx<OpenapiStore>,
-  credentials: OpenApiSpecFetchCredentialsInput | undefined,
+  credentials: OpenApiPreviewSpecFetchCredentialsInput | undefined,
 ) =>
   Effect.gen(function* () {
     if (!credentials) return undefined;
 ): OpenApiSourceConfig => {
   const configHeaders: Record<string, HeaderValueValue> = {};
   for (const [name, value] of Object.entries(config.headers ?? {})) {
-    if (typeof value === "string" || !("kind" in value)) {
+    if (typeof value === "string") {
       configHeaders[name] = value;
     }
   }
   return {
     kind: "openapi",
-    spec: config.spec,
+    spec: specInputToConfigString(config.spec),
     baseUrl: config.baseUrl,
     namespace,
     headers: headersToConfigValues(
   };
 };
-const isHttpUrl = (s: string): boolean => s.startsWith("http://") || s.startsWith("https://");
+const specInputToConfigString = (spec: OpenApiSpecInput): string =>
+  spec.kind === "url" ? spec.url : spec.value;
 export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => {
   type RebuildInput = {
     readonly specText: string;
     readonly scope: string;
     readonly sourceUrl?: string;
-    readonly name?: string;
+    readonly name: string;
-    readonly baseUrl?: string;
+    readonly baseUrl: string | undefined;
-    readonly namespace?: string;
+    readonly namespace: string;
-    readonly headers?: Record<string, OpenApiHeaderInput>;
+    readonly headers?: Record<string, OpenApiConfiguredValueInput>;
-    readonly queryParams?: Record<string, OpenApiCredentialInput>;
+    readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
     readonly specFetchCredentials?: {
-      readonly headers?: Record<string, OpenApiCredentialInput>;
+      readonly headers?: Record<string, OpenApiConfiguredValueInput>;
-      readonly queryParams?: Record<string, OpenApiCredentialInput>;
+      readonly queryParams?: Record<string, OpenApiConfiguredValueInput>;
     };
     readonly oauth2?: OpenApiOAuthInput;
-    readonly credentialTargetScope?: string;
   };
   // ctx comes from the plugin runtime — the same instance is passed to
       const doc = yield* parse(input.specText);
       const result = yield* extract(doc);
-      const namespace =
+      const namespace = input.namespace;
-        input.namespace ??
-        Option.getOrElse(result.title, () => "api")
-          .toLowerCase()
-          .replace(/[^a-z0-9]+/g, "_");
       const outerSource = yield* findOuterSource(ctx, namespace, input.scope);
       if (outerSource && input.baseUrl !== undefined && input.baseUrl.trim() !== "") {
         return yield* new OpenApiOAuthError({
         }
       }
-      const baseUrl = outerSource ? undefined : (input.baseUrl ?? resolveBaseUrl(result.servers));
+      const baseUrl = outerSource ? undefined : input.baseUrl;
       const canonicalHeaders = canonicalizeHeaders(input.headers);
       const canonicalQueryParams = canonicalizeCredentialMap(
         input.queryParams,
         input.specFetchCredentials,
       );
       const canonicalOAuth2 = canonicalizeOAuth2(input.oauth2);
-      const directBindings = [
-        ...canonicalHeaders.bindings,
-        ...canonicalQueryParams.bindings,
-        ...canonicalSpecFetchCredentials.bindings,
-        ...canonicalOAuth2.bindings,
-      ];
-      for (const binding of directBindings) {
-        const bindingTargetScope = yield* targetScopeForBinding(
-          input.credentialTargetScope,
-          binding,
-        );
-        yield* validateOpenApiBindingTarget(ctx, {
-          sourceId: namespace,
-          sourceScope: input.scope,
-          targetScope: bindingTargetScope,
-        });
-      }
       const definitions = compileToolDefinitions(result.operations);
-      const sourceName = input.name ?? Option.getOrElse(result.title, () => namespace);
+      const sourceName = input.name;
       const sourceConfig: SourceConfig = {
         spec: input.specText,
             })),
           });
-          if (directBindings.length > 0) {
-            for (const binding of directBindings) {
-              const bindingTargetScope = yield* targetScopeForBinding(
-                input.credentialTargetScope,
-                binding,
-              );
-              yield* ctx.credentialBindings.set({
-                targetScope: ScopeId.make(bindingTargetScope),
-                pluginId: OPENAPI_PLUGIN_ID,
-                sourceId: namespace,
-                sourceScope: ScopeId.make(input.scope),
-                slotKey: binding.slot,
-                value: binding.value,
-              });
-            }
-          }
           if (Object.keys(hoistedDefs).length > 0) {
             yield* ctx.core.definitions.register({
               sourceId: namespace,
         scope,
         sourceUrl,
         name: existing.name,
-        baseUrl: resolvedConfig.baseUrl,
+        baseUrl: existing.config.baseUrl,
         namespace: existing.namespace,
         headers: existing.config.headers,
         queryParams: existing.config.queryParams,
         specFetchCredentials: existing.config.specFetchCredentials,
         oauth2: existing.config.oauth2,
-        credentialTargetScope: scope,
       });
     });
           // Resolve URL → text and parse BEFORE opening a transaction.
           // Holding `BEGIN` on the pool=1 Postgres connection across a
           // network fetch is the Hyperdrive deadlock path in production.
-          const credentials = yield* resolveSpecFetchInputCredentials(
+          const specText =
-            ctx,
+            config.spec.kind === "url"
-            config.specFetchCredentials,
+              ? yield* resolveSpecText(config.spec.url).pipe(Effect.provide(httpClientLayer))
-          );
+              : config.spec.value;
-          const specText = yield* resolveSpecText(config.spec, credentials).pipe(
-            Effect.provide(httpClientLayer),
-          );
           return yield* rebuildSource(ctx, {
             specText,
             scope: config.scope,
-            sourceUrl: isHttpUrl(config.spec) ? config.spec : undefined,
+            sourceUrl: config.spec.kind === "url" ? config.spec.url : undefined,
             name: config.name,
             baseUrl: config.baseUrl,
             namespace: config.namespace,
             queryParams: config.queryParams,
             specFetchCredentials: config.specFetchCredentials,
             oauth2: config.oauth2,
-            // Default to the source's own scope. refreshSource and editSource
-            // do the same; without this, config-sync's addSpec — which never
-            // passes the field — fails with "credentialTargetScope is
-            // required" the moment the jsonc declares any header secret.
-            credentialTargetScope: config.credentialTargetScope ?? config.scope,
           });
         });
               input.queryParams !== undefined
                 ? canonicalizeCredentialMap(input.queryParams, queryParamSlotFromName)
                 : null;
-            const directBindings = [
-              ...(canonicalHeaders?.bindings ?? []),
-              ...(canonicalQueryParams?.bindings ?? []),
-              ...(canonicalOAuth2?.bindings ?? []),
-            ];
             const affectedPrefixes = [
               ...(input.headers !== undefined ? ["header:"] : []),
               ...(input.queryParams !== undefined ? ["query_param:"] : []),
               ...(input.oauth2 !== undefined ? ["oauth2:"] : []),
             ];
-            const targetScope = input.credentialTargetScope ?? scope;
+            const targetScope = scope;
             if (input.baseUrl !== undefined && input.baseUrl.trim() !== "") {
               const outerSource = yield* findOuterSource(ctx, namespace, scope);
               if (outerSource) {
                 });
               }
             }
-            if (affectedPrefixes.length > 0 || directBindings.length > 0) {
+            if (affectedPrefixes.length > 0) {
               yield* validateOpenApiBindingTarget(ctx, {
                 sourceId: namespace,
                 sourceScope: scope,
                   queryParams: canonicalQueryParams?.values,
                   oauth2: canonicalOAuth2?.oauth2,
                 });
-                if (affectedPrefixes.length > 0 || directBindings.length > 0) {
+                if (affectedPrefixes.length > 0) {
                   yield* ctx.credentialBindings.replaceForSource({
                     targetScope: ScopeId.make(targetScope),
                     pluginId: OPENAPI_PLUGIN_ID,
                     sourceId: namespace,
                     sourceScope: ScopeId.make(scope),
                     slotPrefixes: affectedPrefixes,
-                    bindings: directBindings.map((binding) => ({
+                    bindings: [],
-                      slotKey: binding.slot,
-                      value: binding.value,
-                    })),
                   });
                 }
               }),

packages/plugins/openapi/src/sdk/real-specs.test.ts+2−1

     );
     yield* executor.openapi.addSpec({
-      spec: specText,
+      spec: { kind: "blob", value: specText },
       scope: TEST_SCOPE,
+      name: namespace,
       namespace,
       baseUrl: "",
     });

packages/plugins/openapi/src/sdk/source-contracts.ts+6−0

 export const queryParamBindingSlot = (name: string): string =>
   `query_param:${slugifySlotPart(name)}`;
+export const specFetchHeaderBindingSlot = (headerName: string): string =>
+  `spec_fetch_header:${slugifySlotPart(headerName)}`;
+export const specFetchQueryParamBindingSlot = (name: string): string =>
+  `spec_fetch_query_param:${slugifySlotPart(name)}`;
 export const oauth2ClientIdSlot = (securitySchemeName: string): string =>
   `oauth2:${slugifySlotPart(securitySchemeName)}:client-id`;

packages/plugins/openapi/src/testing/index.ts+52−26

   OpenApi,
 } from "effect/unstable/httpapi";
 import { OAuthTestServer, serveTestHttpServerLayer } from "@executor-js/sdk/testing";
-import { isToolResult, type ScopeId } from "@executor-js/sdk/core";
+import { isToolResult } from "@executor-js/sdk/core";
 import type { OpenApiPluginExtension, OpenApiSpecConfig } from "../sdk/plugin";
 export class OpenApiTestServerAddressError extends Data.TaggedError(
   readonly clearRequests: Effect.Effect<void>;
 }
-export type OpenApiTestSourceOptions = Omit<OpenApiSpecConfig, "spec" | "baseUrl"> & {
+export type OpenApiTestSourceOptions = Omit<
+  OpenApiSpecConfig,
+  "spec" | "baseUrl" | "name" | "namespace"
+> & {
   readonly baseUrl?: string | null;
+  readonly name?: string;
+  readonly namespace?: string;
 };
-export type OpenApiHttpApiTestSourceOptions = Omit<OpenApiSpecConfig, "spec"> & {
+export type OpenApiHttpApiTestSourceOptions = Omit<
+  OpenApiSpecConfig,
+  "spec" | "name" | "namespace" | "baseUrl"
+> & {
+  readonly name?: string;
+  readonly namespace?: string;
+  readonly baseUrl?: string | null;
   readonly specBaseUrl?: string;
   readonly transformSpec?: (spec: Record<string, unknown>) => Record<string, unknown>;
 };
+type OpenApiHttpApiAddSpecCredentialInput =
+  | string
+  | {
+      readonly kind: "secret";
+      readonly prefix?: string;
+    };
+type OpenApiHttpApiAddSpecCredentialsInput = {
+  readonly headers?: Record<string, OpenApiHttpApiAddSpecCredentialInput>;
+  readonly queryParams?: Record<string, OpenApiHttpApiAddSpecCredentialInput>;
+};
 export type OpenApiHttpApiTestAddSpecPayloadOptions = Omit<
   OpenApiHttpApiTestSourceOptions,
-  "scope" | "credentialTargetScope"
+  "scope" | "headers" | "queryParams" | "specFetchCredentials"
-> & {
+> &
-  readonly targetScope: ScopeId;
+  OpenApiHttpApiAddSpecCredentialsInput & {
-  readonly credentialTargetScope?: ScopeId;
+    readonly specFetchCredentials?: OpenApiHttpApiAddSpecCredentialsInput;
-};
+  };
 export type OpenApiTestSourceExecutor = {
   readonly openapi: Pick<OpenApiPluginExtension, "addSpec">;
   const { baseUrl, ...rest } = options;
   return {
     ...rest,
-    spec: server.specJson,
+    spec: { kind: "blob", value: server.specJson },
+    name: rest.name ?? "Test API",
+    namespace: rest.namespace ?? "test_api",
     ...(baseUrl === null ? {} : { baseUrl: baseUrl ?? server.baseUrl }),
-  };
+  } as OpenApiSpecConfig;
 };
 export const addOpenApiTestSource = (
   api: HttpApi.Any,
   options: OpenApiHttpApiTestSourceOptions,
 ): OpenApiSpecConfig => {
-  const { specBaseUrl, transformSpec, ...config } = options;
+  const { baseUrl, specBaseUrl, transformSpec, ...config } = options;
   return {
     ...config,
-    spec: makeOpenApiTestSpecJson(api, { baseUrl: specBaseUrl, transformSpec }),
+    spec: {
-  };
+      kind: "blob",
+      value: makeOpenApiTestSpecJson(api, { baseUrl: specBaseUrl, transformSpec }),
+    },
+    name: config.name ?? "Test API",
+    namespace: config.namespace ?? "test_api",
+    ...(baseUrl === null ? {} : { baseUrl: baseUrl ?? specBaseUrl ?? "https://api.example.test" }),
+  } as OpenApiSpecConfig;
 };
 export const addOpenApiHttpApiTestSource = (
   api: HttpApi.Any,
   options: OpenApiHttpApiTestAddSpecPayloadOptions,
 ) => {
-  const { targetScope, credentialTargetScope, ...sourceOptions } = options;
+  const { ...sourceOptions } = options;
   const config = makeOpenApiHttpApiTestSourceConfig(api, {
     ...sourceOptions,
-    scope: String(targetScope),
+    scope: "unused-http-helper-scope",
-    ...(credentialTargetScope !== undefined
-      ? { credentialTargetScope: String(credentialTargetScope) }
-      : {}),
   });
   return {
-    targetScope,
     spec: config.spec,
     namespace: config.namespace,
-    ...(config.name !== undefined ? { name: config.name } : {}),
+    name: config.name,
-    ...(config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {}),
+    baseUrl: config.baseUrl,
-    ...(config.headers !== undefined ? { headers: config.headers } : {}),
+    ...(sourceOptions.headers !== undefined ? { headers: sourceOptions.headers } : {}),
-    ...(config.queryParams !== undefined ? { queryParams: config.queryParams } : {}),
+    ...(sourceOptions.queryParams !== undefined ? { queryParams: sourceOptions.queryParams } : {}),
     ...(config.oauth2 !== undefined ? { oauth2: config.oauth2 } : {}),
-    ...(credentialTargetScope !== undefined ? { credentialTargetScope } : {}),
+    ...(sourceOptions.specFetchCredentials !== undefined
-    ...(config.specFetchCredentials !== undefined
+      ? { specFetchCredentials: sourceOptions.specFetchCredentials }
-      ? { specFetchCredentials: config.specFetchCredentials }
       : {}),
   };
 };