Derive OpenAPI auth methods from the spec when addSpec gets no explicit template (#957)

* 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.

* Default addSpec baseUrl from the spec's servers; explicit [] means no auth

Refinements from review of the derivation fallback:

- baseUrl now also derives from the spec's first server when the caller
  passes none (same default the add page applies). Without it, a
  headless add produced tools with no host to call — every invocation
  failed with a bare 'HTTP request failed'.
- An explicit empty authenticationTemplate now means 'no auth methods'
  and suppresses derivation. The add page sends the user's edited
  method list even when emptied, so deleting every detected method in
  the inspect step survives instead of being silently re-derived.
- The addSpec tool description documents both defaults and the
  override semantics.
- The e2e scenario now adds the integration purely by spec URL — the
  Resend emulator serves its own /openapi.json now — with no baseUrl
  and no template, so both derivations are covered by the live
  paste-key flow and the emulator ledger check.

Author: RhysSullivan

e2e/scenarios/connect-handoff.test.ts

@@ -0,0 +1,218 @@
+// 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";
+
+// The emulator serves its own OpenAPI document (bearer auth, same shape as
+// real Resend — and as the Sentry spec that failed in prod). Adding it by URL
+// with no authenticationTemplate exercises exactly the agentic path: the
+// add-account modal must render a paste-a-token flow derived from the spec's
+// bare `http`/`bearer` security scheme.
+const EMULATOR_SPEC_URL = `${EMULATOR_BASE}/openapi.json`;
+
+const addSpecCode = (slug: string) => `
+const added = await tools.executor.openapi.addSpec({
+  spec: { kind: "url", url: ${JSON.stringify(EMULATOR_SPEC_URL)} },
+  slug: ${JSON.stringify(slug)},
+});
+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);
+  });