Unify auth methods across OpenAPI, GraphQL, and MCP on a shared placements model (#943)

* Add @executor-js/http-auth: shared placements-based auth-method model One vocabulary for the HTTP protocol plugins (openapi/graphql/mcp): an apikey method carries N header/query placements, each bound to its own credential variable (or sharing one), plus literal placements for static values. Includes the renderer, required-variable extraction, slug normalization, and catalog projection helpers. Core gains the carrier-agnostic getValues seam on ResolveToolsInput (multi-input analog of getValue) and the catalog wire schema now carries placement variable/literal so multi-input methods survive the HTTP boundary. Removes the dead http-source and graphql-greenfield packages (zero consumers; they forked this exact logic). * MCP: adopt the shared placements auth model McpAuthMethod becomes none | apikey(placements) | oauth2 — one method can mix header and query placements, each rendered from its own credential input (or sharing one). buildConnectorInput renders via the shared renderer over credential.values; invokeTool fails explicitly with connection_value_missing instead of dialing unauthenticated; discovery keeps its tolerant skip. The addServer 'auth' shorthand stays as input sugar. Pre-canonical stored shapes (singular auth, retired header/query kinds, openapi-shaped v1-migration templates) are rewritten by the new one-off migrate-config module — runtime decodes only the canonical shape. Slugs and variable names are preserved verbatim (connection.template / item_ids contracts). The react codec collapses onto the new shared-auth-method-codec in packages/react, deleting the first-named-placement truncation; the edit screen diffs placements deeply. Wire tests pin the extreme case: one method = bearer header + team-id query param, asserted on what the server received. * OpenAPI: adopt the shared placements auth model The apiKey arm of Authentication becomes the shared ApiKeyAuthMethod (placements bound to per-input variables) — the variable()-templated header/query records are retired. The oauth arm keeps its core shape (type: "oauth", stored endpoints + scopes). renderAuthTemplate and requiredTemplateVariables now sit on the shared renderer; the catalog projection and react codec collapse onto the shared helpers. Stored legacy templates are rewritten by the one-off migrate-config module; equivalence tests pin that migrated templates render byte-identically to the legacy renderer (multi-variable Datadog-style, literal-only values, prefix extraction). Slugs and variable names are preserved verbatim. * Wire the one-off auth-config migration + unified-auth e2e scenarios The migration planner (and a shared SQLite runner) live in http-auth; each app routes by plugin_id to the plugins' migrate functions: local runs it at boot after the v1->v2 migration (desktop inherits), selfhost at boot beside its defensive column adds, cloud as an out-of-band script (db:migrate-auth:prod) run before deploying canonical-only code. e2e: scenarios move to canonical wire shapes and gain the extreme case — one MCP source declaring [oauth][bearer header + team-id query (two inputs)][bearer header][query token], one connection per method, every invocation made through the real MCP execute surface and asserted against what a recording MCP server received. The selfhost browser suite gains the 2-input connect modal scenario (one field per input, both rendered together on the wire). * GraphQL: adopt the shared placements auth model GraphqlAuthMethod becomes none | apikey(placements) | oauth2(header?, prefix?) — one method can mix header and query placements, each rendered from its own credential input. The local renderer is deleted: apikey renders through the shared renderer, oauth2 through oauthBearerPlacement (custom header/prefix overrides preserved). Introspection, discovery, and invoke run on credential.values; a missing input fails explicitly, naming the variable. Pre-canonical stored shapes (retired {kind:'apiKey', in, name} entries, openapi-shaped v1-migration templates, the singular auth field — incl. the v1 output that wrote BOTH auth:{oauth2} and an apiKey array) are rewritten by the one-off migrate-config module. The react codec collapses onto shared-auth-method-codec, deleting the one-template-per-placement workaround. Wire tests pin the extreme case (bearer header + team-id query on one method) against a recording GraphQL server, on both introspection and invocation. * Sweep remaining consumers onto the canonical auth shapes Examples (docs quickstart + regenerated snippet, promise-sdk, all-plugins), the kernel dynamic-worker integration test, and the local/cloud auth-tool-failure suites move off the retired variable()-templated apiKey shape. Boundary lint suppressions for the migration runner/script; changelog stub for the new http-auth package. * e2e: make the sandbox tool-result assertion shape-agnostic * Changeset + repo notes for the unified auth model * Fold http-auth into @executor-js/sdk as the /http-auth subpath Carrier-agnosticism is a composition property, not a location one: core never imports the module, so it doesn't need its own package. The vocabulary ships as @executor-js/sdk/http-auth (browser-safe subpath, own tsup entry); the standalone package, its workspace entry, deps, and fixed-group/changeset references are gone. * Accept request-shaped auth authoring on every plugin Auth inputs take two dialects, normalized to the one stored model: the canonical placements shape, and the request-shaped template that reads like the request it produces — { type: "apiKey", headers: { Authorization: ["Bearer ", variable("token")] }, queryParams: { team_id: [variable("team_id")] } } variable() is exported from each plugin. Authoring is strict where the migration is tolerant: a template value renders at most ONE variable, as the FINAL part — exotic interleavings are rejected at decode with a pointed message instead of silently flattened (only the one-off migration flattens, for data that already exists). The dialect is accepted by addServer/addIntegration/addSpec/configure on all three plugins (typed clients included — the docs quickstart and the auth-tool-failure suites author this way again), expanded before merge so stored configs stay canonical. Wire tests pin that an authored template renders identically to its canonical twin. * One apikey authoring dialect: request-shaped in, placements out Auth INPUTS accept exactly one apikey shape — the request-shaped template (headers/queryParams records with variable() slots) — expanded to canonical placements at the boundary. Stored configs and the catalog keep reading as placements; apiKeyAuthTemplateFromMethod serializes them back, so every read-modify-write surface (edit screen replace, custom- method remove, add flows) round-trips through one serializer instead of the wire accepting two dialects. Published schemas now teach a single authoring shape; canonical placement inputs are rejected with a schema error pointing at the dialect. * One discriminator: OpenAPI oauth templates re-key to kind:"oauth2" Every auth method is now kind-keyed — the core OAuthAuthentication shape drops its legacy type:"oauth" spelling, so the Authentication union narrows on .kind alone and the '"kind" in template' guards are gone. The one-off config migration rewrites stored type:"oauth" entries (slug and endpoints verbatim); oauth INPUTS are wire-typed (plain slug) and branded in the normalize pass, letting the HTTP handlers pass payloads through untouched. * Migration script: TLS for direct connections + post-migration decode audit The script connects to PlanetScale directly (no Hyperdrive), which requires TLS. The plan now also audits the SIMULATED final state of every protocol-plugin row — rewritten or untouched — against the new runtime's canonical decoders and refuses to write if any row would read as 'no usable config' after deploy. Verified against prod: 343 rows, 302 rewrite, audit clean.

Rhys Sullivan committed 5 months ago

Commit c92bbda1 parent 7212406122 files · +4629 −5854Browse files

Showing the changes to packages/plugins/openapi/src (20 of 122 files). Show all

Unified · Split

20 files

packages/plugins/openapi/src/api/group.ts +15 −24
packages/plugins/openapi/src/api/handlers.ts +2 −14
packages/plugins/openapi/src/promise.ts +6 −9
packages/plugins/openapi/src/react/AddOpenApiSource.tsx +18 −20
packages/plugins/openapi/src/react/OpenApiAccountsPanel.tsx +6 −2
packages/plugins/openapi/src/react/auth-method-config.test.ts +90 −83
packages/plugins/openapi/src/react/auth-method-config.ts +45 −158
packages/plugins/openapi/src/sdk/config.ts +21 −65
packages/plugins/openapi/src/sdk/configure.test.ts +72 −27
packages/plugins/openapi/src/sdk/describe-auth-methods.test.ts +6 −7
packages/plugins/openapi/src/sdk/google-bundle.test.ts +2 −2
packages/plugins/openapi/src/sdk/google-discovery.test.ts +5 −5
packages/plugins/openapi/src/sdk/google-discovery.ts +1 −1
packages/plugins/openapi/src/sdk/index.ts +7 −3
packages/plugins/openapi/src/sdk/migrate-config.test.ts +225 −0
packages/plugins/openapi/src/sdk/migrate-config.ts +70 −0
packages/plugins/openapi/src/sdk/multi-scope-bearer.test.ts +3 −3
packages/plugins/openapi/src/sdk/plugin.test.ts +5 −5
packages/plugins/openapi/src/sdk/plugin.ts +29 −87
packages/plugins/openapi/src/sdk/types.ts +45 −30

packages/plugins/openapi/src/api/group.ts+15−24

@@ -1,5 +1,6 @@
1	import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";	1	import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
2	import { Schema } from "effect";	2	import { Schema } from "effect";
		3	import { ApiKeyAuthMethod, ApiKeyAuthTemplate } from "@executor-js/sdk/http-auth";
3	import {	4	import {
4	InternalError,	5	InternalError,
5	IntegrationAlreadyExistsError,	6	IntegrationAlreadyExistsError,
@@ -46,29 +47,19 @@ const OpenApiSpecInputPayload = Schema.Union([ · 40 unmodified lines
46	}),	47	}),
47	]);	48	]);
48		49
49	const AuthenticationVariablePayload = Schema.Struct({	50	const OAuthTemplatePayload = Schema.Struct({
50	type: Schema.Literal("variable"),	51	slug: Schema.String,
51	name: Schema.String,	52	kind: Schema.Literal("oauth2"),
		53	authorizationUrl: Schema.String,
		54	tokenUrl: Schema.String,
		55	scopes: Schema.Array(Schema.String),
52	});	56	});
53	const AuthenticationTemplateValuePayload = Schema.Union([	57
54	Schema.String,	58	/** Auth INPUTS: oauth templates + the request-shaped apikey dialect. */
55	Schema.Array(Schema.Union([Schema.String, AuthenticationVariablePayload])),	59	const AuthenticationPayload = Schema.Union([OAuthTemplatePayload, ApiKeyAuthTemplate]);
56	]);	60
57	const AuthenticationPayload = Schema.Union([	61	/** Auth in RESPONSES: the canonical stored shapes (placements). */
58	Schema.Struct({	62	const AuthenticationResponse = Schema.Union([OAuthTemplatePayload, ApiKeyAuthMethod]);
59	slug: Schema.String,
60	type: Schema.Literal("apiKey"),
61	headers: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValuePayload)),
62	queryParams: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValuePayload)),
63	}),
64	Schema.Struct({
65	slug: Schema.String,
66	type: Schema.Literal("oauth"),
67	authorizationUrl: Schema.String,
68	tokenUrl: Schema.String,
69	scopes: Schema.Array(Schema.String),
70	}),
71	]);
72		63
73	const AddSpecPayload = Schema.Struct({	64	const AddSpecPayload = Schema.Struct({
74	spec: OpenApiSpecInputPayload,	65	spec: OpenApiSpecInputPayload,
@@ -119,13 +110,13 @@ const OpenApiConfigView = Schema.Struct({ · 44 unmodified lines
119	baseUrl: Schema.optional(Schema.String),	110	baseUrl: Schema.optional(Schema.String),
120	headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),	111	headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
121	queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),	112	queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),
122	authenticationTemplate: Schema.optional(Schema.Array(AuthenticationPayload)),	113	authenticationTemplate: Schema.optional(Schema.Array(AuthenticationResponse)),
123	});	114	});
124		115
125	// The configure result — the merged `authenticationTemplate` after the new	116	// The configure result — the merged `authenticationTemplate` after the new
126	// custom methods were appended/replaced.	117	// custom methods were appended/replaced.
127	const ConfigureResponse = Schema.Struct({	118	const ConfigureResponse = Schema.Struct({
128	authenticationTemplate: Schema.Array(AuthenticationPayload),	119	authenticationTemplate: Schema.Array(AuthenticationResponse),
129	});	120	});
130		121
131	// ---------------------------------------------------------------------------	122	// ---------------------------------------------------------------------------

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

 import { Context, Effect } from "effect";
 import { addGroup, capture } from "@executor-js/api";
-import { AuthTemplateSlug } from "@executor-js/sdk/shared";
-import type { Authentication } from "../sdk";
 import type { OpenApiPluginExtension } from "../sdk/plugin";
 import { OpenApiGroup } from "./group";
             baseUrl: payload.baseUrl,
             headers: payload.headers ? { ...payload.headers } : undefined,
             queryParams: payload.queryParams ? { ...payload.queryParams } : undefined,
-            authenticationTemplate: payload.authenticationTemplate?.map(
+            authenticationTemplate: payload.authenticationTemplate,
-              (entry): Authentication => ({
-                ...entry,
-                slug: AuthTemplateSlug.make(entry.slug),
-              }),
-            ),
           });
         }),
       ),
         Effect.gen(function* () {
           const ext = yield* OpenApiExtensionService;
           const authenticationTemplate = yield* ext.configure(params.slug, {
-            authenticationTemplate: payload.authenticationTemplate.map(
+            authenticationTemplate: payload.authenticationTemplate,
-              (entry): Authentication => ({
-                ...entry,
-                slug: AuthTemplateSlug.make(entry.slug),
-              }),
-            ),
             mode: payload.mode ?? "merge",
           });
           return { authenticationTemplate: [...authenticationTemplate] };

packages/plugins/openapi/src/promise.ts+6−9

@@ -7,12 +7,9 @@ export type { · 6 unmodified lines
7	OpenApiPreviewInput,	7	OpenApiPreviewInput,
8	} from "./sdk/plugin";	8	} from "./sdk/plugin";
9		9
10	// Auth-template authoring helpers. `variable("token")` marks where a	10	// Auth-template authoring helpers. Author apikey methods as canonical
11	// connection's resolved credential renders into an `apiKey` template.	11	// placements, or request-shaped: `headers: { Authorization: ["Bearer ",
12	export { variable, TOKEN_VARIABLE } from "./sdk/types";	12	// variable("token")] }` — both normalize to the same stored model.
13	export type {	13	export { TOKEN_VARIABLE } from "./sdk/types";
14	Authentication,	14	export type { Authentication, AuthenticationInput, APIKeyAuthentication } from "./sdk/types";
15	APIKeyAuthentication,	15	export { variable, type ApiKeyAuthTemplate } from "@executor-js/sdk/http-auth";
16	AuthenticationVariable,
17	AuthenticationTemplateValue,
18	} from "./sdk/types";

packages/plugins/openapi/src/react/AddOpenApiSource.tsx+18−20

   useSlugAlreadyExists,
 } from "@executor-js/react/lib/integration-add";
-import { authenticationFromEditorValue, editorValueFromAuthentication } from "./auth-method-config";
+import {
+  authenticationFromEditorValue,
+  editorValueFromAuthentication,
+  openApiWireAuthInput,
+} from "./auth-method-config";
 import { addOpenApiSpec, previewOpenApiSpec } from "./atoms";
 import { OpenApiSourceDetailsFields } from "./OpenApiSourceDetailsFields";
 import { GoogleProductPicker } from "./GoogleProductPicker";
   type GoogleOpenApiPreset,
 } from "../sdk/google-presets";
 import type { SpecPreview, HeaderPreset, OAuth2Preset } from "../sdk/preview";
-import {
+import { type APIKeyAuthentication, type Authentication, type ServerInfo } from "../sdk/types";
-  type APIKeyAuthentication,
-  type Authentication,
-  type ServerInfo,
-  TOKEN_VARIABLE,
-  variable,
-} from "../sdk/types";
 import { expandServerUrlOptions } from "../sdk/openapi-utils";
 const GOOGLE_BUNDLE_BASE_URL = "https://www.googleapis.com/";
 const apiKeyTemplateFromHeaderPreset = (
   preset: HeaderPreset,
   slug: AuthTemplateSlug,
-): APIKeyAuthentication => {
+): APIKeyAuthentication => ({
-  const headers: Record<string, (string | ReturnType<typeof variable>)[]> = {};
+  slug,
-  for (const headerName of preset.secretHeaders) {
+  kind: "apikey",
+  // Every secret header shares the one credential input (the canonical
+  // `token`, stored as an absent placement variable).
+  placements: preset.secretHeaders.map((headerName) => {
     const prefix = headerPrefix(preset, headerName);
-    headers[headerName] = prefix ? [prefix, variable(TOKEN_VARIABLE)] : [variable(TOKEN_VARIABLE)];
+    return { carrier: "header" as const, name: headerName, ...(prefix ? { prefix } : {}) };
-  }
+  }),
-  return { slug, type: "apiKey", headers };
+});
-};
 const oauthTemplateFromPreset = (
   preset: OAuth2Preset,
   scopes: readonly string[],
 ): OAuthAuthentication => ({
   slug,
-  type: "oauth",
+  kind: "oauth2",
   authorizationUrl: resolveOAuthUrl(
     Option.getOrElse(preset.authorizationUrl, () => ""),
     baseUrl,
         baseUrl: resolvedBaseUrl,
         ...(!isGoogleBundlePreset && editedAuthenticationTemplate.length > 0
           ? {
-              authenticationTemplate: editedAuthenticationTemplate.map((entry) => ({
+              // Serialize to the wire input dialect (apikey → request-shaped).
-                ...entry,
+              authenticationTemplate: editedAuthenticationTemplate.map(openApiWireAuthInput),
-                slug: String(entry.slug),
-              })),
             }
           : {}),
       },

packages/plugins/openapi/src/react/OpenApiAccountsPanel.tsx+6−2

 } from "@executor-js/react/lib/custom-auth-methods";
 import { openApiConfigAtom, openapiConfigure } from "./atoms";
-import { authMethodsFromConfig, templateFromPlacements } from "./auth-method-config";
+import {
+  authMethodsFromConfig,
+  templateFromPlacements,
+  openApiWireAuthInput,
+} from "./auth-method-config";
 import { googleAudienceWarningsForUrls } from "../sdk/google-presets";
 import type { Authentication } from "../sdk/types";
       const exit = await doConfigure({
         params: { slug },
         payload: {
-          authenticationTemplate: input.authenticationTemplate,
+          authenticationTemplate: input.authenticationTemplate.map(openApiWireAuthInput),
           ...(input.mode ? { mode: input.mode } : {}),
         },
         reactivityKeys: integrationWriteKeys,

packages/plugins/openapi/src/react/auth-method-config.test.ts+90−83

 import { describe, expect, it } from "@effect/vitest";
 import { AuthTemplateSlug } from "@executor-js/sdk/shared";
-import type { AuthTemplateEditorValue } from "@executor-js/react/components/auth-template-editor";
 import {
+  authMethodsFromConfig,
   authenticationFromEditorValue,
   editorValueFromAuthentication,
   templateFromPlacements,
 } from "./auth-method-config";
-import { TOKEN_VARIABLE, variable, type Authentication } from "../sdk/types";
+import type { Authentication } from "../sdk/types";
-describe("editorValueFromAuthentication", () => {
+describe("authMethodsFromConfig", () => {
-  it("maps a bearer apiKey header template → an apikey editor value with prefix", () => {
+  it("projects oauth templates with their stored endpoints + scopes", () => {
-    const template: Authentication = {
+    const methods = authMethodsFromConfig([
-      slug: AuthTemplateSlug.make("apikey-0"),
+      {
-      type: "apiKey",
+        slug: AuthTemplateSlug.make("oauth"),
-      headers: { Authorization: ["Bearer ", variable(TOKEN_VARIABLE)] },
+        kind: "oauth2",
-    };
+        authorizationUrl: "https://x.example/auth",
-    expect(editorValueFromAuthentication(template)).toEqual({
+        tokenUrl: "https://x.example/token",
-      kind: "apikey",
+        scopes: ["read"],
-      placements: [
+      },
-        { carrier: "header", name: "Authorization", prefix: "Bearer ", variable: "token" },
+    ]);
-      ],
+    expect(methods[0]).toMatchObject({
-    });
+      id: "oauth",
-  });
-  it("maps a query apiKey template → an apikey editor value (empty prefix)", () => {
-    const template: Authentication = {
-      slug: AuthTemplateSlug.make("apikey-1"),
-      type: "apiKey",
-      queryParams: { api_key: [variable(TOKEN_VARIABLE)] },
-    };
-    expect(editorValueFromAuthentication(template)).toEqual({
-      kind: "apikey",
-      placements: [{ carrier: "query", name: "api_key", prefix: "", variable: "token" }],
-    });
-  });
-  it("maps an oauth template → an oauth editor value carrying endpoints + scopes", () => {
-    const template: Authentication = {
-      slug: AuthTemplateSlug.make("oauth-google"),
-      type: "oauth",
-      authorizationUrl: "https://accounts.example.com/o/oauth2/auth",
-      tokenUrl: "https://oauth2.example.com/token",
-      scopes: ["openid", "email"],
-    };
-    expect(editorValueFromAuthentication(template)).toEqual({
       kind: "oauth",
-      authorizationUrl: "https://accounts.example.com/o/oauth2/auth",
+      source: "spec",
-      tokenUrl: "https://oauth2.example.com/token",
+      oauth: {
-      scopes: ["openid", "email"],
+        authorizationUrl: "https://x.example/auth",
+        tokenUrl: "https://x.example/token",
+        scopes: ["read"],
+      },
     });
   });
-});
-describe("authenticationFromEditorValue", () => {
+  it("projects apikey methods, multi-placement and multi-variable intact", () => {
-  it("returns null for a 'none' value (nothing to register)", () => {
+    const methods = authMethodsFromConfig([
-    expect(authenticationFromEditorValue({ kind: "none" })).toBeNull();
+      {
+        slug: "custom_dd",
+        kind: "apikey",
+        placements: [
+          { carrier: "header", name: "DD-API-KEY", variable: "dd_api_key" },
+          { carrier: "query", name: "team_id", variable: "team_id" },
+        ],
+      },
+    ]);
+    expect(methods[0]).toMatchObject({ id: "custom_dd", kind: "apikey", source: "custom" });
+    expect(methods[0]?.placements).toEqual([
+      { carrier: "header", name: "DD-API-KEY", prefix: "", variable: "dd_api_key" },
+      { carrier: "query", name: "team_id", prefix: "", variable: "team_id" },
+    ]);
   });
+});
-  it("builds an apiKey template from placements, stamping the slug", () => {
+describe("editor round-trip", () => {
-    const value: AuthTemplateEditorValue = {
+  it("apikey stored → editor → stored preserves placements and shared token input", () => {
+    const stored: Authentication = {
+      slug: "bearer",
       kind: "apikey",
-      placements: [{ carrier: "header", name: "X-Token", prefix: "" }],
+      placements: [
+        { carrier: "header", name: "Authorization", prefix: "Bearer " },
+        { carrier: "query", name: "token" },
+      ],
     };
-    expect(authenticationFromEditorValue(value, "custom_x")).toEqual(
+    const editor = editorValueFromAuthentication(stored);
-      templateFromPlacements(value.placements, "custom_x"),
+    const back = authenticationFromEditorValue(editor, "bearer");
-    );
+    expect(back).toEqual(stored);
   });
-  it("builds an oauth template from an oauth value", () => {
+  it("oauth stored → editor carries endpoints + scopes", () => {
-    const value: AuthTemplateEditorValue = {
+    expect(
+      editorValueFromAuthentication({
+        slug: AuthTemplateSlug.make("oauth"),
+        kind: "oauth2",
+        authorizationUrl: "https://x.example/auth",
+        tokenUrl: "https://x.example/token",
+        scopes: ["a", "b"],
+      }),
+    ).toEqual({
       kind: "oauth",
-      authorizationUrl: "https://a.example.com/auth",
+      authorizationUrl: "https://x.example/auth",
-      tokenUrl: "https://a.example.com/token",
+      tokenUrl: "https://x.example/token",
-      scopes: ["read"],
+      scopes: ["a", "b"],
-    };
-    expect(authenticationFromEditorValue(value, "oauth-0")).toEqual({
-      slug: AuthTemplateSlug.make("oauth-0"),
-      type: "oauth",
-      authorizationUrl: "https://a.example.com/auth",
-      tokenUrl: "https://a.example.com/token",
-      scopes: ["read"],
     });
   });
+  it("none editor value yields no method", () => {
+    expect(authenticationFromEditorValue({ kind: "none" })).toBeNull();
+  });
 });
-describe("round-trip (apiKey + oauth)", () => {
+describe("templateFromPlacements", () => {
-  it("apiKey: editorValue ∘ authentication is identity for the placement shape", () => {
+  it("multi-placement custom methods assign distinct name-derived variables", () => {
-    const template: Authentication = {
+    expect(
-      slug: AuthTemplateSlug.make("apikey-0"),
+      templateFromPlacements(
-      type: "apiKey",
+        [
-      headers: { Authorization: ["Bearer ", variable(TOKEN_VARIABLE)] },
+          { carrier: "header", name: "DD-API-KEY", prefix: "" },
-    };
+          { carrier: "header", name: "DD-APPLICATION-KEY", prefix: "" },
-    const value = editorValueFromAuthentication(template);
+        ],
-    const back = authenticationFromEditorValue(value, "apikey-0");
+        "custom_dd",
-    expect(back).toEqual(template);
+      ),
+    ).toEqual({
+      slug: "custom_dd",
+      kind: "apikey",
+      placements: [
+        { carrier: "header", name: "DD-API-KEY", variable: "dd_api_key" },
+        { carrier: "header", name: "DD-APPLICATION-KEY", variable: "dd_application_key" },
+      ],
+    });
   });
-  it("oauth: editorValue ∘ authentication preserves endpoints + scopes", () => {
+  it("a lone placement keeps the canonical token input (stored absent)", () => {
-    const template: Authentication = {
+    expect(templateFromPlacements([{ carrier: "query", name: "api_key", prefix: "" }])).toEqual({
-      slug: AuthTemplateSlug.make("oauth-x"),
+      slug: "",
-      type: "oauth",
+      kind: "apikey",
-      authorizationUrl: "https://a.example.com/auth",
+      placements: [{ carrier: "query", name: "api_key" }],
-      tokenUrl: "https://a.example.com/token",
+    });
-      scopes: ["read", "write"],
-    };
-    const back = authenticationFromEditorValue(editorValueFromAuthentication(template), "oauth-x");
-    expect(back).toEqual(template);
   });
 });

packages/plugins/openapi/src/react/auth-method-config.ts+45−158

@@ -1,192 +1,79 @@
1	// ---------------------------------------------------------------------------	1	// ---------------------------------------------------------------------------
2	// OpenAPI ↔ generic auth-method converters.	2	// OpenAPI ↔ generic auth-method converters — a thin oauth adapter over the
3	//	3	// shared codec (`@executor-js/react/lib/shared-auth-method-codec`). The
4	// The generic Accounts hub speaks in plugin-agnostic `AuthMethod` /	4	// apikey/none paths (multi-placement, multi-variable) live in the shared
5	// `Placement` values (`@executor-js/react/lib/auth-placements`). The OpenAPI	5	// codec; OpenAPI only contributes its oauth flavor: stored endpoints + scopes
6	// plugin stores auth as the HTTP-transport-specific `APIKeyAuthentication`	6	// (`kind: "oauth2"`, the core `OAuthAuthentication` shape) that pre-fill the client-registration form.
7	// template (header/query slots templated with `variable("token")`). These two
8	// converters bridge the wire template to/from the generic placement model, so
9	// they live with the OpenAPI plugin — they touch the openapi sdk
10	// `Authentication` types and would pull transport specifics into core.
11	// ---------------------------------------------------------------------------	7	// ---------------------------------------------------------------------------
12		8
13	import { AuthTemplateSlug } from "@executor-js/sdk/shared";	9	import { AuthTemplateSlug } from "@executor-js/sdk/shared";
14	import type { AuthMethod, Placement } from "@executor-js/react/lib/auth-placements";	10	import type { AuthMethod, Placement } from "@executor-js/react/lib/auth-placements";
15	import type { AuthTemplateEditorValue } from "@executor-js/react/components/auth-template-editor";	11	import type { AuthTemplateEditorValue } from "@executor-js/react/components/auth-template-editor";
16
17	import {	12	import {
18	TOKEN_VARIABLE,	13	authMethodFromSharedTemplate,
19	variable,	14	editorPlacementsFromWire,
20	type APIKeyAuthentication,	15	editorValueFromSharedMethod,
21	type Authentication,	16	wireAuthInputFromShared,
22	type AuthenticationTemplateValue,	17	wirePlacementsFromEditor,
23	} from "../sdk/types";	18	} from "@executor-js/react/lib/shared-auth-method-codec";
24		19
25	// ---------------------------------------------------------------------------	20	import type { APIKeyAuthentication, Authentication, AuthenticationInput } from "../sdk/types";
26	// Template value → placement prefix.
27	//
28	// A header/query slot serializes the credential as `name -> [prefix, token]`,
29	// where `prefix` is the leading literal string before the `variable("token")`
30	// part. A bare `[token]` (or string-only) value has an empty prefix.
31	// ---------------------------------------------------------------------------
32		21
33	const isVariablePart = (part: string \| { readonly type: "variable"; readonly name: string }) =>	22	/** Serialize a canonical method into the wire input union (apikey → the
34	typeof part !== "string" && part.type === "variable";	23	* request-shaped dialect; oauth passes through). */
		24	export const openApiWireAuthInput = (method: Authentication): AuthenticationInput =>
		25	method.kind === "oauth2" ? method : (wireAuthInputFromShared(method) as AuthenticationInput);
35		26
36	/** Extract the literal prefix preceding the credential variable, plus the	27	export const placementsFromApiKey = (template: APIKeyAuthentication): readonly Placement[] =>
37	* variable name that placement renders from (`token` for single-input methods,	28	editorPlacementsFromWire(template.placements);
38	* a distinct name per input for multi-input ones). */
39	const parseTemplateValue = (
40	value: AuthenticationTemplateValue,
41	): { readonly prefix: string; readonly variable: string } => {
42	if (typeof value === "string") return { prefix: "", variable: TOKEN_VARIABLE };
43	const parts: string[] = [];
44	for (const part of value) {
45	if (isVariablePart(part)) {
46	return { prefix: parts.join(""), variable: (part as { readonly name: string }).name };
47	}
48	if (typeof part === "string") parts.push(part);
49	}
50	return { prefix: parts.join(""), variable: TOKEN_VARIABLE };
51	};
52		29
53	export const placementsFromApiKey = (template: APIKeyAuthentication): Placement[] => {	30	const oauthAuthMethod = (template: Extract<Authentication, { kind: "oauth2" }>): AuthMethod => {
54	const placements: Placement[] = [];	31	const slug = String(template.slug);
55	for (const [name, value] of Object.entries(template.headers ?? {})) {	32	return {
56	const { prefix, variable } = parseTemplateValue(value);	33	id: slug,
57	placements.push({ carrier: "header", name, prefix, variable });	34	label: "OAuth2",
58	}	35	kind: "oauth",
59	for (const [name, value] of Object.entries(template.queryParams ?? {})) {	36	source: slug.startsWith("custom_") ? "custom" : "spec",
60	const { prefix, variable } = parseTemplateValue(value);	37	template: AuthTemplateSlug.make(slug),
61	placements.push({ carrier: "query", name, prefix, variable });	38	placements: [],
62	}	39	// Carry the integration's declared endpoints/scopes so the
63	return placements;	40	// client-registration form pre-fills them.
64	};	41	oauth: {
65		42	authorizationUrl: template.authorizationUrl,
66	// ---------------------------------------------------------------------------	43	tokenUrl: template.tokenUrl,
67	// Templates → generic methods.	44	scopes: template.scopes,
68	// ---------------------------------------------------------------------------	45	},
69		46	};
70	const labelForApiKey = (slug: string, placements: readonly Placement[]): string => {
71	const first = placements[0];
72	if (first) return `API key (${first.name \|\| (first.carrier === "header" ? "header" : "query")})`;
73	return `API key (${slug})`;
74	};	47	};
75		48
76	/** Map each stored auth template to a generic `AuthMethod`. */	49	/** Map each stored auth template to a generic `AuthMethod`. */
77	export function authMethodsFromConfig(templates: readonly Authentication[]): AuthMethod[] {	50	export function authMethodsFromConfig(templates: readonly Authentication[]): AuthMethod[] {
78	return templates.map((template: Authentication): AuthMethod => {	51	return templates.map((template: Authentication): AuthMethod => {
79	const slug = String(template.slug);	52	if (template.kind === "oauth2") return oauthAuthMethod(template);
80	const source: "spec" \| "custom" = slug.startsWith("custom_") ? "custom" : "spec";	53	return authMethodFromSharedTemplate(template);
81	if (template.type === "oauth") {
82	return {
83	id: slug,
84	label: "OAuth2",
85	kind: "oauth",
86	source,
87	template: AuthTemplateSlug.make(slug),
88	placements: [],
89	// Carry the integration's declared endpoints/scopes so the
90	// client-registration form pre-fills them.
91	oauth: {
92	authorizationUrl: template.authorizationUrl,
93	tokenUrl: template.tokenUrl,
94	scopes: template.scopes,
95	},
96	};
97	}
98	const placements = placementsFromApiKey(template);
99	return {
100	id: slug,
101	label: labelForApiKey(slug, placements),
102	kind: "apikey",
103	source,
104	template: AuthTemplateSlug.make(slug),
105	placements,
106	};
107	});	54	});
108	}	55	}
109		56
110	// ---------------------------------------------------------------------------	57	/** Build an apikey method from generic placements. When `slug` is omitted the
111	// Generic placements → apiKey template (inverse).	58	* backend assigns a `custom_<id>` slug. */
112	//
113	// Each placement becomes a header/query slot whose value is
114	// `prefix ? [prefix, variable("token")] : [variable("token")]`. A custom method
115	// may omit `slug`; the backend backfills `custom_<id>`.
116	// ---------------------------------------------------------------------------
117
118	/** Slugify a placement name into a variable identifier: `DD-API-KEY` →
119	* `dd_api_key`. */
120	const slugifyVariable = (name: string): string =>
121	name
122	.toLowerCase()
123	.replace(/[^a-z0-9]+/g, "_")
124	.replace(/^_+\|_+$/g, "");
125
126	/** Assign an input variable to each (named) placement. A lone input is the
127	* canonical `token`; multiple inputs each get their own distinct variable so a
128	* connection can carry a different value per location. An explicit
129	* `placement.variable` (from a round-trip) is honored. */
130	const assignVariables = (placements: readonly Placement[]): Map<Placement, string> => {
131	const named = placements.filter((p) => p.name);
132	const out = new Map<Placement, string>();
133	if (named.length <= 1) {
134	for (const p of named) out.set(p, p.variable ?? TOKEN_VARIABLE);
135	return out;
136	}
137	const taken = new Set<string>();
138	for (const p of named) {
139	const base = slugifyVariable(p.name) \|\| "input";
140	let candidate = p.variable ?? base;
141	let n = 2;
142	while (taken.has(candidate)) candidate = `${base}_${n++}`;
143	taken.add(candidate);
144	out.set(p, candidate);
145	}
146	return out;
147	};
148
149	const valueFromPlacement = (placement: Placement, varName: string): AuthenticationTemplateValue =>
150	placement.prefix ? [placement.prefix, variable(varName)] : [variable(varName)];
151
152	/** Build an `APIKeyAuthentication` template from generic placements. When
153	* `slug` is omitted the backend assigns a `custom_<id>` slug. */
154	export function templateFromPlacements(	59	export function templateFromPlacements(
155	placements: readonly Placement[],	60	placements: readonly Placement[],
156	slug?: string,	61	slug?: string,
157	): APIKeyAuthentication {	62	): APIKeyAuthentication {
158	const variables = assignVariables(placements);
159	const headers: Record<string, AuthenticationTemplateValue> = {};
160	const queryParams: Record<string, AuthenticationTemplateValue> = {};
161	for (const placement of placements) {
162	if (!placement.name) continue;
163	const varName = variables.get(placement) ?? TOKEN_VARIABLE;
164	if (placement.carrier === "header") {
165	headers[placement.name] = valueFromPlacement(placement, varName);
166	} else {
167	queryParams[placement.name] = valueFromPlacement(placement, varName);
168	}
169	}
170	return {	63	return {
171	slug: AuthTemplateSlug.make(slug ?? ""),	64	slug: slug ?? "",
172	type: "apiKey",	65	kind: "apikey",
173	...(Object.keys(headers).length > 0 ? { headers } : {}),	66	placements: wirePlacementsFromEditor(placements),
174	...(Object.keys(queryParams).length > 0 ? { queryParams } : {}),
175	};	67	};
176	}	68	}
177		69
178	// ---------------------------------------------------------------------------	70	// ---------------------------------------------------------------------------
179	// Stored `Authentication` ⇆ generic `AuthTemplateEditorValue`.	71	// Stored `Authentication` ⇆ generic `AuthTemplateEditorValue`.
180	//
181	// The shared add-time `AuthTemplateEditor` edits a plugin-agnostic value; these
182	// bridge it to/from the OpenAPI wire template so a spec-detected method seeds an
183	// editable default and the user's edits round-trip back to `Authentication[]`
184	// on submit. apiKey → placements; oauth → endpoints + scopes.
185	// ---------------------------------------------------------------------------	72	// ---------------------------------------------------------------------------
186		73
187	/** Convert one stored `Authentication` template into a generic editor value. */	74	/** Convert one stored `Authentication` template into a generic editor value. */
188	export function editorValueFromAuthentication(template: Authentication): AuthTemplateEditorValue {	75	export function editorValueFromAuthentication(template: Authentication): AuthTemplateEditorValue {
189	if (template.type === "oauth") {	76	if (template.kind === "oauth2") {
190	return {	77	return {
191	kind: "oauth",	78	kind: "oauth",
192	authorizationUrl: template.authorizationUrl ?? "",	79	authorizationUrl: template.authorizationUrl ?? "",
@@ -194,7 +81,7 @@ export function editorValueFromAuthentication(template: Authentication): AuthTem · 1 unmodified line
194	scopes: template.scopes ?? [],	81	scopes: template.scopes ?? [],
195	};	82	};
196	}	83	}
197	return { kind: "apikey", placements: placementsFromApiKey(template) };	84	return editorValueFromSharedMethod(template);
198	}	85	}
199		86
200	/** Build an `OAuthAuthentication` template from a generic oauth editor value. */	87	/** Build an `OAuthAuthentication` template from a generic oauth editor value. */
@@ -203,7 +90,7 @@ const oauthTemplateFromEditorValue = ( · 2 unmodified lines
203	slug?: string,	90	slug?: string,
204	): Authentication => ({	91	): Authentication => ({
205	slug: AuthTemplateSlug.make(slug ?? ""),	92	slug: AuthTemplateSlug.make(slug ?? ""),
206	type: "oauth",	93	kind: "oauth2",
207	authorizationUrl: value.authorizationUrl,	94	authorizationUrl: value.authorizationUrl,
208	tokenUrl: value.tokenUrl,	95	tokenUrl: value.tokenUrl,
209	scopes: [...value.scopes],	96	scopes: [...value.scopes],

packages/plugins/openapi/src/sdk/config.ts+21−65

 import { Option, Schema } from "effect";
+import {
+  ApiKeyAuthMethod,
+  TOKEN_VARIABLE,
+  renderAuthPlacements,
+  requiredPlacementVariables,
+} from "@executor-js/sdk/http-auth";
-import type { Authentication, AuthenticationTemplateValue, AuthenticationVariable } from "./types";
+import type { Authentication } from "./types";
-import { TOKEN_VARIABLE } from "./types";
 // ---------------------------------------------------------------------------
 // OpenAPI integration config — the opaque blob stored on the catalog
 //   - the auth templates a connection's value is rendered through.
 // ---------------------------------------------------------------------------
-const AuthenticationVariableSchema = Schema.Struct({
-  type: Schema.Literal("variable"),
-  name: Schema.String,
-});
-const AuthenticationTemplateValueSchema = Schema.Union([
-  Schema.String,
-  Schema.Array(Schema.Union([Schema.String, AuthenticationVariableSchema])),
-]);
-const APIKeyAuthenticationSchema = Schema.Struct({
-  slug: Schema.String,
-  type: Schema.Literal("apiKey"),
-  headers: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValueSchema)),
-  queryParams: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValueSchema)),
-});
 const OAuthAuthenticationSchema = Schema.Struct({
   slug: Schema.String,
-  type: Schema.Literal("oauth"),
+  kind: Schema.Literal("oauth2"),
   authorizationUrl: Schema.String,
   tokenUrl: Schema.String,
   scopes: Schema.Array(Schema.String),
 });
-export const AuthenticationSchema = Schema.Union([
+export const AuthenticationSchema = Schema.Union([OAuthAuthenticationSchema, ApiKeyAuthMethod]);
-  OAuthAuthenticationSchema,
-  APIKeyAuthenticationSchema,
-]);
 export const OpenApiIntegrationConfigSchema = Schema.Struct({
   /** Inlined OpenAPI document text (resolved + parsed source of truth). */
 // ---------------------------------------------------------------------------
 // Template rendering — "auth state derived into the auth-template format"
-// (D11). The resolved credential value renders into the template's
+// (D11). An apiKey method renders through the shared placements renderer; an
-// `variable("token")` slots, identically for apiKey and oauth (the oauth value
+// oauth template (no explicit placement) renders a bearer `authorization`
-// IS the access token). Returns the headers + query params to apply.
+// header from the `token` input (the access token).
 // ---------------------------------------------------------------------------
-const isVariable = (part: string | AuthenticationVariable): part is AuthenticationVariable =>
-  typeof part !== "string";
-const renderTemplateValue = (
-  template: AuthenticationTemplateValue,
-  values: Record<string, string | null>,
-): string => {
-  if (typeof template === "string") return template;
-  return template.map((part) => (isVariable(part) ? (values[part.name] ?? "") : part)).join("");
-};
 export interface RenderedAuth {
   readonly headers: Record<string, string>;
   readonly queryParams: Record<string, string>;
 }
 /** Render an auth template against a connection's resolved input `values`
- *  (`variable → value`). For an apiKey template, each `variable("<name>")` is
+ *  (`variable → value`). Each placement substitutes from its own entry, so a
- *  substituted from its own entry, so a method with two distinct inputs (e.g.
+ *  method with two distinct inputs (e.g. Datadog) fills each header from a
- *  Datadog) fills each header from a different value. For an oauth template (no
+ *  different value. */
- *  explicit placement), render a bearer Authorization header from `token`. */
 export const renderAuthTemplate = (
   template: Authentication,
   values: Record<string, string | null>,
 ): RenderedAuth => {
-  if (template.type === "oauth") {
+  if (template.kind === "oauth2") {
     return {
       headers: { authorization: `Bearer ${values[TOKEN_VARIABLE] ?? ""}` },
       queryParams: {},
     };
   }
-  const headers: Record<string, string> = {};
+  return renderAuthPlacements(template.placements, values);
-  const queryParams: Record<string, string> = {};
-  for (const [name, tmpl] of Object.entries(template.headers ?? {})) {
-    headers[name] = renderTemplateValue(tmpl, values);
-  }
-  for (const [name, tmpl] of Object.entries(template.queryParams ?? {})) {
-    queryParams[name] = renderTemplateValue(tmpl, values);
-  }
-  return { headers, queryParams };
 };
 /** The distinct input variables a template references — the inputs a connection
- *  must supply. An oauth template needs `token`; an apiKey template needs every
+ *  must supply. An oauth template needs `token`; an apiKey method needs every
- *  `variable("<name>")` across its placements. */
+ *  variable across its placements. */
 export const requiredTemplateVariables = (template: Authentication): readonly string[] => {
-  if (template.type === "oauth") return [TOKEN_VARIABLE];
+  if (template.kind === "oauth2") return [TOKEN_VARIABLE];
-  const names = new Set<string>();
+  return requiredPlacementVariables(template.placements);
-  const collect = (tmpl: AuthenticationTemplateValue): void => {
-    if (typeof tmpl === "string") return;
-    for (const part of tmpl) {
-      if (isVariable(part)) names.add(part.name);
-    }
-  };
-  for (const tmpl of Object.values(template.headers ?? {})) collect(tmpl);
-  for (const tmpl of Object.values(template.queryParams ?? {})) collect(tmpl);
-  return [...names];
 };

packages/plugins/openapi/src/sdk/configure.test.ts+72−27

 // integration's opaque config. These tests exercise the extension method
 // directly (the same path the HTTP `configure` handler calls):
 //   - round-trip: add a custom apiKey method → `getConfig` shows it with the
-//     correct header/query placement + `variable("token")` slot,
+//     correct header/query placements,
 //   - slug generation: a method with no slug is assigned `custom_<id>`,
 //   - slug uniqueness/dedupe: a method whose slug matches an existing entry
 //     replaces it rather than duplicating, and two slug-less methods in one call
 import { makeTestConfig, memoryCredentialsPlugin } from "@executor-js/sdk/testing";
 import { openApiPlugin } from "./plugin";
-import { variable, type APIKeyAuthentication, type Authentication } from "./types";
+import type { APIKeyAuthentication, Authentication, AuthenticationInput } from "./types";
+import { variable } from "@executor-js/sdk/http-auth";
 import {
   makeOpenApiHttpApiTestSourceConfig,
   serveOpenApiHttpApiTestServer,
   return spec.url;
 };
-// A custom apiKey method that places the connection value into `x-api-key`.
+// A custom apiKey method that places the connection value into `x-api-key`,
-const customApiKey: APIKeyAuthentication = {
+// authored request-shaped (the one apikey input dialect).
-  slug: AuthTemplateSlug.make("my_custom"),
+const customApiKey: AuthenticationInput = {
+  slug: "my_custom",
   type: "apiKey",
   headers: { "x-api-key": [variable("token")] },
 };
 // Build an apiKey method WITHOUT a slug — simulating an untyped JSON caller that
 // omits it, which `configure` should backfill with a generated `custom_<id>`.
 // The cast is confined to this one boundary helper.
-const sluglessApiKey = (placement: Omit<APIKeyAuthentication, "slug" | "type">): Authentication =>
+const sluglessApiKey = (
-  // lint-allow-double-cast: fixture — simulates a JSON caller omitting `slug`; configure backfills it
+  template: Omit<AuthenticationInput & { type: "apiKey" }, "slug" | "type">,
-  ({ type: "apiKey", ...placement }) as unknown as Authentication;
+): AuthenticationInput => ({ type: "apiKey", ...template });
 describe("OpenAPI Plugin — configure (custom auth method)", () => {
   it.effect("adds a custom apiKey method and getConfig reflects it", () =>
         const template = (config?.authenticationTemplate ?? []) as readonly Authentication[];
         expect(template).toHaveLength(1);
         const entry = template[0] as APIKeyAuthentication;
-        expect(entry.type).toBe("apiKey");
+        expect(entry.kind).toBe("apikey");
         expect(String(entry.slug)).toBe("my_custom");
-        // The header placement preserves the `variable("token")` slot verbatim.
+        // The placement preserves the canonical `token` input (stored absent).
-        expect(entry.headers).toEqual({ "x-api-key": [variable("token")] });
+        expect(entry.placements).toEqual([{ carrier: "header", name: "x-api-key" }]);
       }),
     ),
   );
       Effect.gen(function* () {
         const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
-        const seedTemplate: Authentication = {
+        const seedTemplate: AuthenticationInput = {
-          slug: AuthTemplateSlug.make("seed"),
+          slug: "seed",
           type: "apiKey",
           headers: { authorization: ["Bearer ", variable("token")] },
         };
           slug: "cfg_genslug",
         });
-        const slugless = sluglessApiKey({
+        const slugless = sluglessApiKey({ headers: { "x-api-key": [variable("token")] } });
-          headers: { "x-api-key": [variable("token")] },
-        });
         const merged = yield* executor.openapi.configure("cfg_genslug", {
           authenticationTemplate: [slugless],
         });
         // Re-submit the same slug with a different placement → replace in place.
-        const replacement: APIKeyAuthentication = {
+        const replacement: AuthenticationInput = {
-          slug: AuthTemplateSlug.make("my_custom"),
+          slug: "my_custom",
           type: "apiKey",
           headers: { "x-other": [variable("token")] },
         };
-        const slugless = sluglessApiKey({
+        const slugless = sluglessApiKey({ queryParams: { api_key: [variable("token")] } });
-          queryParams: { api_key: [variable("token")] },
+        const slugless2 = sluglessApiKey({ queryParams: { token: [variable("token")] } });
-        });
-        const slugless2 = sluglessApiKey({
-          queryParams: { token: [variable("token")] },
-        });
         const merged = yield* executor.openapi.configure("cfg_dedupe", {
           authenticationTemplate: [replacement, slugless, slugless2],
         const replaced = merged.find(
           (m: Authentication) => String(m.slug) === "my_custom",
         ) as APIKeyAuthentication;
-        expect(replaced.headers).toEqual({ "x-other": [variable("token")] });
+        expect(replaced.placements).toEqual([{ carrier: "header", name: "x-other" }]);
       }),
     ),
   );
       Effect.gen(function* () {
         const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
-        const seedTemplate: Authentication = {
+        const seedTemplate: AuthenticationInput = {
-          slug: AuthTemplateSlug.make("seed"),
+          slug: "seed",
           type: "apiKey",
           headers: { authorization: ["Bearer ", variable("token")] },
         };
     ),
   );
+  it.effect("the request-shaped dialect configures a method and renders on the wire", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* servePluginTestApi();
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+        yield* executor.openapi.addSpec({
+          spec: { kind: "blob", value: server.specJson },
+          slug: "cfg_authored",
+          baseUrl: server.baseUrl,
+        });
+        // Authored request-shaped; stored canonical.
+        yield* executor.openapi.configure("cfg_authored", {
+          authenticationTemplate: [
+            {
+              slug: "bearer",
+              type: "apiKey",
+              headers: { authorization: ["Bearer ", variable("token")] },
+            },
+          ],
+        });
+        const config = yield* executor.openapi.getConfig("cfg_authored");
+        expect(config?.authenticationTemplate?.[0]).toEqual({
+          slug: "bearer",
+          kind: "apikey",
+          placements: [{ carrier: "header", name: "authorization", prefix: "Bearer " }],
+        });
+        yield* executor.connections.create({
+          owner: "org",
+          name: ConnectionName.make("main"),
+          integration: IntegrationSlug.make("cfg_authored"),
+          template: AuthTemplateSlug.make("bearer"),
+          value: "authored-secret",
+        });
+        const result = unwrapInvocation(
+          yield* executor.execute(
+            ToolAddress.make("tools.cfg_authored.org.main.items.echoHeaders"),
+            {},
+          ),
+        ).data as { authorization?: string };
+        expect(result.authorization).toBe("Bearer authored-secret");
+      }),
+    ),
+  );
   it.effect("getConfig returns null for an unknown integration", () =>
     Effect.scoped(
       Effect.gen(function* () {

packages/plugins/openapi/src/sdk/describe-auth-methods.test.ts+6−7

 } from "@executor-js/sdk/core";
 import { describeOpenApiAuthMethods, describeOpenApiIntegrationDisplay } from "./plugin";
-import { variable, type Authentication } from "./types";
+import { type Authentication } from "./types";
 // ---------------------------------------------------------------------------
 // `describeOpenApiAuthMethods` projects the stored `authenticationTemplate[]`
       recordWith([
         {
           slug: AuthTemplateSlug.make("bearer"),
-          type: "apiKey",
+          kind: "apikey",
-          headers: { Authorization: ["Bearer ", variable("token")] },
+          placements: [{ carrier: "header", name: "Authorization", prefix: "Bearer " }],
         },
       ]),
     );
         label: "API key (Authorization)",
         kind: "apikey",
         template: "bearer",
-        placements: [
+        // The canonical `token` input is stored (and projected) as absent.
-          { carrier: "header", name: "Authorization", prefix: "Bearer ", variable: "token" },
+        placements: [{ carrier: "header", name: "Authorization", prefix: "Bearer " }],
-        ],
       },
     ]);
   });
       recordWith([
         {
           slug: AuthTemplateSlug.make("oauth"),
-          type: "oauth",
+          kind: "oauth2",
           authorizationUrl: "https://auth.example/authorize",
           tokenUrl: "https://auth.example/token",
           scopes: ["read", "write"],

packages/plugins/openapi/src/sdk/google-bundle.test.ts+2−2

@@ -205,8 +205,8 @@ describe("Google bundle add flow", () => { · 204 unmodified lines
205	// collapses under `https://mail.google.com/`, so the requested consent	205	// collapses under `https://mail.google.com/`, so the requested consent
206	// is clean rather than the raw per-method union.	206	// is clean rather than the raw per-method union.
207	const config = yield* executor.openapi.getConfig("google");	207	const config = yield* executor.openapi.getConfig("google");
208	const oauth = config?.authenticationTemplate?.find((entry) => entry.type === "oauth");	208	const oauth = config?.authenticationTemplate?.find((entry) => entry.kind === "oauth2");
209	expect(oauth?.type === "oauth" ? [...oauth.scopes].sort() : undefined).toEqual(	209	expect(oauth?.kind === "oauth2" ? [...oauth.scopes].sort() : undefined).toEqual(
210	[	210	[
211	"https://mail.google.com/",	211	"https://mail.google.com/",
212	"https://www.googleapis.com/auth/calendar",	212	"https://www.googleapis.com/auth/calendar",

packages/plugins/openapi/src/sdk/google-discovery.test.ts+5−5

packages/plugins/openapi/src/sdk/google-discovery.ts+1−1

@@ -623,7 +623,7 @@ const googleOauthTemplate = (scopes: Record<string, string>): readonly Authentic · 622 unmodified lines
623	[	623	[
624	{	624	{
625	slug: AuthTemplateSlug.make(GOOGLE_OAUTH_SECURITY_SCHEME),	625	slug: AuthTemplateSlug.make(GOOGLE_OAUTH_SECURITY_SCHEME),
626	type: "oauth",	626	kind: "oauth2",
627	authorizationUrl: GOOGLE_OAUTH_AUTHORIZATION_URL,	627	authorizationUrl: GOOGLE_OAUTH_AUTHORIZATION_URL,
628	tokenUrl: GOOGLE_OAUTH_TOKEN_URL,	628	tokenUrl: GOOGLE_OAUTH_TOKEN_URL,
629	scopes: Object.keys(scopes),	629	scopes: Object.keys(scopes),

packages/plugins/openapi/src/sdk/index.ts+7−3

   OperationId,
   HttpMethod,
   ParameterLocation,
-  variable,
+  TOKEN_VARIABLE,
+  normalizeOpenApiAuthInputs,
   type Authentication,
+  type AuthenticationInput,
   type APIKeyAuthentication,
-  type AuthenticationVariable,
-  type AuthenticationTemplateValue,
 } from "./types";
+// Request-shaped authoring: `headers: { Authorization: ["Bearer ", variable("token")] }`.
+export { variable, type ApiKeyAuthTemplate } from "@executor-js/sdk/http-auth";
+export { migrateOpenApiAuthConfig } from "./migrate-config";

packages/plugins/openapi/src/sdk/migrate-config.test.ts+225−0

@@ -0,0 +1,225 @@
	1	import { describe, expect, it } from "@effect/vitest";
	2
	3	import { renderAuthTemplate } from "./config";
	4	import { migrateOpenApiAuthConfig } from "./migrate-config";
	5	import type { Authentication } from "./types";
	6
	7	// ---------------------------------------------------------------------------
	8	// The one-off config migration rewrites the retired `variable()`-templated
	9	// apiKey shape into canonical placements. Slugs and variable names are
	10	// preserved verbatim (`connection.template` / `item_ids` contracts), and the
	11	// EQUIVALENCE tests pin that a migrated template renders byte-identically to
	12	// what the legacy renderer produced for the same values.
	13	// ---------------------------------------------------------------------------
	14
	15	const BASE = { spec: "{}", baseUrl: "https://api.example.com" } as const;
	16
	17	describe("migrateOpenApiAuthConfig", () => {
	18	it("rewrites a single-input bearer template (prefix + token)", () => {
	19	const migrated = migrateOpenApiAuthConfig({
	20	...BASE,
	21	authenticationTemplate: [
	22	{
	23	slug: "bearer",
	24	type: "apiKey",
	25	headers: { Authorization: ["Bearer ", { type: "variable", name: "token" }] },
	26	},
	27	],
	28	});
	29	expect(migrated).toEqual({
	30	...BASE,
	31	authenticationTemplate: [
	32	{
	33	slug: "bearer",
	34	kind: "apikey",
	35	placements: [{ carrier: "header", name: "Authorization", prefix: "Bearer " }],
	36	},
	37	],
	38	});
	39	});
	40
	41	it("rewrites a multi-input template (Datadog), variables preserved verbatim", () => {
	42	const migrated = migrateOpenApiAuthConfig({
	43	...BASE,
	44	authenticationTemplate: [
	45	{
	46	slug: "datadog",
	47	type: "apiKey",
	48	headers: {
	49	"DD-API-KEY": [{ type: "variable", name: "dd_api_key" }],
	50	"DD-APPLICATION-KEY": [{ type: "variable", name: "dd_application_key" }],
	51	},
	52	queryParams: { site: [{ type: "variable", name: "site" }] },
	53	},
	54	],
	55	});
	56	expect(migrated).toEqual({
	57	...BASE,
	58	authenticationTemplate: [
	59	{
	60	slug: "datadog",
	61	kind: "apikey",
	62	placements: [
	63	{ carrier: "header", name: "DD-API-KEY", variable: "dd_api_key" },
	64	{ carrier: "header", name: "DD-APPLICATION-KEY", variable: "dd_application_key" },
	65	{ carrier: "query", name: "site", variable: "site" },
	66	],
	67	},
	68	],
	69	});
	70	});
	71
	72	it("rewrites literal-only template values into literal placements", () => {
	73	const migrated = migrateOpenApiAuthConfig({
	74	...BASE,
	75	authenticationTemplate: [
	76	{
	77	slug: "versioned",
	78	type: "apiKey",
	79	headers: {
	80	"X-Api-Version": "2023-01-01",
	81	Authorization: ["Bearer ", { type: "variable", name: "token" }],
	82	},
	83	},
	84	],
	85	}) as { authenticationTemplate: readonly unknown[] };
	86	expect(migrated.authenticationTemplate[0]).toEqual({
	87	slug: "versioned",
	88	kind: "apikey",
	89	placements: [
	90	{ carrier: "header", name: "X-Api-Version", literal: "2023-01-01" },
	91	{ carrier: "header", name: "Authorization", prefix: "Bearer " },
	92	],
	93	});
	94	});
	95
	96	it('re-keys the retired `type: "oauth"` spelling to `kind: "oauth2"`', () => {
	97	const migrated = migrateOpenApiAuthConfig({
	98	...BASE,
	99	authenticationTemplate: [
	100	{
	101	slug: "oauth",
	102	type: "oauth",
	103	authorizationUrl: "https://x.example/auth",
	104	tokenUrl: "https://x.example/token",
	105	scopes: ["read"],
	106	},
	107	{
	108	slug: "key",
	109	type: "apiKey",
	110	queryParams: { key: [{ type: "variable", name: "token" }] },
	111	},
	112	],
	113	}) as { authenticationTemplate: readonly unknown[] };
	114	expect(migrated.authenticationTemplate[0]).toEqual({
	115	slug: "oauth",
	116	kind: "oauth2",
	117	authorizationUrl: "https://x.example/auth",
	118	tokenUrl: "https://x.example/token",
	119	scopes: ["read"],
	120	});
	121	});
	122
	123	it("is idempotent — canonical configs return null", () => {
	124	const canonical = {
	125	...BASE,
	126	authenticationTemplate: [
	127	{
	128	slug: "bearer",
	129	kind: "apikey",
	130	placements: [{ carrier: "header", name: "Authorization", prefix: "Bearer " }],
	131	},
	132	],
	133	};
	134	expect(migrateOpenApiAuthConfig(canonical)).toBeNull();
	135	const lifted = migrateOpenApiAuthConfig({
	136	...BASE,
	137	authenticationTemplate: [
	138	{ slug: "b", type: "apiKey", headers: { A: [{ type: "variable", name: "token" }] } },
	139	],
	140	});
	141	expect(migrateOpenApiAuthConfig(lifted)).toBeNull();
	142	});
	143
	144	it("leaves template-less, foreign, and unmigratable blobs untouched", () => {
	145	expect(migrateOpenApiAuthConfig({ ...BASE })).toBeNull();
	146	expect(migrateOpenApiAuthConfig({ transport: "remote", endpoint: "x" })).toBeNull();
	147	expect(migrateOpenApiAuthConfig(null)).toBeNull();
	148	expect(
	149	migrateOpenApiAuthConfig({ ...BASE, authenticationTemplate: [{ garbage: true }] }),
	150	).toBeNull();
	151	});
	152	});
	153
	154	// ---------------------------------------------------------------------------
	155	// Equivalence — the migrated template renders EXACTLY what the legacy
	156	// renderer produced. Expected outputs below are the legacy renderer's
	157	// behavior, written out by hand so the old code can stay deleted.
	158	// ---------------------------------------------------------------------------
	159
	160	describe("legacy render equivalence", () => {
	161	const migrateTemplate = (legacy: unknown): Authentication => {
	162	const migrated = migrateOpenApiAuthConfig({
	163	...BASE,
	164	authenticationTemplate: [legacy],
	165	}) as { authenticationTemplate: readonly Authentication[] };
	166	return migrated.authenticationTemplate[0]!;
	167	};
	168
	169	it("bearer header (prefix + token)", () => {
	170	const template = migrateTemplate({
	171	slug: "bearer",
	172	type: "apiKey",
	173	headers: { Authorization: ["Bearer ", { type: "variable", name: "token" }] },
	174	});
	175	expect(renderAuthTemplate(template, { token: "tok_1" })).toEqual({
	176	headers: { Authorization: "Bearer tok_1" },
	177	queryParams: {},
	178	});
	179	});
	180
	181	it("two distinct inputs across headers and query (Datadog-style)", () => {
	182	const template = migrateTemplate({
	183	slug: "datadog",
	184	type: "apiKey",
	185	headers: {
	186	"DD-API-KEY": [{ type: "variable", name: "dd_api_key" }],
	187	"DD-APPLICATION-KEY": [{ type: "variable", name: "dd_application_key" }],
	188	},
	189	queryParams: { team: [{ type: "variable", name: "team" }] },
	190	});
	191	expect(
	192	renderAuthTemplate(template, { dd_api_key: "a", dd_application_key: "b", team: "t" }),
	193	).toEqual({
	194	headers: { "DD-API-KEY": "a", "DD-APPLICATION-KEY": "b" },
	195	queryParams: { team: "t" },
	196	});
	197	});
	198
	199	it("literal-only value renders verbatim with no credential", () => {
	200	const template = migrateTemplate({
	201	slug: "versioned",
	202	type: "apiKey",
	203	headers: {
	204	"X-Api-Version": "2023-01-01",
	205	Authorization: ["Bearer ", { type: "variable", name: "token" }],
	206	},
	207	});
	208	expect(renderAuthTemplate(template, { token: "tok_1" })).toEqual({
	209	headers: { "X-Api-Version": "2023-01-01", Authorization: "Bearer tok_1" },
	210	queryParams: {},
	211	});
	212	});
	213
	214	it("bare query token (no prefix)", () => {
	215	const template = migrateTemplate({
	216	slug: "key",
	217	type: "apiKey",
	218	queryParams: { api_key: [{ type: "variable", name: "token" }] },
	219	});
	220	expect(renderAuthTemplate(template, { token: "k1" })).toEqual({
	221	headers: {},
	222	queryParams: { api_key: "k1" },
	223	});
	224	});
	225	});

packages/plugins/openapi/src/sdk/migrate-config.ts+70−0

@@ -0,0 +1,70 @@
	1	// ---------------------------------------------------------------------------
	2	// One-off config migration — rewrite pre-canonical OpenAPI integration
	3	// `config` blobs into the canonical placements model. Runs once per database
	4	// (boot for local/selfhost, out-of-band script for cloud); runtime code
	5	// decodes ONLY the canonical shape (`decodeOpenApiIntegrationConfig`).
	6	//
	7	// The retired shape is the `variable()`-templated apiKey:
	8	// { slug, type: "apiKey", headers/queryParams: Record<name,
	9	// string \| (string \| {type:"variable", name})[]> }
	10	// Each entry becomes one placement: prefix = literals before the first
	11	// variable, the variable name preserved VERBATIM (it keys the connections'
	12	// stored `item_ids`; the canonical `token` is stored as absent), a
	13	// literal-only value becomes a `literal` placement. OAuth templates
	14	// re-key from the retired `type: "oauth"` spelling to `kind: "oauth2"`.
	15	// ---------------------------------------------------------------------------
	16
	17	import { Option } from "effect";
	18	import {
	19	apiKeyMethodFromLegacyTemplate,
	20	decodeLegacyApiKeyTemplate,
	21	} from "@executor-js/sdk/http-auth";
	22
	23	import { decodeOpenApiIntegrationConfig } from "./config";
	24
	25	const isCanonicalEntry = (entry: unknown): boolean =>
	26	typeof entry === "object" &&
	27	entry !== null &&
	28	"kind" in entry &&
	29	((entry as { kind: unknown }).kind === "apikey" \|\|
	30	(entry as { kind: unknown }).kind === "oauth2");
	31
	32	/** The retired oauth spelling: `type: "oauth"` instead of `kind: "oauth2"`. */
	33	const isLegacyOAuthEntry = (
	34	entry: unknown,
	35	): entry is { readonly type: "oauth" } & Record<string, unknown> =>
	36	typeof entry === "object" &&
	37	entry !== null &&
	38	"type" in entry &&
	39	(entry as { type: unknown }).type === "oauth";
	40
	41	const migrateEntry = (entry: unknown): unknown \| null => {
	42	if (isCanonicalEntry(entry)) return entry;
	43	if (isLegacyOAuthEntry(entry)) {
	44	const { type: _type, ...rest } = entry;
	45	return { ...rest, kind: "oauth2" };
	46	}
	47	const legacy = Option.getOrNull(decodeLegacyApiKeyTemplate(entry));
	48	if (legacy !== null) return apiKeyMethodFromLegacyTemplate(legacy);
	49	return null;
	50	};
	51
	52	/** Rewrite a stored OpenAPI integration config blob into the canonical shape.
	53	* Returns the rewritten config, or `null` when no rewrite is needed (already
	54	* canonical, no auth templates, or not this plugin's shape). Idempotent. */
	55	export const migrateOpenApiAuthConfig = (config: unknown): unknown \| null => {
	56	if (typeof config !== "object" \|\| config === null) return null;
	57	if (!("spec" in config)) return null;
	58	if (!("authenticationTemplate" in config)) return null;
	59
	60	const entries = (config as { authenticationTemplate: unknown }).authenticationTemplate;
	61	if (!Array.isArray(entries)) return null;
	62
	63	const migrated = entries.map(migrateEntry);
	64	if (migrated.some((entry) => entry === null)) return null;
	65	const changed = migrated.some((entry, index) => entry !== entries[index]);
	66	if (!changed) return null;
	67
	68	const next = { ...config, authenticationTemplate: migrated };
	69	return decodeOpenApiIntegrationConfig(next) !== null ? next : null;
	70	};

packages/plugins/openapi/src/sdk/multi-scope-bearer.test.ts+3−3

@@ -36,7 +36,7 @@ import { · 35 unmodified lines
36	} from "@executor-js/plugin-openapi/testing";	36	} from "@executor-js/plugin-openapi/testing";
37		37
38	import { openApiPlugin } from "./plugin";	38	import { openApiPlugin } from "./plugin";
39	import { variable, type Authentication } from "./types";	39	import { type AuthenticationInput } from "./types";
40		40
41	// ---------------------------------------------------------------------------	41	// ---------------------------------------------------------------------------
42	// Test API — a single endpoint that echoes the Authorization header so the	42	// Test API — a single endpoint that echoes the Authorization header so the
@@ -68,10 +68,10 @@ const serveVercel = () => · 25 unmodified lines
68	serveOpenApiHttpApiTestServer({ api: VercelApi, handlersLayer: ProjectsGroupLive });	68	serveOpenApiHttpApiTestServer({ api: VercelApi, handlersLayer: ProjectsGroupLive });
69		69
70	// Bearer template: the connection value renders into `Authorization: Bearer …`.	70	// Bearer template: the connection value renders into `Authorization: Bearer …`.
71	const bearerTemplate: Authentication = {	71	const bearerTemplate: AuthenticationInput = {
72	slug: AuthTemplateSlug.make("bearer"),	72	slug: AuthTemplateSlug.make("bearer"),
73	type: "apiKey",	73	type: "apiKey",
74	headers: { authorization: ["Bearer ", variable("token")] },	74	headers: { authorization: ["Bearer ", { type: "variable" as const, name: "token" }] },
75	};	75	};
76		76
77	const testPlugins = () =>	77	const testPlugins = () =>

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

@@ -32,7 +32,7 @@ import { · 31 unmodified lines
32	} from "@executor-js/sdk/testing";	32	} from "@executor-js/sdk/testing";
33		33
34	import { openApiPlugin } from "./plugin";	34	import { openApiPlugin } from "./plugin";
35	import { variable, type Authentication } from "./types";	35	import { type AuthenticationInput } from "./types";
36	import {	36	import {
37	addOpenApiTestConnection,	37	addOpenApiTestConnection,
38	makeOpenApiHttpApiTestSourceConfig,	38	makeOpenApiHttpApiTestSourceConfig,
@@ -154,16 +154,16 @@ const servePluginTestApi = () => · 115 unmodified lines
154	});	154	});
155		155
156	// An apiKey auth template that places the connection value into `x-api-key`.	156	// An apiKey auth template that places the connection value into `x-api-key`.
157	const apiKeyTemplate: Authentication = {	157	const apiKeyTemplate: AuthenticationInput = {
158	slug: AuthTemplateSlug.make("apiKey"),	158	slug: AuthTemplateSlug.make("apiKey"),
159	type: "apiKey",	159	type: "apiKey",
160	headers: { "x-api-key": [variable("token")] },	160	headers: { "x-api-key": [{ type: "variable" as const, name: "token" }] },
161	};	161	};
162		162
163	// An oauth template — the connection value renders as a bearer token.	163	// An oauth template — the connection value renders as a bearer token.
164	const oauthTemplate: Authentication = {	164	const oauthTemplate: AuthenticationInput = {
165	slug: AuthTemplateSlug.make("oauth"),	165	slug: AuthTemplateSlug.make("oauth"),
166	type: "oauth",	166	kind: "oauth2",
167	authorizationUrl: "https://auth.example.test/authorize",	167	authorizationUrl: "https://auth.example.test/authorize",
168	tokenUrl: "https://auth.example.test/token",	168	tokenUrl: "https://auth.example.test/token",
169	scopes: ["read"],	169	scopes: ["read"],

packages/plugins/openapi/src/sdk/plugin.ts+29−87

   mergeAuthTemplates,
   tool,
   type AuthMethodDescriptor,
-  type AuthPlacementDescriptor,
   type Integration,
   type IntegrationConfig,
   type IntegrationRecord,
 import { previewSpec, type SpecPreview } from "./preview";
 import { openApiPresets } from "./presets";
 import { makeDefaultOpenapiStore, type OpenapiStore, type StoredOperation } from "./store";
-import type { Authentication, AuthenticationTemplateValue } from "./types";
+import type { Authentication } from "./types";
-import { OperationBinding, TOKEN_VARIABLE } from "./types";
+import { OperationBinding, normalizeOpenApiAuthInputs, type AuthenticationInput } from "./types";
+import { ApiKeyAuthTemplate, describeApiKeyAuthMethod } from "@executor-js/sdk/http-auth";
 // ---------------------------------------------------------------------------
 // Plugin config
   readonly headers?: Record<string, string>;
   /** Static query params applied to every request. */
   readonly queryParams?: Record<string, string>;
-  /** Auth methods a connection's value renders through. */
+  /** Auth methods a connection's value renders through — canonical
-  readonly authenticationTemplate?: readonly Authentication[];
+   *  placements or the request-shaped authoring dialect. */
+  readonly authenticationTemplate?: readonly AuthenticationInput[];
 }
 export interface OpenApiExtensionFailure {
    *  already exists, replaces) the integration's existing template array. A
    *  custom apiKey method with no `slug` is assigned a generated `custom_<id>`
    *  slug that is collision-checked against the existing template. */
-  readonly authenticationTemplate: readonly Authentication[];
+  readonly authenticationTemplate: readonly AuthenticationInput[];
   readonly mode?: "merge" | "replace";
 }
   }),
 ]);
-const AuthenticationVariableSchema = Schema.Struct({
-  type: Schema.Literal("variable"),
-  name: Schema.String,
-});
-const AuthenticationTemplateValueSchema = Schema.Union([
-  Schema.String,
-  Schema.Array(Schema.Union([Schema.String, AuthenticationVariableSchema])),
-]);
 const AuthenticationSchema = Schema.Union([
   Schema.Struct({
     slug: Schema.String,
-    type: Schema.Literal("apiKey"),
+    kind: Schema.Literal("oauth2"),
-    headers: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValueSchema)),
-    queryParams: Schema.optional(Schema.Record(Schema.String, AuthenticationTemplateValueSchema)),
-  }),
-  Schema.Struct({
-    slug: Schema.String,
-    type: Schema.Literal("oauth"),
     authorizationUrl: Schema.String,
     tokenUrl: Schema.String,
     scopes: Schema.Array(Schema.String),
   }),
+  // Credential methods are authored request-shaped — the ONE apikey input
+  // dialect: `{ type: "apiKey", headers: { Authorization: ["Bearer ",
+  // variable("token")] }, queryParams: { … } }`.
+  ApiKeyAuthTemplate,
 ]);
 const AddSourceInputSchema = Schema.Struct({
 // Declared auth methods — project the stored `authenticationTemplate` into the
 // catalog's plugin-agnostic `AuthMethodDescriptor[]`. This mirrors the client's
 // `authMethodsFromConfig` (in the React auth-method-config module) on the
-// server so the catalog field is consistent. OpenAPI also renders its own
+// server so the catalog field is consistent. apikey/none projection comes from
-// accounts slot, so this projection is consistency work, not a fix; an absent /
+// the shared model; the oauth method carries the stored endpoints + scopes.
-// malformed config yields `[]` with no regression.
-//
-// Placement prefix extraction: a header/query slot serializes the credential as
-// `name -> [prefix, variable("token")]`; the leading literals before the
-// `variable("token")` part are the prefix (empty for a bare `[token]`).
 // ---------------------------------------------------------------------------
-/** Extract the literal prefix preceding the credential variable, plus the
- *  variable name a placement renders from (`token` for single-input methods, a
- *  distinct name per input for multi-input ones). */
-const parseTemplateValue = (
-  value: AuthenticationTemplateValue,
-): { readonly prefix: string; readonly variable: string } => {
-  if (typeof value === "string") return { prefix: "", variable: TOKEN_VARIABLE };
-  const parts: string[] = [];
-  for (const part of value) {
-    if (typeof part !== "string" && part.type === "variable") {
-      return { prefix: parts.join(""), variable: part.name };
-    }
-    if (typeof part === "string") parts.push(part);
-  }
-  return { prefix: parts.join(""), variable: TOKEN_VARIABLE };
-};
-const placementsFromAuthentication = (
-  template: Extract<Authentication, { readonly type: "apiKey" }>,
-): readonly AuthPlacementDescriptor[] => {
-  const placements: AuthPlacementDescriptor[] = [];
-  for (const [name, value] of Object.entries(template.headers ?? {})) {
-    const { prefix, variable } = parseTemplateValue(value);
-    placements.push({ carrier: "header", name, prefix, variable });
-  }
-  for (const [name, value] of Object.entries(template.queryParams ?? {})) {
-    const { prefix, variable } = parseTemplateValue(value);
-    placements.push({ carrier: "query", name, prefix, variable });
-  }
-  return placements;
-};
-const apiKeyLabel = (slug: string, placements: readonly AuthPlacementDescriptor[]): string => {
-  const first = placements[0];
-  if (first) return `API key (${first.name || (first.carrier === "header" ? "header" : "query")})`;
-  return `API key (${slug})`;
-};
 export const describeOpenApiAuthMethods = (
   record: IntegrationRecord,
 ): readonly AuthMethodDescriptor[] => {
   if (!config) return [];
   return (config.authenticationTemplate ?? []).map(
     (template: Authentication): AuthMethodDescriptor => {
-      const slug = String(template.slug);
+      if (template.kind === "oauth2") {
-      if (template.type === "oauth") {
         return {
-          id: slug,
+          id: String(template.slug),
           label: "OAuth2",
           kind: "oauth",
-          template: slug,
+          template: String(template.slug),
           oauth: {
             authorizationUrl: template.authorizationUrl,
             tokenUrl: template.tokenUrl,
           },
         };
       }
-      const placements = placementsFromAuthentication(template);
+      return describeApiKeyAuthMethod(template);
-      return {
-        id: slug,
-        label: apiKeyLabel(slug, placements),
-        kind: "apikey",
-        template: slug,
-        placements,
-      };
     },
   );
 };
             // Google Discovery converter derived from the spec (the bundle add
             // path relies on this — it has no preview to detect auth from).
             ...(config.authenticationTemplate
-              ? { authenticationTemplate: config.authenticationTemplate }
+              ? {
+                  authenticationTemplate: normalizeOpenApiAuthInputs(config.authenticationTemplate),
+                }
               : resolved.authenticationTemplate
                 ? { authenticationTemplate: resolved.authenticationTemplate }
                 : {}),
               const current = decodeOpenApiIntegrationConfig(record.config);
               if (!current) return [] as readonly Authentication[];
+              const incoming = normalizeOpenApiAuthInputs(input.authenticationTemplate);
               const merged =
                 input.mode === "replace"
-                  ? input.authenticationTemplate
+                  ? incoming
-                  : mergeAuthTemplates(
+                  : mergeAuthTemplates(current.authenticationTemplate ?? [], incoming);
-                      current.authenticationTemplate ?? [],
-                      input.authenticationTemplate,
-                    );
               const next: OpenApiIntegrationConfig = {
                 ...current,
                   headers: input.headers,
                   queryParams: input.queryParams,
                   authenticationTemplate: input.authenticationTemplate as
-                    | readonly Authentication[]
+                    | readonly AuthenticationInput[]
                     | undefined,
                 })
                 .pipe(
           if (missing.length > 0) {
             return openApiAuthToolFailure({
               code:
-                template.type === "oauth" ? "oauth_connection_missing" : "connection_value_missing",
+                template.kind === "oauth2"
+                  ? "oauth_connection_missing"
+                  : "connection_value_missing",
               message: `Connection "${credential.connection}" for "${integration}" has no resolvable credential value. Re-authenticate or update the connection.`,
               owner: credential.owner,
               integration,
               connection: String(credential.connection),
-              credentialKind: template.type === "oauth" ? "oauth" : "secret",
+              credentialKind: template.kind === "oauth2" ? "oauth" : "secret",
             });
           }
           const rendered = renderAuthTemplate(template, credential.values);

packages/plugins/openapi/src/sdk/types.ts+45−30

@@ -1,43 +1,58 @@
1	import { Schema } from "effect";	1	import { Schema } from "effect";
2	import type { AuthTemplateSlug } from "@executor-js/sdk/shared";	2	import { AuthTemplateSlug, type OAuthAuthentication } from "@executor-js/sdk/shared";
3	import type { OAuthAuthentication } from "@executor-js/sdk/shared";	3	import {
		4	apiKeyMethodFromAuthTemplate,
		5	isApiKeyAuthTemplate,
		6	type ApiKeyAuthMethod,
		7	type ApiKeyAuthTemplate,
		8	} from "@executor-js/sdk/http-auth";
4		9
5	// ---------------------------------------------------------------------------	10	// ---------------------------------------------------------------------------
6	// Auth-template model (ported from the v2 scaffold `openapi/types.ts`).	11	// Auth-template model.
7	//	12	//
8	// The apiKey template is HTTP-transport-specific: it declares where the user's	13	// The apiKey method is the SHARED placements model (`@executor-js/sdk/http-auth`,
9	// credential goes on the outbound request (headers / query params) via the	14	// the same shape the graphql/mcp plugins store): N header/query placements,
10	// `variable()` templating below. That placement is why it lives with the	15	// each rendered from its own credential input. The oauth template is
11	// openapi plugin rather than in core. The oauth template is mechanism-intrinsic	16	// mechanism-intrinsic and comes from core (`OAuthAuthentication`, keyed
12	// and comes from core (`OAuthAuthentication`); an integration's `Authentication`	17	// `kind: "oauth2"` with stored endpoints+scopes); an integration's
13	// union composes the two. Client credentials (clientId/secret) live on the core	18	// `Authentication` union composes the two. Client credentials
14	// `OAuthClient`, not here.	19	// (clientId/secret) live on the core `OAuthClient`, not here.
		20	//
		21	// Pre-canonical stored templates (`type: "apiKey"` with `variable()`-templated
		22	// header/query records) are rewritten by the one-off config migration
		23	// (`migrate-config.ts`) — runtime code knows only this model.
15	// ---------------------------------------------------------------------------	24	// ---------------------------------------------------------------------------
16		25
17	export type AuthenticationVariable = {	26	export { TOKEN_VARIABLE } from "@executor-js/sdk/http-auth";
18	readonly type: "variable";
19	readonly name: string;
20	};
21
22	/** A literal string, or a parts-array mixing literals and variable refs. */
23	export type AuthenticationTemplateValue = string \| readonly (string \| AuthenticationVariable)[];
24		27
25	export const variable = (name: string): AuthenticationVariable => ({	28	export type APIKeyAuthentication = ApiKeyAuthMethod;
26	type: "variable",
27	name,
28	});
29		29
30	/** The variable name the resolved credential value renders into. */	30	/** Every method is keyed by `kind` — `kind: "oauth2"` \| `kind: "apikey"`. */
31	export const TOKEN_VARIABLE = "token" as const;	31	export type Authentication = OAuthAuthentication \| APIKeyAuthentication;
32		32
33	export type APIKeyAuthentication = {	33	/** What auth inputs accept: oauth templates (wire-typed: plain slug) plus the
34	readonly slug: AuthTemplateSlug;	34	* request-shaped apikey dialect (`type: "apiKey"`, headers/queryParams
35	readonly type: "apiKey";	35	* records) — the ONE apikey authoring shape. Stored configs and the catalog
36	readonly headers?: Record<string, AuthenticationTemplateValue>;	36	* read as canonical placements; `apiKeyAuthTemplateFromMethod` serializes
37	readonly queryParams?: Record<string, AuthenticationTemplateValue>;	37	* them back for read-modify-write flows. */
		38	export type OAuthAuthenticationInput = Omit<OAuthAuthentication, "slug"> & {
		39	readonly slug: string;
38	};	40	};
39		41	export type AuthenticationInput = OAuthAuthenticationInput \| ApiKeyAuthTemplate;
40	export type Authentication = OAuthAuthentication \| APIKeyAuthentication;	42
		43	/** Expand the request-shaped dialect into canonical placements and brand the
		44	* oauth slugs. A dialect entry without a slug gets a blank one —
		45	* `mergeAuthTemplates` backfills `custom_<id>`. */
		46	export const normalizeOpenApiAuthInputs = (
		47	inputs: readonly AuthenticationInput[],
		48	): readonly Authentication[] =>
		49	inputs.map((input): Authentication => {
		50	if (!isApiKeyAuthTemplate(input)) {
		51	return { ...input, slug: AuthTemplateSlug.make(input.slug) };
		52	}
		53	const method = apiKeyMethodFromAuthTemplate(input);
		54	return { ...method, slug: method.slug ?? "" };
		55	});
41		56
42	// ---------------------------------------------------------------------------	57	// ---------------------------------------------------------------------------
43	// Branded IDs	58	// Branded IDs

@@ -243,7 +243,7 @@ it.effect("converts Google Discovery documents into Executor-preserving OpenAPI · 242 unmodified lines
243	// than v1's `oauth2` source config.	243	// than v1's `oauth2` source config.
244	// removed: identityScopes assertion — that field belonged to the v1	244	// removed: identityScopes assertion — that field belonged to the v1
245	// OAuth2SourceConfig slot model, which no longer exists in v2.	245	// OAuth2SourceConfig slot model, which no longer exists in v2.
246	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.type === "oauth");	246	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.kind === "oauth2");
247	expect(oauthTemplate).toBeDefined();	247	expect(oauthTemplate).toBeDefined();
248	}),	248	}),
249	);	249	);
@@ -440,8 +440,8 @@ it.effect("bundles Google Discovery documents into one Google OpenAPI source", ( · 190 unmodified lines
440	expect(extractedChatMessage?.pathTemplate).toBe("/v1/{+name}");	440	expect(extractedChatMessage?.pathTemplate).toBe("/v1/{+name}");
441	expect(extractedChatMessage?.baseUrl).toBe("https://chat.googleapis.com/");	441	expect(extractedChatMessage?.baseUrl).toBe("https://chat.googleapis.com/");
442	// v2: the bundled oauth scopes are carried on the oauth auth template.	442	// v2: the bundled oauth scopes are carried on the oauth auth template.
443	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.type === "oauth");	443	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.kind === "oauth2");
444	expect(oauthTemplate?.type === "oauth" ? oauthTemplate.scopes : undefined).toEqual([	444	expect(oauthTemplate?.kind === "oauth2" ? oauthTemplate.scopes : undefined).toEqual([
445	"https://www.googleapis.com/auth/gmail.metadata",	445	"https://www.googleapis.com/auth/gmail.metadata",
446	"https://www.googleapis.com/auth/chat.spaces.readonly",	446	"https://www.googleapis.com/auth/chat.spaces.readonly",
447	]);	447	]);
@@ -579,8 +579,8 @@ it.effect("compacts and filters the merged bundle scope set into a clean consent · 131 unmodified lines
579		579
580	// The derived oauth auth template carries the compacted/filtered set	580	// The derived oauth auth template carries the compacted/filtered set
581	// (gmail.readonly collapsed, userinfo.email → email, chat.bot/chat.app.* dropped).	581	// (gmail.readonly collapsed, userinfo.email → email, chat.bot/chat.app.* dropped).
582	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.type === "oauth");	582	const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.kind === "oauth2");
583	expect(oauthTemplate?.type === "oauth" ? [...oauthTemplate.scopes].sort() : undefined).toEqual(	583	expect(oauthTemplate?.kind === "oauth2" ? [...oauthTemplate.scopes].sort() : undefined).toEqual(
584	[...expectedConsentScopes].sort(),	584	[...expectedConsentScopes].sort(),
585	);	585	);
586		586