Derive OpenAPI auth methods from the spec when addSpec gets no template

addSpec only persisted auth methods when the caller passed an explicit
authenticationTemplate (or for Google Discovery conversions). The add
page derives templates from the preview client-side before calling it,
but headless callers (MCP execute, direct API) don't — so any spec
added that way silently lost its declared security schemes. The
resulting integration had zero auth methods and its Add-connection
modal rendered a dead 'No authentication' state with nowhere to paste
a credential, even though the connections.createHandoff URL pointing
at it was correct.

- Move the preset-to-template derivation from AddOpenApiSource into
  the sdk (derive-auth.ts); the React add flow now imports it, so the
  two paths cannot drift.
- addSpec falls back to that derivation when no template is passed,
  via a new previewSpecText (preview minus the URL fetch, so addSpec
  keeps its error/context channels).
- Unit test: a bearer-scheme spec added with no template persists a
  derived apikey method and renders a pasted token as a bearer header.
- New e2e scenario walks the whole agentic handoff: addSpec over MCP,
  createHandoff URL contract, browser paste into the add-account
  modal, then a live call through the connection verified against an
  emulated provider's request ledger.

Author: RhysSullivan

e2e/scenarios/connect-handoff.test.ts

@@ -0,0 +1,252 @@
+// The agentic connect handoff: an agent adds an API over MCP, asks for a
+// handoff URL (`coreTools.connections.createHandoff`), and the user opens that
+// URL in a browser to paste the credential. This scenario walks the WHOLE
+// path — the exact flow that failed in production with a "wrong / bad" URL —
+// against a real emulated provider (resend.emulators.dev) so the failure
+// point is captured with trace + screenshots instead of guessed at:
+//
+//   1. MCP `execute` → `openapi.addSpec` registers the emulated Resend API
+//   2. MCP `execute` → `connections.createHandoff` returns the browser URL
+//   3. The URL's origin must be THIS deployment (not a hardcoded host)
+//   4. Playwright opens it: the Add connection modal must be open with a
+//      credential field, the emulator-minted API key is pasted and submitted
+//   5. The saved connection is proven live: `execute` sends an email through
+//      the new tools and the emulator's request ledger shows the call
+//      arriving with the pasted bearer token
+import { randomBytes } from "node:crypto";
+
+import { expect } from "@effect/vitest";
+import { Effect } from "effect";
+import { composePluginApi } from "@executor-js/api/server";
+import { openApiHttpPlugin } from "@executor-js/plugin-openapi/api";
+
+import { scenario } from "../src/scenario";
+import { Api, Browser, Mcp, Target } from "../src/services";
+import type { Identity, Target as TargetShape } from "../src/target";
+import type { BrowserSurface } from "../src/surfaces/browser";
+import type { McpSession } from "../src/surfaces/mcp";
+
+const api = composePluginApi([openApiHttpPlugin()] as const);
+
+const unique = (prefix: string) => `${prefix}_${randomBytes(4).toString("hex")}`;
+
+const EMULATOR_BASE = "https://resend.emulators.dev";
+
+/** Minimal Resend-shaped OpenAPI subset pointed at the emulator. Bearer auth
+ *  mirrors the real provider (and the Sentry spec that failed in prod): the
+ *  add-account modal must render a paste-a-token flow from a bare
+ *  `http`/`bearer` security scheme, not just from an explicit apiKey
+ *  authenticationTemplate. */
+const resendSpec = {
+  openapi: "3.0.3",
+  info: { title: "Resend (emulated)", version: "1.0.0" },
+  paths: {
+    "/emails": {
+      post: {
+        operationId: "sendEmail",
+        tags: ["emails"],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  from: { type: "string" },
+                  to: { type: "string" },
+                  subject: { type: "string" },
+                  html: { type: "string" },
+                },
+                required: ["from", "to", "subject"],
+              },
+            },
+          },
+        },
+        responses: { "200": { description: "sent" } },
+      },
+    },
+  },
+  components: {
+    securitySchemes: { auth_token: { type: "http", scheme: "bearer" } },
+  },
+  security: [{ auth_token: [] }],
+} as const;
+
+const addSpecCode = (slug: string) => `
+const added = await tools.executor.openapi.addSpec({
+  spec: { kind: "blob", value: ${JSON.stringify(JSON.stringify(resendSpec))} },
+  slug: ${JSON.stringify(slug)},
+  baseUrl: ${JSON.stringify(EMULATOR_BASE)},
+});
+return added.ok ? { ok: true, slug: added.data.slug, toolCount: added.data.toolCount } : { ok: false, error: added.error };
+`;
+
+const createHandoffCode = (slug: string) => `
+const handoff = await tools.executor.coreTools.connections.createHandoff({
+  integration: ${JSON.stringify(slug)},
+  owner: "org",
+  label: "Resend (emulated)",
+});
+return handoff.ok ? { ok: true, url: handoff.data.url } : { ok: false, error: handoff.error };
+`;
+
+// Selfhost scenarios share one workspace identity — leaked connections fail
+// other scenarios' zero-state assertions, so remove everything this one made.
+const removeConnectionsCode = (slug: string) => `
+const list = await tools.executor.coreTools.connections.list({});
+const mine = (list.ok ? list.data.connections : []).filter((c) => c.integration === ${JSON.stringify(slug)});
+for (const c of mine) {
+  await tools.executor.coreTools.connections.remove({ owner: c.owner, integration: c.integration, name: c.name });
+}
+return { removed: mine.length };
+`;
+
+const sendEmailCode = (slug: string, subject: string) => `
+const found = await tools.search({ namespace: ${JSON.stringify(slug)}, query: "send email", limit: 5 });
+const path = found.items[0]?.path;
+if (!path) return { ok: false, error: "no send tool found", items: found.items };
+let t = tools;
+for (const seg of path.split(".")) t = t[seg];
+const sent = await t({
+  body: {
+    from: "onboarding@example.com",
+    to: "e2e@example.com",
+    subject: ${JSON.stringify(subject)},
+    html: "<p>connect-handoff e2e</p>",
+  },
+});
+return { ok: sent.ok, path, result: sent.ok ? sent.data : sent.error };
+`;
+
+/** Run `execute`, auto-approving a paused execution (policy elicitation) once,
+ *  and parse the sandbox's JSON return value. */
+const executeJson = (session: McpSession, code: string) =>
+  Effect.gen(function* () {
+    let result = yield* session.call("execute", { code });
+    if (result.text.includes("executionId:")) {
+      result = yield* session.approvePaused(result.text);
+    }
+    expect(result.ok, `execute completed (got: ${result.text.slice(0, 400)})`).toBe(true);
+    return JSON.parse(result.text) as Record<string, unknown>;
+  });
+
+const mintEmulatorApiKey = Effect.promise(async () => {
+  const response = await fetch(`${EMULATOR_BASE}/_emulate/credentials`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ type: "api-key" }),
+  });
+  const body = (await response.json()) as { credential?: { token?: string } };
+  const token = body.credential?.token;
+  if (!token) throw new Error(`emulator credential mint failed: ${JSON.stringify(body)}`);
+  return token;
+});
+
+const fetchLedgerText = Effect.promise(async () => {
+  const response = await fetch(`${EMULATOR_BASE}/_emulate/ledger`);
+  return response.text();
+});
+
+scenario(
+  "Connect · the agentic handoff URL opens this deployment's add-account flow and the pasted key works",
+  { timeout: 240_000 },
+  Effect.gen(function* () {
+    const target = yield* Target;
+    const mcp = yield* Mcp;
+    const browser = yield* Browser;
+    const { client: makeApiClient } = yield* Api;
+
+    const integration = unique("resendhf");
+    const emailSubject = unique("connect-handoff");
+    const apiKey = yield* mintEmulatorApiKey;
+
+    const identity = yield* target.newIdentity();
+    const session = mcp.session(identity);
+    const client = yield* makeApiClient(api, identity);
+
+    yield* runScenario({
+      target,
+      browser,
+      session,
+      identity,
+      integration,
+      emailSubject,
+      apiKey,
+    }).pipe(
+      // Best-effort cleanup even on failure: drop the created connection(s)
+      // over MCP, then the integration over the API.
+      Effect.ensuring(
+        Effect.gen(function* () {
+          yield* session.call("execute", { code: removeConnectionsCode(integration) });
+          yield* client.openapi.removeSpec({ params: { slug: integration } });
+        }).pipe(Effect.ignore),
+      ),
+    );
+  }),
+);
+
+const runScenario = (input: {
+  readonly target: TargetShape;
+  readonly browser: BrowserSurface;
+  readonly session: McpSession;
+  readonly identity: Identity;
+  readonly integration: string;
+  readonly emailSubject: string;
+  readonly apiKey: string;
+}) =>
+  Effect.gen(function* () {
+    const { target, browser, session, identity, integration, emailSubject, apiKey } = input;
+
+    // 1. Agent registers the emulated provider over MCP.
+    const added = yield* executeJson(session, addSpecCode(integration));
+    expect(added.ok, `addSpec succeeded: ${JSON.stringify(added)}`).toBe(true);
+
+    // 2. Agent asks for the browser handoff URL.
+    const handoff = yield* executeJson(session, createHandoffCode(integration));
+    expect(handoff.ok, `createHandoff succeeded: ${JSON.stringify(handoff)}`).toBe(true);
+    const handoffUrl = String(handoff.url);
+
+    // 3. The URL must target THIS deployment. (Production returned a URL the
+    //    user called "wrong/bad" — pin the contract here.)
+    const parsed = new URL(handoffUrl);
+    expect(parsed.origin, `handoff URL (${handoffUrl}) targets this deployment`).toBe(
+      new URL(target.baseUrl).origin,
+    );
+    expect(parsed.pathname).toBe(`/integrations/${integration}`);
+    expect(parsed.searchParams.get("addAccount")).toBe("1");
+
+    // 4. The user opens the handoff URL and pastes the credential.
+    yield* browser.session(identity, async ({ page, step }) => {
+      await step("Open the handoff URL from the agent", async () => {
+        await page.goto(handoffUrl, { waitUntil: "networkidle" });
+      });
+
+      await step("The Add connection modal is open", async () => {
+        await page.getByRole("heading", { name: /Add connection/ }).waitFor({ timeout: 15_000 });
+      });
+
+      await step("Paste the emulator API key", async () => {
+        const credential = page.getByPlaceholder(/paste the value \/ token/i);
+        await credential.waitFor({ timeout: 15_000 });
+        await credential.fill(apiKey);
+      });
+
+      await step("Submit Add connection", async () => {
+        await page.getByRole("button", { name: "Add connection", exact: true }).click();
+        await page
+          .getByRole("heading", { name: /Add connection/ })
+          .waitFor({ state: "hidden", timeout: 20_000 });
+      });
+    });
+
+    // 5. The connection is live: send an email through the new tools and see
+    //    it arrive at the emulator with the pasted token.
+    const sent = yield* executeJson(session, sendEmailCode(integration, emailSubject));
+    expect(sent.ok, `email sent through the pasted connection: ${JSON.stringify(sent)}`).toBe(true);
+
+    const ledger = yield* fetchLedgerText;
+    expect(
+      ledger.includes(emailSubject),
+      "the emulator's request ledger recorded the call made through Executor",
+    ).toBe(true);
+  });