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.

Author: RhysSullivan

.changeset/unified-auth-methods.md

@@ -0,0 +1,14 @@
+---
+"executor": minor
+"@executor-js/react": minor
+---
+
+**One auth model across OpenAPI, GraphQL, and MCP**
+
+- Every protocol plugin now stores the same placements-based auth methods (the new `@executor-js/sdk/http-auth` vocabulary): an API-key method carries any mix of header and query placements, each rendered from its own credential input — so one source can declare OAuth, a bearer-header-plus-team-id-query method, a plain bearer, and a query token side by side, and one connection can carry several values (e.g. both Datadog keys).
+- MCP and GraphQL gain what only OpenAPI could do before: multi-placement methods, query-parameter credentials (servers like ui.sh's `?token=`), and multi-input connections. Rendering, catalog projection, slug normalization, and the React method editor/codec are shared instead of triplicated; the connect modal collects one value per input.
+- Invoking with an unresolvable credential input now fails with `connection_value_missing` (naming the missing inputs) instead of silently dialing unauthenticated.
+- Stored integration configs are rewritten to the canonical shape by a one-off migration: local and self-host run it automatically at startup; cloud operators run `bun run db:migrate-auth:prod` before deploying. Connection bindings and stored credential values are preserved exactly.
+- Authoring: apikey methods are authored in ONE request-shaped dialect on every plugin — it 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; a plain-string value is a static literal). Inputs normalize to the canonical placements model, which is what stored configs and the catalog read as. Authoring is strict where the renderer is: a value carries at most one variable, as the final part.
+- Every method is keyed by `kind` — OpenAPI's oauth templates re-key from the retired `type: "oauth"` spelling to `kind: "oauth2"` (matching MCP/GraphQL); the one-off migration rewrites stored entries.
+- Breaking (wire): the retired single-placement inputs (`headerName` on MCP, `in`/`name` on GraphQL), raw canonical-placement inputs, and `type: "oauth"` oauth inputs are rejected. The `mcp.addServer` singular `auth` shorthand still works.

AGENTS.md

@@ -47,7 +47,10 @@ before using it.
 ## Package Roles
 
 - `packages/core/sdk`: executor core contracts, plugin wiring, scopes, sources,
-  secrets, policies, and test fixtures.
+  secrets, policies, and test fixtures. The `@executor-js/sdk/http-auth`
+  subpath carries the shared placements-based auth-method vocabulary the HTTP
+  protocol plugins compose (core itself never imports it — composition, not
+  location, keeps core carrier-agnostic).
 - `packages/core/storage-*`: storage adapters and storage test support.
 - `packages/plugins/*`: protocol and provider plugins. Plugin-specific
   runtime, React, API, and testing helpers should live with the owning plugin.

apps/cloud/package.json

@@ -13,6 +13,8 @@
     "db:studio": "drizzle-kit studio",
     "db:studio:prod": "op run --env-file=.env.production -- bun --bun ../../node_modules/.bun/node_modules/drizzle-kit/bin.cjs studio",
     "db:migrate:prod": "op run --env-file=.env.production -- bun --bun ../../node_modules/.bun/node_modules/drizzle-kit/bin.cjs migrate",
+    "db:migrate-auth:prod": "op run --env-file=.env.production -- bun run scripts/migrate-auth-configs.ts",
+    "db:migrate-auth:dev": "op run --env-file=.env.op -- bun run scripts/migrate-auth-configs.ts",
     "db:migrate:dev": "op run --env-file=.env.op -- bun --bun ../../node_modules/.bun/node_modules/drizzle-kit/bin.cjs migrate",
     "build": "node scripts/build.mjs",
     "preview": "vite preview",

apps/cloud/scripts/migrate-auth-configs.ts

@@ -0,0 +1,101 @@
+/* oxlint-disable executor/no-try-catch-or-throw, executor/no-json-parse -- boundary: out-of-band migration script over a raw postgres connection */
+// ---------------------------------------------------------------------------
+// One-off data migration: rewrite pre-canonical integration auth configs
+// into the shared placements model. Run OUT-OF-BAND against the database
+// BEFORE deploying code that only decodes the canonical shape (the same
+// rule as schema migrations — Workers never migrate at request time):
+//
+//   bun run db:migrate-auth:prod      # op run --env-file=.env.production
+//   bun run db:migrate-auth:dev       # against the local PGlite dev db
+//
+// Idempotent — canonical rows plan zero updates, so re-running is safe.
+// Pass --dry-run to print the plan without writing.
+// ---------------------------------------------------------------------------
+
+import postgres from "postgres";
+import { Option } from "effect";
+import { planAuthConfigMigration, type AuthConfigMigrationRow } from "@executor-js/sdk/http-auth";
+import {
+  decodeGraphqlIntegrationConfigOption,
+  migrateGraphqlAuthConfig,
+} from "@executor-js/plugin-graphql";
+import { migrateMcpAuthConfig, parseMcpIntegrationConfig } from "@executor-js/plugin-mcp";
+import {
+  decodeOpenApiIntegrationConfig,
+  migrateOpenApiAuthConfig,
+} from "@executor-js/plugin-openapi";
+
+const transforms = {
+  mcp: migrateMcpAuthConfig,
+  graphql: migrateGraphqlAuthConfig,
+  openapi: migrateOpenApiAuthConfig,
+};
+
+// Whether a config decodes under the NEW runtime (the canonical shapes).
+// Used by the post-migration audit: every row the new code will read must
+// decode, whether the migration rewrote it or left it untouched.
+const decodesCanonically: Record<string, (config: unknown) => boolean> = {
+  mcp: (config) => parseMcpIntegrationConfig(config) !== null,
+  graphql: (config) => Option.isSome(decodeGraphqlIntegrationConfigOption(config)),
+  openapi: (config) => decodeOpenApiIntegrationConfig(config) !== null,
+};
+
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) {
+  console.error("DATABASE_URL is not set");
+  process.exit(1);
+}
+const dryRun = process.argv.includes("--dry-run");
+
+// Direct (non-Hyperdrive) connection — PlanetScale requires TLS.
+const sql = postgres(connectionString, { max: 1, prepare: false, ssl: "require" });
+
+try {
+  const rows = await sql<{ row_id: string; plugin_id: string; config: unknown }[]>`
+    SELECT row_id, plugin_id, config FROM integration
+  `;
+
+  const inputs: AuthConfigMigrationRow[] = rows.map((row) => ({
+    rowId: row.row_id,
+    pluginId: row.plugin_id,
+    // postgres-js parses json columns; tolerate text just in case.
+    config: typeof row.config === "string" ? JSON.parse(row.config) : row.config,
+  }));
+
+  const updates = planAuthConfigMigration(inputs, transforms);
+  console.log(`${rows.length} integration row(s), ${updates.length} to rewrite`);
+
+  // Post-migration audit: simulate the final state of every row this plugin
+  // set owns and check it decodes under the new runtime. A row that neither
+  // rewrites nor decodes would read as "no usable config" after deploy —
+  // surface those BEFORE writing anything.
+  const planned = new Map(updates.map((update) => [update.rowId, update.config]));
+  const undecodable = inputs.filter((row) => {
+    const decodes = decodesCanonically[row.pluginId];
+    if (!decodes) return false; // not a protocol-plugin row (no auth config)
+    return !decodes(planned.get(row.rowId) ?? row.config);
+  });
+  if (undecodable.length > 0) {
+    console.error(`${undecodable.length} row(s) would NOT decode after migration:`);
+    for (const row of undecodable) console.error(`  ${row.pluginId} ${row.rowId}`);
+    process.exit(1);
+  }
+  console.log("audit: every row decodes canonically after migration");
+
+  if (dryRun) {
+    for (const update of updates) console.log(`  would rewrite ${update.rowId}`);
+  } else if (updates.length > 0) {
+    await sql.begin(async (tx) => {
+      for (const update of updates) {
+        await tx`
+          UPDATE integration
+          SET config = ${tx.json(update.config as never)}
+          WHERE row_id = ${update.rowId}
+        `;
+      }
+    });
+    console.log(`rewrote ${updates.length} row(s)`);
+  }
+} finally {
+  await sql.end();
+}

apps/host-selfhost/src/app.ts

@@ -4,7 +4,10 @@ import { Layer } from "effect";
 
 import { composePluginApi, ExecutorApp, textFailureStrategy } from "@executor-js/api/server";
 
+import { runSqliteAuthConfigMigration } from "@executor-js/sdk/http-auth";
+
 import { resolveAuthProviders } from "./auth";
+import { authConfigTransforms } from "./db/auth-config-migration";
 import { makeSelfHostAdminApiLayer } from "./admin/handlers";
 import { makeSelfHostSystemApiLayer } from "./system/handlers";
 import { selfHostAccountMiddleware } from "./account";
@@ -54,6 +57,11 @@ export const makeSelfHostApp = async (options: MakeSelfHostAppOptions = {}) => {
     version: SELF_HOST_SCHEMA_VERSION,
   });
 
+  // One-off data migration: rewrite pre-canonical integration auth configs
+  // into the shared placements model. Idempotent — a no-op once every row is
+  // canonical (same defensive-at-boot pattern as the column adds above).
+  await runSqliteAuthConfigMigration(dbHandle.client, authConfigTransforms);
+
   // ---- auth providers ---------------------------------------------------
   // Better Auth: cookie/bearer/api-key identity + /api/auth handler + account
   // API + MCP OAuth seam, all over the shared libSQL handle.

apps/host-selfhost/src/db/auth-config-migration.ts

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// The per-plugin auth-config transforms the one-off boot migration runs over
+// the `integration` table (see `runSqliteAuthConfigMigration`). Each plugin
+// owns the rewrite of its own legacy config shapes into the canonical
+// placements model; this map only routes by `plugin_id`.
+// ---------------------------------------------------------------------------
+
+import type { AuthConfigTransform } from "@executor-js/sdk/http-auth";
+import { migrateGraphqlAuthConfig } from "@executor-js/plugin-graphql";
+import { migrateMcpAuthConfig } from "@executor-js/plugin-mcp";
+import { migrateOpenApiAuthConfig } from "@executor-js/plugin-openapi";
+
+export const authConfigTransforms: Record<string, AuthConfigTransform> = {
+  mcp: migrateMcpAuthConfig,
+  graphql: migrateGraphqlAuthConfig,
+  openapi: migrateOpenApiAuthConfig,
+};

apps/local/src/db/auth-config-migration.ts

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// The per-plugin auth-config transforms the one-off boot migration runs over
+// the `integration` table (see `runSqliteAuthConfigMigration`). Each plugin
+// owns the rewrite of its own legacy config shapes into the canonical
+// placements model; this map only routes by `plugin_id`.
+// ---------------------------------------------------------------------------
+
+import type { AuthConfigTransform } from "@executor-js/sdk/http-auth";
+import { migrateGraphqlAuthConfig } from "@executor-js/plugin-graphql";
+import { migrateMcpAuthConfig } from "@executor-js/plugin-mcp";
+import { migrateOpenApiAuthConfig } from "@executor-js/plugin-openapi";
+
+export const authConfigTransforms: Record<string, AuthConfigTransform> = {
+  mcp: migrateMcpAuthConfig,
+  graphql: migrateGraphqlAuthConfig,
+  openapi: migrateOpenApiAuthConfig,
+};

apps/local/src/executor.ts

@@ -5,10 +5,12 @@ import { basename, join } from "node:path";
 import { createHash } from "node:crypto";
 
 import { Subject, Tenant, createExecutor, type AnyPlugin, type Executor } from "@executor-js/sdk";
+import { runSqliteAuthConfigMigration } from "@executor-js/sdk/http-auth";
 import { collectTables } from "@executor-js/api/server";
 import { loadPluginsFromJsonc } from "@executor-js/config";
 
 import executorConfig from "../executor.config";
+import { authConfigTransforms } from "./db/auth-config-migration";
 import { createSqliteFumaDb } from "./db/sqlite-fumadb";
 import { migrateLocalV1ToV2IfNeeded } from "./db/v1-v2-migration";
 
@@ -167,6 +169,15 @@ const createLocalExecutorLayer = () => {
         (db) => Effect.promise(() => db.close()).pipe(Effect.ignore),
       );
 
+      // One-off data migration: rewrite pre-canonical integration auth
+      // configs (incl. v1→v2 outputs) into the shared placements model.
+      // Idempotent — a no-op once every row is canonical.
+      yield* Effect.tryPromise({
+        try: () => runSqliteAuthConfigMigration(sqlite.client, authConfigTransforms),
+        catch: (cause) =>
+          new LocalExecutorCreateError({ message: CREATE_SQLITE_ERROR_MESSAGE, cause }),
+      });
+
       // webBaseUrl is where the executor's web UI listens — same port as the
       // daemon API since the daemon serves both. Mirrors serve.ts's port
       // resolution so a custom $PORT flows through. EXECUTOR_WEB_BASE_URL

bun.lock

@@ -4,7 +4,7 @@ Edit examples/docs-sdk-quickstart/src/main.ts between the docs:start/docs:end ma
 _/}
 
 ```ts
-// An integration is the API surface. The apiKey template declares where a
+// An integration is the API surface. The auth template declares where a
 // connection's credential is placed on each request — here, an `X-API-Key`
 // header. `variable("token")` is the slot the resolved credential renders into.
 await executor.openapi.addSpec({