@engenty/wizards-runtime 0.0.0-stage → 0.7.6

package/apps/runtime/dist/connectors/gmail.js

@@ -0,0 +1,107 @@
+import { GOOGLE_OAUTH2, googleJson } from "../engenty/connections-google/shared.js";
+import { htmlToMarkdown } from "../render/convert.js";
+import { dayAfter, mailActions, snippetOf, } from "./mail.js";
+const GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/me";
+const SCOPE_READONLY = "https://www.googleapis.com/auth/gmail.readonly";
+const header = (payload, name) => payload?.headers?.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? null;
+function body(payload, mime) {
+    if (!payload) {
+        return null;
+    }
+    if (payload.mimeType === mime && payload.body?.data) {
+        return Buffer.from(payload.body.data, "base64url").toString("utf8");
+    }
+    for (const part of payload.parts ?? []) {
+        const found = body(part, mime);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+function attachments(payload, out = []) {
+    if (payload?.filename && payload.body?.attachmentId) {
+        out.push({
+            id: payload.body.attachmentId,
+            name: payload.filename,
+            mime: payload.mimeType ?? "application/octet-stream",
+            size: payload.body.size ?? null,
+        });
+    }
+    for (const part of payload?.parts ?? []) {
+        attachments(part, out);
+    }
+    return out;
+}
+function toMessage(raw) {
+    const html = body(raw.payload, "text/html");
+    const text = body(raw.payload, "text/plain") ?? (html ? htmlToMarkdown(html) : (raw.snippet ?? ""));
+    return {
+        id: raw.id,
+        date: raw.internalDate ? new Date(Number(raw.internalDate)).toISOString() : null,
+        from: header(raw.payload, "From"),
+        to: (header(raw.payload, "To") ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+        subject: header(raw.payload, "Subject"),
+        snippet: raw.snippet ?? snippetOf(text),
+        attachments: attachments(raw.payload),
+        text,
+        html,
+    };
+}
+/** Gmail's own search syntax: `{a b}` is "a OR b", dates are `after:`/`before:` days. */
+function query(input) {
+    const quoted = (input.terms ?? []).map((t) => (/\s/.test(t) ? `"${t.replace(/"/g, "")}"` : t));
+    return [
+        quoted.length ? `{${quoted.join(" ")}}` : "",
+        input.from ? `from:${input.from}` : "",
+        input.since ? `after:${input.since.replace(/-/g, "/")}` : "",
+        input.until ? `before:${dayAfter(input.until).replace(/-/g, "/")}` : "",
+        input.has_attachment ? "has:attachment" : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+const getMessage = (ctx, id) => googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(id)}?format=full`);
+const backend = {
+    async search(input, ctx) {
+        const url = new URL(`${GMAIL_API}/messages`);
+        url.searchParams.set("q", query(input));
+        url.searchParams.set("maxResults", String(input.limit ?? 40));
+        const list = await googleJson(ctx, url.toString());
+        const out = [];
+        const ids = (list.messages ?? []).map((m) => m.id);
+        for (let i = 0; i < ids.length; i += 10) {
+            const batch = await Promise.all(ids.slice(i, i + 10).map((id) => getMessage(ctx, id)));
+            out.push(...batch.map(toMessage));
+        }
+        return out.map(({ text: _text, html: _html, to: _to, ...summary }) => summary);
+    },
+    async read(id, ctx) {
+        return toMessage(await getMessage(ctx, id));
+    },
+    async attachment(id, attachmentId, ctx) {
+        const info = attachments((await getMessage(ctx, id)).payload).find((a) => a.id === attachmentId);
+        const data = await googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(id)}/attachments/${encodeURIComponent(attachmentId)}`);
+        if (!data.data) {
+            throw new Error("gmail attachment has no data");
+        }
+        return {
+            name: info?.name ?? "attachment",
+            mime: info?.mime ?? "application/octet-stream",
+            data_base64: Buffer.from(data.data, "base64url").toString("base64"),
+        };
+    },
+};
+export const gmailConnector = {
+    id: "mail-gmail",
+    moduleId: "wizards-mail",
+    name: "Gmail",
+    description: "Read mail in a Gmail or Google Workspace account.",
+    icon: "logo:gmail",
+    toolPrefix: "mail",
+    auth: { kind: "oauth2", oauth2: GOOGLE_OAUTH2 },
+    actions: mailActions(backend, [SCOPE_READONLY]),
+};

package/apps/runtime/dist/connectors/imap.js

@@ -0,0 +1,261 @@
+import { resolveMx } from "node:dns/promises";
+import { ImapFlow } from "imapflow";
+import { htmlToMarkdown } from "../render/convert.js";
+import { assertPublicUrl } from "../tools/net-guard.js";
+import { dayAfter, mailActions, snippetOf, } from "./mail.js";
+const KNOWN_HOSTS = {
+    "gmail.com": "imap.gmail.com",
+    "googlemail.com": "imap.gmail.com",
+    "outlook.com": "outlook.office365.com",
+    "hotmail.com": "outlook.office365.com",
+    "live.com": "outlook.office365.com",
+    "icloud.com": "imap.mail.me.com",
+    "me.com": "imap.mail.me.com",
+    "yahoo.com": "imap.mail.yahoo.com",
+    "gmx.at": "imap.gmx.net",
+    "gmx.de": "imap.gmx.net",
+    "gmx.net": "imap.gmx.net",
+    "web.de": "imap.web.de",
+    "a1.net": "securemail.a1.net",
+    "fastmail.com": "imap.fastmail.com",
+};
+const ALLOW_PRIVATE = process.env.ALLOW_PRIVATE_FETCH === "1";
+/** A mail server that does not answer within this long is reported, not waited for. */
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Google Workspace on a company domain: the domain's mail is handled by Google. */
+async function usesGoogleMail(domain) {
+    try {
+        const records = await Promise.race([
+            resolveMx(domain),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("mx")), 4000)),
+        ]);
+        return records.some((r) => /(^|\.)(google|googlemail)\.com\.?$/i.test(r.exchange));
+    }
+    catch {
+        return false;
+    }
+}
+async function hostFor(credentials, domain) {
+    const typed = credentials.host?.trim();
+    if (typed) {
+        return typed;
+    }
+    if (KNOWN_HOSTS[domain]) {
+        return KNOWN_HOSTS[domain];
+    }
+    return (await usesGoogleMail(domain)) ? "imap.gmail.com" : `imap.${domain}`;
+}
+async function open(credentials) {
+    const email = credentials.email.trim();
+    const domain = email.split("@")[1]?.toLowerCase() ?? "";
+    const host = await hostFor(credentials, domain);
+    const port = Number(credentials.port) || 993;
+    if (!ALLOW_PRIVATE && port !== 993 && port !== 143) {
+        throw new Error("IMAP runs on port 993 (or 143).");
+    }
+    // The host is typed by the person: it must be a public mail server, never this server's network.
+    await assertPublicUrl(`https://${host}`);
+    const client = new ImapFlow({
+        host,
+        port,
+        secure: port === 993,
+        auth: { user: email, pass: credentials.password },
+        logger: false,
+        socketTimeout: 60_000,
+        connectionTimeout: CONNECT_TIMEOUT_MS,
+        greetingTimeout: CONNECT_TIMEOUT_MS,
+    });
+    // A dropped connection must not take the process down.
+    client.on("error", () => undefined);
+    let timer;
+    try {
+        await Promise.race([
+            client.connect(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(Object.assign(new Error("timeout"), { code: "ETIMEDOUT" })), CONNECT_TIMEOUT_MS + 2000);
+            }),
+        ]);
+    }
+    catch (err) {
+        client.close();
+        // The message names the server that was tried, so a wrong guess is visible.
+        throw Object.assign(err instanceof Error ? err : new Error(String(err)), { imapHost: host });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return client;
+}
+/** Runs `use` on the mailbox that holds everything ("All Mail" where the server has one). */
+async function withMailbox(ctx, use) {
+    const client = await open(JSON.parse(ctx.accessToken));
+    try {
+        const boxes = await client.list();
+        const all = boxes.find((b) => b.specialUse === "\\All");
+        const lock = await client.getMailboxLock(all?.path ?? "INBOX", { readOnly: true });
+        try {
+            return await use(client);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    finally {
+        await client.logout().catch(() => undefined);
+    }
+}
+function parts(node, out) {
+    if (!node) {
+        return out;
+    }
+    const name = node.dispositionParameters?.filename ?? node.parameters?.name;
+    const part = node.part ?? "1";
+    if (node.childNodes?.length) {
+        for (const child of node.childNodes) {
+            parts(child, out);
+        }
+    }
+    else if (node.disposition === "attachment" || (name && !node.type.startsWith("text/"))) {
+        out.attachments.push({
+            id: part,
+            name: name ?? `attachment-${part}`,
+            mime: node.type,
+            size: node.size ?? null,
+        });
+    }
+    else if (node.type === "text/plain" && !out.plain) {
+        out.plain = part;
+    }
+    else if (node.type === "text/html" && !out.html) {
+        out.html = part;
+    }
+    return out;
+}
+const emptyParts = () => ({ attachments: [], plain: null, html: null });
+function sender(from) {
+    const f = from?.[0];
+    return f?.address ? (f.name ? `${f.name} <${f.address}>` : f.address) : null;
+}
+async function bytes(client, uid, part) {
+    const { content } = await client.download(uid, part, { uid: true });
+    if (!content) {
+        throw new Error("The mail is no longer there.");
+    }
+    const chunks = [];
+    for await (const chunk of content) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+const backend = {
+    search: (input, ctx) => withMailbox(ctx, async (client) => {
+        const query = {};
+        if (input.since) {
+            query.since = input.since;
+        }
+        if (input.until) {
+            query.before = dayAfter(input.until);
+        }
+        if (input.from) {
+            query.from = input.from;
+        }
+        const terms = input.terms ?? [];
+        if (terms.length === 1) {
+            query.text = terms[0];
+        }
+        else if (terms.length > 1) {
+            query.or = terms.map((text) => ({ text }));
+        }
+        if (!Object.keys(query).length) {
+            query.all = true;
+        }
+        const found = (await client.search(query, { uid: true })) || [];
+        const limit = input.limit ?? 40;
+        // Without the attachment filter the newest `limit` are enough; with it, look further back.
+        const uids = found.slice(-(input.has_attachment ? limit * 4 : limit));
+        if (!uids.length) {
+            return [];
+        }
+        const messages = await client.fetchAll(uids, { envelope: true, bodyStructure: true, internalDate: true }, { uid: true });
+        return messages
+            .map((m) => ({
+            id: String(m.uid),
+            date: m.internalDate ? new Date(m.internalDate).toISOString() : null,
+            from: sender(m.envelope?.from),
+            subject: m.envelope?.subject ?? null,
+            snippet: "",
+            attachments: parts(m.bodyStructure, emptyParts()).attachments,
+        }))
+            .filter((m) => !input.has_attachment || m.attachments.length > 0)
+            .reverse()
+            .slice(0, limit);
+    }),
+    read: (id, ctx) => withMailbox(ctx, async (client) => {
+        const m = await client.fetchOne(id, { envelope: true, bodyStructure: true, internalDate: true }, { uid: true });
+        if (!m) {
+            throw new Error("The mail is no longer there.");
+        }
+        const found = parts(m.bodyStructure, emptyParts());
+        const html = found.html ? (await bytes(client, id, found.html)).toString("utf8") : null;
+        const text = found.plain
+            ? (await bytes(client, id, found.plain)).toString("utf8")
+            : html
+                ? htmlToMarkdown(html)
+                : "";
+        return {
+            id,
+            date: m.internalDate ? new Date(m.internalDate).toISOString() : null,
+            from: sender(m.envelope?.from),
+            to: (m.envelope?.to ?? []).map((t) => t.address ?? "").filter(Boolean),
+            subject: m.envelope?.subject ?? null,
+            snippet: snippetOf(text),
+            attachments: found.attachments,
+            text,
+            html,
+        };
+    }),
+    attachment: (id, attachmentId, ctx) => withMailbox(ctx, async (client) => {
+        const m = await client.fetchOne(id, { bodyStructure: true }, { uid: true });
+        const info = m
+            ? parts(m.bodyStructure, emptyParts()).attachments.find((a) => a.id === attachmentId)
+            : undefined;
+        if (!info) {
+            throw new Error("The mail has no such attachment.");
+        }
+        return {
+            name: info.name,
+            mime: info.mime,
+            data_base64: (await bytes(client, id, attachmentId)).toString("base64"),
+        };
+    }),
+};
+export const imapConnector = {
+    id: "imap",
+    moduleId: "wizards-mail",
+    name: "IMAP",
+    description: "Read mail in any mailbox over IMAP (GMX, iCloud, your own domain …).",
+    icon: "mail",
+    toolPrefix: "mail",
+    auth: {
+        kind: "api_key",
+        apiKey: {
+            fields: [
+                { key: "email", label: "Email address", placeholder: "name@company.com" },
+                { key: "password", label: "Password or app password", secret: true },
+                {
+                    key: "host",
+                    label: "IMAP server",
+                    placeholder: "leave empty for Gmail, GMX, iCloud …",
+                    required: false,
+                },
+                { key: "port", label: "Port", placeholder: "993", required: false },
+            ],
+            verify: async (credentials) => {
+                const client = await open(credentials);
+                await client.logout().catch(() => undefined);
+                return { label: credentials.email.trim(), externalId: credentials.email.trim() };
+            },
+        },
+    },
+    actions: mailActions(backend, []),
+};

package/apps/runtime/dist/connectors/index.js

@@ -0,0 +1,325 @@
+import { isLang } from "@engenty-wizards/shared/definition";
+import { note } from "@engenty-wizards/shared/run";
+import { eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { buildAuthorizationUrl, createOAuth2Pkce, exchangeAuthorizationCode, refreshAccessToken, } from "../engenty/connections-sdk/oauth2.js";
+import { scopesForGroups, } from "../engenty/connections-sdk/types.js";
+import { env } from "../env.js";
+import { NotedError } from "../model-errors.js";
+import { seal, unseal } from "../secrets/crypto.js";
+import { deleteSecret, getSecret, putSecret } from "../store/index.js";
+import { serverText } from "../texts.js";
+import { connectorFetch, MAIL_CONNECTORS, resolveEnv, usable, viaAccount } from "./builtin.js";
+import { resolveConnector } from "./external.js";
+import { AccountConnectError, redeemTicket, refreshThroughAccount, startThroughAccount, } from "./via-account.js";
+/** The connectors a person can pick for each kind of connection. */
+const CONNECTORS = { mail: MAIL_CONNECTORS };
+const HINTS = { imap: "imapHint" };
+/** The built-in connectors' fields in each language; their definitions say them in English. */
+const FIELD_WORDS = {
+    de: {
+        imap: {
+            email: { label: "E-Mail-Adresse", placeholder: "name@firma.at" },
+            password: { label: "Passwort oder App-Passwort" },
+            host: { label: "IMAP-Server", placeholder: "leer lassen bei Gmail, GMX, iCloud …" },
+        },
+    },
+};
+/**
+ * What a connection asks the provider for: what reading needs, plus what each action the wizard
+ * may use needs. A wizard that only reads never asks for the right to send or delete.
+ */
+function scopesFor(connection, connector) {
+    const scopes = new Set(scopesForGroups(connector, new Set(["read"])));
+    for (const action of connector.actions) {
+        if (connection.actions?.includes(action.id)) {
+            for (const scope of action.providerScopes ?? []) {
+                scopes.add(scope);
+            }
+        }
+    }
+    return [...scopes];
+}
+/** Where the provider sends the person back; must be registered with the OAuth client. */
+export function connectRedirectUri() {
+    return env.connectRedirectUrl || `${env.appUrl}/api/connect/callback`;
+}
+const slot = (connectionId) => `connection:${connectionId}`;
+/** A connector that needs no credential: there is nothing for the person to connect. */
+const open = (connector) => connector.auth.kind === "api_key" && connector.auth.apiKey.fields.length === 0;
+/** The connectors behind a connection: the built-in ones of its kind, or the one it names. */
+async function candidates(connection, projectId) {
+    if (connection.connector) {
+        const found = await resolveConnector(projectId, connection.connector);
+        return found ? [found.connector] : [];
+    }
+    return connection.kind ? CONNECTORS[connection.kind] : [];
+}
+export async function connectorOptions(connection, projectId, lang = "en") {
+    const out = [];
+    for (const c of await candidates(connection, projectId)) {
+        if (!(await usable(c))) {
+            continue;
+        }
+        out.push(c.auth.kind === "api_key"
+            ? {
+                id: c.id,
+                name: c.name,
+                auth: "api_key",
+                fields: c.auth.apiKey.fields.map((f) => ({
+                    ...f,
+                    ...(lang === "en" ? undefined : FIELD_WORDS[lang]?.[c.id]?.[f.key]),
+                })),
+                hint: HINTS[c.id] && serverText(lang, HINTS[c.id]),
+            }
+            : { id: c.id, name: c.name, auth: "oauth2" });
+    }
+    return out;
+}
+async function connectorFor(connection, connectorId, projectId) {
+    const connector = (await candidates(connection, projectId)).find((c) => c.id === connectorId);
+    if (!connector) {
+        throw new Error(`Unknown connector "${connectorId}".`);
+    }
+    return connector;
+}
+export async function connectionViews(connections, scope, projectId, 
+/** The language the person reads the connectors' fields in. */
+lang = "en") {
+    return Promise.all(connections.map(async (c) => {
+        const stored = await getSecret(scope, slot(c.id));
+        const only = c.connector ? (await candidates(c, projectId))[0] : undefined;
+        return {
+            id: c.id,
+            kind: c.kind ?? null,
+            connector: c.connector ?? null,
+            title: c.title ?? only?.name ?? null,
+            description: c.description ?? null,
+            account: stored
+                ? {
+                    connector: stored.provider,
+                    label: stored.label,
+                    connectedAt: stored.createdAt.toISOString(),
+                }
+                : only && open(only)
+                    ? { connector: only.id, label: only.name, connectedAt: new Date(0).toISOString() }
+                    : null,
+            connectors: await connectorOptions(c, projectId, lang),
+        };
+    }));
+}
+export async function startOAuth(scope, projectId, runId, connection, connectorId, lang) {
+    const connector = await connectorFor(connection, connectorId, projectId);
+    if (connector.auth.kind !== "oauth2") {
+        throw new Error(`${connector.name} is not connected by signing in.`);
+    }
+    if (await viaAccount(connector)) {
+        // The Manage-App keeps the PKCE verifier; ours stays empty.
+        const state = {
+            scope,
+            projectId,
+            runId,
+            connectionId: connection.id,
+            connectorId,
+            verifier: "",
+            exp: Date.now() + 15 * 60_000,
+            lang,
+        };
+        try {
+            return await startThroughAccount(scopesFor(connection, connector), seal(state), connectRedirectUri());
+        }
+        catch (err) {
+            throw err instanceof AccountConnectError ? new ConnectError(err.message) : err;
+        }
+    }
+    // Servers that hand out OAuth clients on request (most MCP servers): get one on first use.
+    await connector.auth.oauth2.registerClient?.();
+    const pkce = createOAuth2Pkce();
+    const state = {
+        scope,
+        projectId,
+        runId,
+        connectionId: connection.id,
+        connectorId,
+        verifier: pkce.codeVerifier,
+        exp: Date.now() + 15 * 60_000,
+        lang,
+    };
+    return buildAuthorizationUrl({
+        connector,
+        pkce,
+        redirectUri: connectRedirectUri(),
+        scopes: scopesFor(connection, connector),
+        state: seal(state),
+        resolveEnv,
+    });
+}
+/** The language a sign-in was started in, a wizard's or a plugin's; null where it names none. */
+export function oauthStateLang(rawState) {
+    const lang = unseal(rawState)?.lang;
+    return isLang(lang) ? lang : null;
+}
+/** The run an OAuth callback belongs to; its tenant is looked up before the state is used. */
+export function oauthStateRun(rawState) {
+    return unseal(rawState)?.runId ?? null;
+}
+/**
+ * Google came back: with a code, or — connected through the account's Manage-App — with a
+ * ticket that holds the tokens.
+ */
+export async function finishOAuth(answer, rawState) {
+    const state = unseal(rawState);
+    if (!state || state.exp < Date.now()) {
+        throw new Error("The sign-in has expired. Connect again.");
+    }
+    const run = await db.query.run.findFirst({ where: eq(schema.run.id, state.runId) });
+    const connection = run?.definition.connections?.find((c) => c.id === state.connectionId);
+    if (!connection) {
+        throw new Error("The run this sign-in belongs to is gone.");
+    }
+    const connector = await connectorFor(connection, state.connectorId, state.projectId);
+    if (connector.auth.kind !== "oauth2") {
+        throw new Error("not an oauth connector");
+    }
+    const tokens = "ticket" in answer
+        ? await redeemTicket(answer.ticket)
+        : await exchangeAuthorizationCode({
+            code: answer.code,
+            codeVerifier: state.verifier,
+            config: connector.auth.oauth2,
+            redirectUri: connectRedirectUri(),
+            resolveEnv,
+        });
+    // A provider that will not name the account still connected it.
+    const account = (await connector.auth.oauth2
+        .resolveAccount?.(tokens.accessToken, fetch)
+        .catch(() => null)) ?? { label: connector.name };
+    const stored = {
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt?.toISOString() ?? null,
+        scopes: tokens.grantedScopes,
+        ...("ticket" in answer ? { via: "account" } : {}),
+    };
+    await putSecret(state.scope, slot(connection.id), connector.id, account.label, stored);
+    return state;
+}
+/** Connects an `api_key` connector with what the person typed; the connector checks it first. */
+export async function connectWithCredentials(scope, projectId, connection, connectorId, values) {
+    const connector = await connectorFor(connection, connectorId, projectId);
+    if (connector.auth.kind !== "api_key") {
+        throw new Error(`${connector.name} is connected by signing in.`);
+    }
+    const credentials = {};
+    for (const field of connector.auth.apiKey.fields) {
+        const value = String(values[field.key] ?? "").trim();
+        if (!value && field.required !== false) {
+            throw new ConnectError(note("fieldMissing", { label: field.label }));
+        }
+        if (value) {
+            credentials[field.key] = value.slice(0, 500);
+        }
+    }
+    let account;
+    try {
+        account = await connector.auth.apiKey.verify(credentials, connectorFetch);
+    }
+    catch (err) {
+        throw new ConnectError(connectFailure(err));
+    }
+    const stored = {
+        accessToken: JSON.stringify(credentials),
+        refreshToken: null,
+        expiresAt: null,
+        scopes: [],
+    };
+    await putSecret(scope, slot(connection.id), connector.id, account.label, stored);
+    return account.label;
+}
+/** A connect attempt the person can fix (wrong password, unknown server). */
+export class ConnectError extends NotedError {
+}
+function connectFailure(err) {
+    const e = err;
+    const host = e.imapHost ? ` (${e.imapHost})` : "";
+    if (e.authenticationFailed) {
+        const answer = e.responseText?.slice(0, 160);
+        return note("signInRefused", { host, answer: answer ? note("serverSaid", { answer }) : "" });
+    }
+    if (e.code === "ENOTFOUND") {
+        return note("mailServerNotExist", { host });
+    }
+    if (e.code === "ETIMEDOUT" || e.code === "ETIMEOUT" || e.code === "ECONNREFUSED") {
+        return note("mailServerNotResponding", { host });
+    }
+    const detail = String(e.message ?? err).slice(0, 200);
+    return note("connectingNotWork", { host, detail });
+}
+export function disconnect(scope, connectionId) {
+    return deleteSecret(scope, slot(connectionId));
+}
+// --- using ---------------------------------------------------------------------
+/**
+ * The connector and the context its actions run with, for a connection the person has
+ * connected — with a fresh access token. `null` when nothing is connected.
+ */
+export async function connectionContext(scope, connection, projectId) {
+    const stored = await getSecret(scope, slot(connection.id));
+    if (!stored) {
+        const only = connection.connector ? (await candidates(connection, projectId))[0] : undefined;
+        return only && open(only)
+            ? { connector: only, label: only.name, ctx: actionContext(scope, connection, only, "{}", []) }
+            : null;
+    }
+    const connector = await connectorFor(connection, stored.provider, projectId);
+    let data = stored.data;
+    const expires = data.expiresAt ? Date.parse(data.expiresAt) : null;
+    if (connector.auth.kind === "oauth2" &&
+        data.refreshToken &&
+        expires !== null &&
+        expires - Date.now() < 5 * 60_000) {
+        const tokens = data.via === "account"
+            ? await refreshThroughAccount(data.refreshToken)
+            : await refreshAccessToken({
+                config: connector.auth.oauth2,
+                refreshToken: data.refreshToken,
+                resolveEnv,
+            });
+        data = {
+            ...(data.via ? { via: data.via } : {}),
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? data.refreshToken,
+            expiresAt: tokens.expiresAt?.toISOString() ?? null,
+            scopes: tokens.grantedScopes.length ? tokens.grantedScopes : data.scopes,
+        };
+        await putSecret(scope, slot(connection.id), connector.id, stored.label, data);
+    }
+    return {
+        connector,
+        label: stored.label,
+        ctx: actionContext(scope, connection, connector, data.accessToken, data.scopes, stored),
+    };
+}
+function actionContext(scope, connection, connector, accessToken, scopes, stored) {
+    return {
+        accessToken,
+        fetchImpl: connectorFetch,
+        log: () => undefined,
+        connection: {
+            id: connection.id,
+            connector_id: connector.id,
+            auth_kind: connector.auth.kind,
+            autonomous_mode: "read_only",
+            connected_by: null,
+            created_at: (stored?.createdAt ?? new Date()).toISOString(),
+            display_name: stored?.label ?? connector.name,
+            error_message: null,
+            external_account: stored?.label ?? null,
+            granted_scopes: scopes,
+            owner_user_id: null,
+            space_id: null,
+            status: "active",
+            tenant_id: scope.wizardId,
+        },
+    };
+}