@every-app/sdk 0.2.0 → 0.3.0-rc.10

package/dist/server/integrationFetch.js

@@ -0,0 +1,688 @@
+import { ACCOUNT_HEADER, CATALOG, ConfigurationError, GATEWAY_ERROR_HEADER, INTEGRATION_PROXY_PREFIX, OAUTH_TOKEN_BODY_LIMIT, allowedScopes, apiKeyHosts, authorizationFor, capabilitySettings, carriesToken, declaredScopeSets, describeTokenEndpoints, devProviderFile, grantedScopes, heldTokenCallAllowed, injectClientCredentials, integrationProxyPath, oauthClientCredentials, oauthReadMethods, oauthWriteMethods, providerSettingPrefix, requestedScopes, requestedTokenScopes, resolveDevProvider, rewriteTokenRequestScope, scopeExcess, tokenEndpointFor, tokenGrantType, EMAIL_SENDERS_ENV, chooseEmailProvider, parseEmailList, parseEmailSender, } from "../internal/index.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
+import { BINDING_ORIGIN, gatewayBinding, streamingRequest, } from "./gatewayFetch.js";
+export function integrationFetch({ env, provider, for: explicitTarget, account, optional = false, }) {
+    const catalogEntry = fetchableCapability(provider);
+    const what = `integrationFetch("${provider}")`;
+    // Checked now, so a call nobody's fails where the fetch is made; and
+    // again per call, where an identity may since have neared its expiry.
+    attributionFor(env, explicitTarget, what);
+    const values = env;
+    const binding = gatewayBinding(env);
+    if (binding && typeof binding.fetch !== "function") {
+        throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
+    }
+    // An id outside the catalog: the gateway's to resolve over the binding,
+    // or in local dev, the registered row's spec `everyapp dev` hands over.
+    const integration = catalogEntry ??
+        (binding ? undefined : devRegisteredProvider(provider, values));
+    const local = binding || !integration ? null : localCredentials(integration, values);
+    // In dev an OAuth provider with a held token in `.dev.vars` serves API
+    // calls without the client (the token stands in for a connection).
+    const devToken = !binding && integration?.mode === "oauth_client" && integration.flow
+        ? stringValue(values[devAccessTokenName(provider)])
+        : undefined;
+    // An OAuth provider with a Gateway-owned flow answers an API call
+    // without the client (`integration_not_connected`, below); a token
+    // endpoint call without the client throws when it is made.
+    const decidesLater = integration?.mode === "oauth_client" && integration.flow !== undefined;
+    if (!binding && !local && !devToken && integration && !decidesLater) {
+        if (optional)
+            return null;
+        const names = [
+            ...capabilitySettings(integration),
+            ...(integration.mode === "oauth_client" && integration.flow
+                ? [devAccessTokenName(provider)]
+                : []),
+        ];
+        throw new ConfigurationError(`${integration.label} is unavailable: deploy with the EVERY_APP_GATEWAY binding, or set ${names.join(", ")} in .dev.vars for local development.`);
+    }
+    return async (input, init) => {
+        const target = attributionFor(env, explicitTarget, what);
+        const outbound = new Request(input, init);
+        const upstream = new URL(outbound.url);
+        const headers = new Headers(outbound.headers);
+        headers.delete("authorization");
+        headers.delete("cookie");
+        if (!integration) {
+            // A gateway-registered provider: the gateway holds its spec, so the
+            // gateway checks the host; here only that it is https at all.
+            if (upstream.protocol !== "https:") {
+                throw new TypeError(`integrationFetch("${provider}") reaches https URLs only, not ${upstream.protocol}//${upstream.host}.`);
+            }
+            applyAttribution(headers, target);
+            return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
+        }
+        if (integration.mode === "oauth_client") {
+            // A call to the provider's API with the token the gateway holds
+            // (docs/design/2026-10-oauth-providers.md section 7), for an entry
+            // that supports the Gateway-owned flow; a token endpoint stays the
+            // app-driven call it always was.
+            const toApi = integration.flow !== undefined &&
+                upstream.protocol === "https:" &&
+                integration.api.includes(upstream.host) &&
+                !tokenEndpointFor(integration, upstream);
+            if (toApi) {
+                if (binding) {
+                    if (account)
+                        headers.set(ACCOUNT_HEADER, account);
+                    applyAttribution(headers, target);
+                    return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
+                }
+                return devHeldTokenCall({
+                    provider,
+                    capability: integration,
+                    outbound,
+                    upstream,
+                    headers,
+                    values,
+                });
+            }
+            return oauthClientCall({
+                provider: provider,
+                capability: integration,
+                outbound,
+                upstream,
+                headers,
+                values,
+                ...(binding
+                    ? { binding, target }
+                    : { client: local }),
+            });
+        }
+        // In local dev a provider's host setting (`.dev.vars`) adds its host,
+        // as the gateway's setting does there.
+        const hosts = binding
+            ? [...integration.hosts]
+            : apiKeyHosts(integration, values);
+        if (upstream.protocol !== "https:" || !hosts.includes(upstream.host)) {
+            throw new TypeError(`integrationFetch("${provider}") only reaches ${hosts.join(", ")}, not ${upstream.host}.`);
+        }
+        if (binding) {
+            applyAttribution(headers, target);
+            return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
+        }
+        applyAttribution(headers, undefined);
+        // The developer's own key, put where the provider's entry says, as the
+        // gateway would put its own.
+        const auth = local;
+        for (const [name, value] of Object.entries(auth.headers)) {
+            headers.set(name, value);
+        }
+        for (const [name, value] of Object.entries(auth.query)) {
+            upstream.searchParams.set(name, value);
+        }
+        return fetch(streamingRequest(upstream.toString(), outbound, headers));
+    };
+}
+/**
+ * The `.dev.vars` name of a held token for `provider` in local dev
+ * (`GOOGLE_WORKSPACE_ACCESS_TOKEN`, `GITHUB_ACCESS_TOKEN`): a token the
+ * developer obtained themselves, standing in for the connection the
+ * gateway would hold. Dev-only: the gateway never reads it.
+ */
+export function devAccessTokenName(provider) {
+    return `${providerSettingPrefix(provider)}ACCESS_TOKEN`;
+}
+/**
+ * An app's call to an OAuth provider's API in local dev, with no
+ * gateway: the gateway's held-token checks in its order (the app's
+ * declared sets, the method, the route), then the developer's own token
+ * from `.dev.vars` as the bearer, straight to the provider.
+ */
+async function devHeldTokenCall({ provider, capability, outbound, upstream, headers, values, }) {
+    const token = stringValue(values[devAccessTokenName(provider)]);
+    if (!token) {
+        return devRefusal(409, "integration_not_connected", `${capability.label} isn't connected here. In local dev, set ${devAccessTokenName(provider)} in .dev.vars to a token you obtained yourself; deployed, the person connects at /connect/${provider}.`, { connectPath: `/connect/${provider}`, reconnect: false });
+    }
+    const policy = capability.scopePolicy;
+    const grant = policy
+        ? devScopeSets(policy, provider, capability.label, values, "any")
+        : null;
+    if (grant && "problem" in grant) {
+        return devRefusal(403, grant.code, grant.problem);
+    }
+    const method = outbound.method.toUpperCase();
+    const reads = oauthReadMethods(capability).includes(method);
+    const writes = !reads &&
+        capability.access.includes("write") &&
+        oauthWriteMethods(capability).includes(method) &&
+        devDeclaredAccess(provider, values) === "write";
+    if (policy && grant) {
+        const allowed = heldTokenCallAllowed({
+            policy,
+            declaredSets: grant.sets,
+            // The developer's token stands for a connection granted every set.
+            connectionSets: grant.sets,
+            hosts: capability.api,
+            method,
+            upstream,
+            readMethods: oauthReadMethods(capability),
+            writes,
+        });
+        if (!allowed.ok) {
+            const status = {
+                integration_not_connected: 409,
+                integration_method_not_allowed: 405,
+                integration_scope_not_allowed: 403,
+            }[allowed.code];
+            return devRefusal(status, allowed.code, allowed.code === "integration_not_connected"
+                ? `${capability.label} is connected without ${allowed.missingSets.join(", ")}.`
+                : allowed.message);
+        }
+    }
+    else if (!reads && !writes) {
+        return devRefusal(405, "integration_method_not_allowed", `${capability.label} calls may use ${oauthReadMethods(capability).join(" or ")} with access: "read"; ${method} needs access: "write" in the app's capabilities entry, on a provider that offers it.`);
+    }
+    applyAttribution(headers, undefined);
+    headers.set("authorization", `Bearer ${token}`);
+    for (const name of ["access_token", "token"]) {
+        upstream.searchParams.delete(name);
+    }
+    headers.delete("x-http-method-override");
+    return fetch(new Request(upstream.toString(), {
+        method,
+        headers,
+        body: method === "GET" || method === "HEAD" ? null : outbound.body,
+        signal: outbound.signal,
+        // As the gateway: the token never follows a redirect.
+        redirect: "manual",
+        ...(method === "GET" || method === "HEAD" ? {} : { duplex: "half" }),
+    }));
+}
+/** The `access` the manifest entry for `provider` declares in dev (EVERYAPP_DEV_CAPABILITIES), or null. */
+function devDeclaredAccess(provider, values) {
+    const raw = values["EVERYAPP_DEV_CAPABILITIES"];
+    try {
+        const capabilities = typeof raw === "string" ? jsonRecord(JSON.parse(raw)) : undefined;
+        const entry = jsonRecord(capabilities?.[provider]);
+        return typeof entry?.["access"] === "string" ? entry["access"] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The developer's own key or client from `.dev.vars` (with EVERYAPP_DEV
+ * set), under the gateway's names; null until every setting it needs is.
+ */
+function localCredentials(integration, values) {
+    if (!values["EVERYAPP_DEV"])
+        return null;
+    if (integration.mode === "oauth_client") {
+        return oauthClientCredentials(integration, values);
+    }
+    return authorizationFor(integration, values);
+}
+/**
+ * A call to an OAuth client's token endpoint: over the binding, where the
+ * gateway puts its client on it, or in local dev straight to the provider
+ * with the developer's client put on it by the gateway's own rule.
+ */
+async function oauthClientCall({ provider, capability, outbound, upstream, headers, values, binding, target, client, }) {
+    const endpoint = tokenEndpointFor(capability, upstream);
+    const method = outbound.method.toUpperCase();
+    if (!endpoint || !endpoint.methods.includes(method)) {
+        throw new TypeError(`integrationFetch("${provider}") only reaches ${capability.label}'s token endpoints (${describeTokenEndpoints(capability)}), not ${method} ${upstream.origin}${upstream.pathname}. Call its API with the user's token directly.`);
+    }
+    if (binding) {
+        applyAttribution(headers, target);
+        return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
+    }
+    applyAttribution(headers, undefined);
+    if (!client) {
+        throw new ConfigurationError(`${capability.label}'s token endpoints need the client in .dev.vars for local development: set ${capabilitySettings(capability).join(", ")}.`);
+    }
+    // The gateway's scope checks, in its order, answering its refusals: an
+    // app sees in `everyapp dev` what the gateway will say.
+    const policy = capability.scopePolicy;
+    const grant = policy
+        ? devScopeSets(policy, provider, capability.label, values)
+        : null;
+    if (grant && "problem" in grant) {
+        return devRefusal(403, grant.code, grant.problem);
+    }
+    const sets = grant?.sets;
+    const body = method === "GET" ? null : await outbound.text();
+    if (body !== null &&
+        new TextEncoder().encode(body).byteLength > OAUTH_TOKEN_BODY_LIMIT) {
+        throw new TypeError(`A token request's body is at most ${OAUTH_TOKEN_BODY_LIMIT / 1024} KiB.`);
+    }
+    if (policy &&
+        ["grant_type", "scope", "user_scope"].some((name) => upstream.searchParams.has(name))) {
+        return devRefusal(400, "integration_body_invalid", "Put grant_type, scope and user_scope in the token request's body, not its query string; the gateway decides on the body.");
+    }
+    let injected = injectClientCredentials({ url: upstream, headers, body }, endpoint, client);
+    if (!injected.ok)
+        throw new TypeError(injected.problem);
+    if (policy && sets) {
+        const refused = refuseTokenRequest(policy, capability, sets, injected);
+        if (refused)
+            return refused;
+        injected = {
+            ok: true,
+            ...rewriteTokenRequestScope(policy, sets, injected),
+        };
+    }
+    const response = await fetch(new Request(injected.url, {
+        method,
+        headers: injected.headers,
+        body: injected.body,
+        signal: outbound.signal,
+        // As the gateway: the client never follows a redirect.
+        redirect: "manual",
+    }));
+    if (!policy || !sets || !response.ok)
+        return response;
+    return checkTokenResponse(policy, capability, sets, response);
+}
+/**
+ * The gateway's refusal shape (`{ error, code, message }`, the code in
+ * `x-everyapp-error`) from the local-dev twin, so {@link gatewayRefusal}
+ * reads it the same way.
+ */
+function devRefusal(status, code, message, extra = {}) {
+    const labels = {
+        400: "Bad Request",
+        403: "Forbidden",
+        405: "Method Not Allowed",
+        409: "Conflict",
+        502: "Bad Gateway",
+    };
+    return Response.json({ error: labels[status] ?? "Error", code, message, ...extra }, { status, headers: { [GATEWAY_ERROR_HEADER]: code } });
+}
+/**
+ * The scope sets the manifest declares for `id`, read from
+ * EVERYAPP_DEV_CAPABILITIES (the manifest's `capabilities` as JSON, which
+ * `everyAppWorker()` writes in dev), or the gateway's refusal, in its
+ * order: the client not listed for writing (`capability_not_requested`),
+ * then a void grant (`integration_scopes_undeclared`: the variable
+ * missing, the entry without usable `scopes`, or a set this registry
+ * doesn't offer). Fails closed like the gateway: a hand-rolled dev harness
+ * that passes no capabilities gets nothing.
+ */
+function devScopeSets(policy, id, label, values, 
+/** The grant the entry needs: `write` for a token-endpoint call (the app-driven flow), `any` for a held-token call. */
+grant = "write") {
+    const offered = Object.keys(policy.sets).join(", ");
+    const raw = values["EVERYAPP_DEV_CAPABILITIES"];
+    let capabilities;
+    try {
+        capabilities =
+            typeof raw === "string" ? jsonRecord(JSON.parse(raw)) : undefined;
+    }
+    catch {
+        capabilities = undefined;
+    }
+    if (!capabilities) {
+        return {
+            code: "integration_scopes_undeclared",
+            problem: `${label}'s scope sets aren't known here: everyapp dev passes the manifest's capabilities to the Worker as EVERYAPP_DEV_CAPABILITIES when everyapp.config.ts builds it with everyAppWorker() from @every-app/sdk/cloudflare.`,
+        };
+    }
+    const entry = Object.hasOwn(capabilities, id)
+        ? jsonRecord(capabilities[id])
+        : undefined;
+    // The gateway's check 2: listing the client for writing is the grant
+    // of the app-driven flow; a held-token call takes any listing.
+    const access = entry?.["access"];
+    if (!entry ||
+        (grant === "write"
+            ? access !== "write"
+            : access !== "read" && access !== "write")) {
+        return {
+            code: "capability_not_requested",
+            problem: `This app doesn't list ${label} in its capabilities. Add capabilities: { ${JSON.stringify(id)}: { access: "${grant === "write" ? "write" : "read"}" } } to everyapp.config.ts and start everyapp dev again.`,
+        };
+    }
+    const sets = declaredScopeSets(policy, entry);
+    if (sets)
+        return { sets };
+    const listed = entry["scopes"];
+    const unknown = Array.isArray(listed)
+        ? listed.filter((name) => typeof name === "string" && !Object.hasOwn(policy.sets, name))
+        : [];
+    if (unknown.length > 0) {
+        return {
+            code: "integration_scopes_undeclared",
+            problem: `This app's ${label} entry names scope sets this SDK doesn't offer: ${unknown.join(", ")}. It offers: ${offered}. Fix everyapp.config.ts and start everyapp dev again, or update @every-app/sdk if it is older than the set.`,
+        };
+    }
+    return {
+        code: "integration_scopes_undeclared",
+        problem: `This app lists ${label} without the scope sets it uses. Add scopes: [...] (one or more of: ${offered}) to its ${JSON.stringify(id)} entry in everyapp.config.ts and start everyapp dev again.`,
+    };
+}
+function jsonRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * The gateway's checks on a token request before it goes out: the grant
+ * type must be one the policy completes, and a `scope` the body names must
+ * stay within the sets. Null when the request may go.
+ */
+function refuseTokenRequest(policy, capability, sets, request) {
+    const grantType = tokenGrantType(request);
+    if (!policy.grantTypes.includes(grantType)) {
+        const completes = policy.grantTypes.map((type) => type === null ? "a code exchange without grant_type" : type);
+        const asked = grantType === null
+            ? "a request without grant_type"
+            : grantType === "other"
+                ? "this request's grant_type"
+                : grantType;
+        return devRefusal(403, "integration_grant_not_allowed", `Through the gateway, ${capability.label} completes ${completes.join(" and ")} grants only; ${asked} isn't one of them. An app never gets app-level tokens with the operator's client.`);
+    }
+    const asked = requestedTokenScopes(policy, request);
+    const excess = asked ? scopeExcess(asked, allowedScopes(policy, sets)) : [];
+    if (excess.length > 0) {
+        return devRefusal(403, "integration_scope_not_allowed", `This app may ask ${capability.label} for ${sets.join(", ")} (${requestedScopes(policy, sets).scopes.join(", ")}); the request also asks ${excess.join(", ")}. Build the authorize URL and the token request from integrationStatus().scopes.`);
+    }
+    return null;
+}
+/**
+ * The gateway's check on a provider's 2xx answer: a token it carries must
+ * name scopes, and those must stay within the sets; on a refusal the
+ * answer is dropped, never forwarded, so no app holds a token outside its
+ * grant. An answer without a token (Slack's `ok: false`) is the app's to
+ * read. A non-2xx answer never reaches here.
+ */
+async function checkTokenResponse(policy, capability, sets, response) {
+    const invalid = () => devRefusal(502, "integration_response_invalid", `${capability.label} answered with something that isn't a token response (over ${OAUTH_TOKEN_BODY_LIMIT / 1024} KiB or not a JSON object); nothing was passed on.`);
+    const bytes = await response.arrayBuffer();
+    if (bytes.byteLength > OAUTH_TOKEN_BODY_LIMIT)
+        return invalid();
+    const text = new TextDecoder().decode(bytes);
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return invalid();
+    }
+    if (!json || typeof json !== "object" || Array.isArray(json)) {
+        return invalid();
+    }
+    // The body was decoded on read: its length and encoding headers no
+    // longer describe it.
+    const headers = new Headers(response.headers);
+    for (const name of [
+        "set-cookie",
+        "content-length",
+        "content-encoding",
+        "transfer-encoding",
+    ]) {
+        headers.delete(name);
+    }
+    const forward = () => new Response(text, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+    if (!carriesToken(json))
+        return forward();
+    const granted = grantedScopes(policy, json);
+    if (!granted) {
+        return devRefusal(502, "integration_scope_unverified", `${capability.label} issued a token without saying which scopes it carries, so the gateway can't hold it to this app's scope sets; nothing was passed on. Ask the person to connect again.`);
+    }
+    const excess = scopeExcess(granted, allowedScopes(policy, sets));
+    if (excess.length > 0) {
+        const remedy = {
+            google: "Ask for only the scopes integrationStatus() returns, without include_granted_scopes, and connect again; if the app needs more, add the scope set to everyapp.config.ts and deploy.",
+            microsoft: "On a shared Microsoft client a token carries everything the person consented to this client: have them remove this app's consent at https://myapplications.microsoft.com and connect again, or add the scope set to everyapp.config.ts and deploy.",
+            slack: "Slack scopes add up per workspace installation: reinstall the app in the workspace with only the status's scopes, or add the scope set to everyapp.config.ts and deploy.",
+            space: "Ask for only the scopes integrationStatus() returns and connect again, or add the scope set to everyapp.config.ts and deploy.",
+            comma: "Ask for only the scopes integrationStatus() returns and connect again, or add the scope set to everyapp.config.ts and deploy.",
+        }[policy.dialect];
+        return devRefusal(403, "integration_scope_exceeded", `${capability.label} granted scopes this app doesn't declare: ${excess.join(", ")}. It declares ${sets.join(", ")} (${requestedScopes(policy, sets).scopes.join(", ")}). Nothing was passed on. ${remedy}`);
+    }
+    return forward();
+}
+/**
+ * A provider outside the catalog in local dev (no binding): the gateway
+ * row's spec from EVERYAPP_DEV_PROVIDERS (`.everyapp/providers/<id>.json`,
+ * which `everyAppWorker()` reads in dev), or a ConfigurationError naming
+ * the file that doesn't parse, or the command that writes one.
+ */
+function devRegisteredProvider(provider, values) {
+    if (!values["EVERYAPP_DEV"]) {
+        throw new ConfigurationError(`"${provider}" isn't in the built-in provider catalog. A provider registered on the gateway (everyapp provider add) is reached through the EVERY_APP_GATEWAY binding, or in everyapp dev from ${devProviderFile(provider)}.`);
+    }
+    const resolved = resolveDevProvider(values, provider);
+    if (!resolved.found)
+        throw new ConfigurationError(resolved.problem);
+    if (resolved.capability.mode === "ai") {
+        throw new ConfigurationError(`${provider} is an AI provider: list it under providers and call it with createGatewayFetch(), not integrationFetch().`);
+    }
+    return resolved.capability;
+}
+/**
+ * The provider `integrationFetch()` calls: one whose key or OAuth client
+ * the gateway holds, or undefined for an id outside the built-in catalog
+ * (a provider registered on the gateway, which the binding resolves).
+ */
+function fetchableCapability(provider) {
+    const found = CATALOG.get(String(provider));
+    if (!found)
+        return undefined;
+    if (found.mode === "service") {
+        throw new ConfigurationError(`${String(provider)} is a gateway service: call its helper from @every-app/sdk/server (sendEmail(), listMembers()), not integrationFetch().`);
+    }
+    if (found.mode === "ai") {
+        throw new ConfigurationError(`${String(provider)} is an AI provider: list it under providers and call it with createGatewayFetch(), not integrationFetch().`);
+    }
+    return found;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * Whether the app can use an integration right now, without calling the
+ * provider: show "an admin needs to set up DataForSEO" (or "sending isn't
+ * set up") up front instead of failing mid-task. An OAuth client's status
+ * carries its public `clientId` for the authorize URL.
+ */
+export async function integrationStatus({ env, provider, for: explicitTarget, }) {
+    const status = await readIntegrationStatus({
+        env,
+        provider,
+        ...(explicitTarget === undefined ? {} : { for: explicitTarget }),
+    });
+    return withSetup(status, String(provider), env);
+}
+/**
+ * `status` with its setup fields: the Gateway's as it sent them, or in
+ * local development (no binding) the `.dev.vars` names a status that
+ * isn't configured lacks.
+ */
+function withSetup(status, provider, values) {
+    const binding = gatewayBinding(values);
+    if (binding || !status.requested || status.configured) {
+        return {
+            ...status,
+            settings: Array.isArray(status.settings) ? status.settings : [],
+            setup: typeof status.setup === "string" ? status.setup : null,
+            command: typeof status.command === "string" ? status.command : null,
+        };
+    }
+    const integration = CATALOG.get(provider) ?? devRegisteredProvider(provider, values);
+    const settings = provider === "email"
+        ? ["EMAIL_FROM"]
+        : integration
+            ? [...capabilitySettings(integration)]
+            : [];
+    return {
+        ...status,
+        settings,
+        setup: settings.length
+            ? `${integration?.label ?? provider} isn't set up for local development: set ${settings.join(" and ")} in .dev.vars.`
+            : `${integration?.label ?? provider} isn't set up for local development.`,
+        command: null,
+    };
+}
+async function readIntegrationStatus({ env, provider, for: explicitTarget, }) {
+    const target = attributionFor(env, explicitTarget, `integrationStatus("${String(provider)}")`);
+    const values = env;
+    const binding = gatewayBinding(env);
+    // A provider registered on the gateway is the gateway's to answer for;
+    // without one, the catalog, or in local dev the row's spec from
+    // `.everyapp/providers/<id>.json`.
+    const integration = binding && typeof binding.fetch === "function"
+        ? CATALOG.get(String(provider))
+        : (CATALOG.get(String(provider)) ??
+            devRegisteredProvider(String(provider), values));
+    if (integration?.mode === "ai") {
+        throw new ConfigurationError(`${String(provider)} is an AI provider: it has no integration status (createGatewayFetch() answers ai_provider_not_configured when its key is unset).`);
+    }
+    const unavailable = () => (provider === "email"
+        ? {
+            requested: false,
+            configured: false,
+            ready: false,
+            sender: null,
+            senders: [],
+            provider: null,
+        }
+        : {
+            requested: false,
+            configured: false,
+            ready: false,
+        });
+    if (binding && typeof binding.fetch === "function") {
+        const statusUrl = `${BINDING_ORIGIN}${INTEGRATION_PROXY_PREFIX}/${provider}`;
+        let response;
+        if (target === undefined) {
+            response = await binding.fetch(statusUrl);
+        }
+        else {
+            // Whose status: the person's identity (their OAuth connection) or the
+            // organization's, as a call would carry it.
+            const headers = new Headers();
+            applyAttribution(headers, target);
+            response = await binding.fetch(statusUrl, { headers });
+        }
+        if (!response.ok)
+            return unavailable();
+        return (await response.json());
+    }
+    if (!integration)
+        return unavailable();
+    if (integration.mode === "service") {
+        if (provider === "email") {
+            return devEmailStatus(values);
+        }
+        // Members: listMembers() answers from the dev identity, nothing to set.
+        const dev = Boolean(values["EVERYAPP_DEV"]);
+        return {
+            requested: true,
+            configured: dev,
+            ready: dev,
+        };
+    }
+    if (integration.mode === "oauth_client") {
+        return devOAuthClientStatus(provider, integration, values);
+    }
+    const configured = Boolean(values["EVERYAPP_DEV"] && authorizationFor(integration, values));
+    return {
+        requested: true,
+        configured,
+        ready: configured,
+    };
+}
+/**
+ * An OAuth client in local dev, with no gateway: the developer's own, from
+ * `.dev.vars`, and for a client with scope sets the manifest's, from
+ * EVERYAPP_DEV_CAPABILITIES, shaped as the gateway's status is: an app
+ * that doesn't list the client is told nothing, and a void grant is not
+ * ready and hides the client id.
+ */
+function devOAuthClientStatus(id, capability, values) {
+    const client = values["EVERYAPP_DEV"]
+        ? oauthClientCredentials(capability, values)
+        : null;
+    const policy = capability.scopePolicy;
+    // An entry with a Gateway-owned flow is listed for reading or writing;
+    // the app-driven flow alone needs the write grant.
+    const grant = policy
+        ? devScopeSets(policy, id, capability.label, values, capability.flow ? "any" : "write")
+        : null;
+    // The Gateway-owned flow's fields, in dev: a token in `.dev.vars`
+    // stands for a connection granted every declared set.
+    const flow = capability.flow ? "both" : "app";
+    const devToken = capability.flow
+        ? stringValue(values[devAccessTokenName(id)])
+        : undefined;
+    const gateway = (sets) => capability.flow
+        ? {
+            flow,
+            connectPath: `/connect/${id}`,
+            connection: devToken
+                ? {
+                    account: "user",
+                    label: devAccessTokenName(id),
+                    scopeSets: sets,
+                    ready: true,
+                }
+                : null,
+        }
+        : { flow };
+    if (grant && "problem" in grant) {
+        if (grant.code === "capability_not_requested") {
+            return { requested: false, configured: false, ready: false };
+        }
+        return {
+            requested: true,
+            configured: Boolean(client),
+            ready: false,
+            scopeSets: [],
+            ...gateway([]),
+        };
+    }
+    const asked = policy && grant ? requestedScopes(policy, grant.sets) : null;
+    return {
+        requested: true,
+        configured: Boolean(client),
+        ready: Boolean(client) || Boolean(devToken),
+        ...(client ? { clientId: client.clientId } : {}),
+        ...((client || devToken) && grant && asked
+            ? {
+                scopeSets: grant.sets,
+                scopes: asked.scopes,
+                ...(asked.userScopes.length > 0
+                    ? { userScopes: asked.userScopes }
+                    : {}),
+            }
+            : {}),
+        ...gateway(grant?.sets ?? []),
+    };
+}
+/**
+ * Email in local dev, with no gateway: sends are printed unless `.dev.vars`
+ * sets EMAIL_FROM (and the REST settings), and the senders are the ones
+ * `.dev.vars` sets as EVERYAPP_EMAIL_SENDERS, standing in for the
+ * installation's (`everyapp email set --sender`); unset, none. The
+ * provider is the one the gateway would pick from the same settings:
+ * `cloudflare` for the REST pair, `resend` for RESEND_API_KEY, EMAIL_PROVIDER
+ * choosing when both are set.
+ */
+function devEmailStatus(values) {
+    const dev = Boolean(values["EVERYAPP_DEV"]);
+    const configured = dev && Boolean(stringValue(values["EMAIL_FROM"]));
+    const choice = chooseEmailProvider(values["EMAIL_PROVIDER"], (provider) => (provider === "cloudflare"
+        ? stringValue(values["EMAIL_REST_API_TOKEN"]) &&
+            stringValue(values["CLOUDFLARE_ACCOUNT_ID"])
+        : stringValue(values["RESEND_API_KEY"]))
+        ? "settings"
+        : null);
+    return {
+        requested: true,
+        configured,
+        ready: configured,
+        sender: configured
+            ? parseEmailSender(stringValue(values["EMAIL_FROM"]), stringValue(values["EMAIL_FROM_NAME"]))
+            : null,
+        senders: dev ? parseEmailList(values[EMAIL_SENDERS_ENV]) : [],
+        provider: configured && choice.ok ? choice.provider : null,
+    };
+}