@zackbart/connecta 0.30.0 → 0.31.0

package/dist/providers/cloudflare/graphql.js

@@ -0,0 +1,385 @@
+// Read-only admission for Cloudflare's GraphQL Analytics API. A document is
+// tokenized by the GraphQL lexical grammar (strings, block strings, comments
+// and commas are skipped as the spec skips them) and its top-level
+// definitions are walked, so a `mutation` hidden in a string, a comment, or
+// after an anonymous query is still found, and anything that is not a query
+// or a fragment is refused. Nothing here does I/O.
+import { ConnectorCallError } from "../../errors.js";
+const SCOPED_FIELDS = new Set(["accounts", "zones"]);
+function refuse(message) {
+    throw new ConnectorCallError("invalid_args", message);
+}
+function tokenize(source) {
+    const tokens = [];
+    let at = 0;
+    const length = source.length;
+    while (at < length) {
+        const character = source[at];
+        if (character === " " || character === "\t" || character === "\n" || character === "\r" || character === ",") {
+            at += 1;
+            continue;
+        }
+        if (character === "") {
+            at += 1;
+            continue;
+        }
+        if (character === "#") {
+            while (at < length && source[at] !== "\n" && source[at] !== "\r")
+                at += 1;
+            continue;
+        }
+        if (source.startsWith("...", at)) {
+            tokens.push({ kind: "punct", value: "..." });
+            at += 3;
+            continue;
+        }
+        if ("!$&()[]{}:=@|".includes(character)) {
+            tokens.push({ kind: "punct", value: character });
+            at += 1;
+            continue;
+        }
+        if (/[_A-Za-z]/.test(character)) {
+            const start = at;
+            while (at < length && /[_0-9A-Za-z]/.test(source[at]))
+                at += 1;
+            tokens.push({ kind: "name", value: source.slice(start, at) });
+            continue;
+        }
+        if (character === "-" || /[0-9]/.test(character)) {
+            const match = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(source.slice(at));
+            if (!match)
+                refuse("The GraphQL document has a malformed number.");
+            tokens.push({ kind: "number", value: match[0] });
+            at += match[0].length;
+            continue;
+        }
+        if (source.startsWith('"""', at)) {
+            let end = at + 3;
+            let text = "";
+            for (;;) {
+                if (end >= length)
+                    refuse("The GraphQL document has an unterminated block string.");
+                if (source.startsWith('\\"""', end)) {
+                    text += '"""';
+                    end += 4;
+                    continue;
+                }
+                if (source.startsWith('"""', end))
+                    break;
+                text += source[end];
+                end += 1;
+            }
+            tokens.push({ kind: "string", value: text });
+            at = end + 3;
+            continue;
+        }
+        if (character === '"') {
+            let end = at + 1;
+            let text = "";
+            for (;;) {
+                const next = source[end];
+                if (next === undefined || next === "\n" || next === "\r")
+                    refuse("The GraphQL document has an unterminated string.");
+                if (next === '"')
+                    break;
+                if (next === "\\") {
+                    const escape = source[end + 1];
+                    if (escape === "u") {
+                        const hex = source.slice(end + 2, end + 6);
+                        if (!/^[0-9A-Fa-f]{4}$/.test(hex))
+                            refuse("The GraphQL document has a malformed string escape.");
+                        text += String.fromCharCode(parseInt(hex, 16));
+                        end += 6;
+                        continue;
+                    }
+                    const simple = {
+                        '"': '"',
+                        "\\": "\\",
+                        "/": "/",
+                        b: "\b",
+                        f: "\f",
+                        n: "\n",
+                        r: "\r",
+                        t: "\t",
+                    };
+                    if (escape === undefined || !(escape in simple))
+                        refuse("The GraphQL document has a malformed string escape.");
+                    text += simple[escape];
+                    end += 2;
+                    continue;
+                }
+                text += next;
+                end += 1;
+            }
+            tokens.push({ kind: "string", value: text });
+            at = end + 1;
+            continue;
+        }
+        refuse(`The GraphQL document has an unexpected character at offset ${at}.`);
+    }
+    return tokens;
+}
+const OPENERS = { "(": ")", "[": "]", "{": "}" };
+/**
+ * Refuse anything but queries and fragments, and report the account and zone
+ * tags the document names. `variables` resolves `$name` tag values.
+ */
+export function inspectGraphqlQuery(source, variables, options = {}) {
+    const tokens = tokenize(source);
+    if (tokens.length === 0)
+        refuse("The GraphQL document is empty.");
+    let index = 0;
+    let operations = 0;
+    // Skip one balanced group starting at `index` (an opener); returns the index after its closer.
+    const skipGroup = (start) => {
+        const stack = [];
+        for (let at = start; at < tokens.length; at += 1) {
+            const token = tokens[at];
+            if (token.kind !== "punct")
+                continue;
+            if (OPENERS[token.value])
+                stack.push(OPENERS[token.value]);
+            else if (token.value === ")" || token.value === "]" || token.value === "}") {
+                if (stack.pop() !== token.value)
+                    refuse("The GraphQL document has unbalanced brackets.");
+                if (stack.length === 0)
+                    return at + 1;
+            }
+        }
+        return refuse("The GraphQL document has unbalanced brackets.");
+    };
+    // From a definition keyword, consume the header (name, variables,
+    // directives) and its selection set.
+    const skipDefinition = (start) => {
+        for (let at = start; at < tokens.length; at += 1) {
+            const token = tokens[at];
+            if (token.kind !== "punct")
+                continue;
+            if (token.value === "{")
+                return skipGroup(at);
+            if (token.value === "(" || token.value === "[")
+                at = skipGroup(at) - 1;
+            else if (token.value === "}" || token.value === ")" || token.value === "]") {
+                refuse("The GraphQL document has unbalanced brackets.");
+            }
+        }
+        return refuse("A GraphQL definition has no selection set.");
+    };
+    // Each top-level definition's token range, for the strict checks below.
+    const definitions = [];
+    const nameAfter = (at) => {
+        const token = tokens[at];
+        return token?.kind === "name" ? token.value : undefined;
+    };
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token.kind === "punct" && token.value === "{") {
+            operations += 1;
+            const end = skipGroup(index);
+            definitions.push({ kind: "query", name: undefined, start: index, end });
+            index = end;
+            continue;
+        }
+        if (token.kind === "name" && token.value === "query") {
+            operations += 1;
+            const end = skipDefinition(index + 1);
+            definitions.push({ kind: "query", name: nameAfter(index + 1), start: index, end });
+            index = end;
+            continue;
+        }
+        if (token.kind === "name" && token.value === "fragment") {
+            const end = skipDefinition(index + 1);
+            definitions.push({ kind: "fragment", name: nameAfter(index + 1), start: index, end });
+            index = end;
+            continue;
+        }
+        if (token.kind === "name" && (token.value === "mutation" || token.value === "subscription")) {
+            refuse(`graphql_query runs read-only queries; this document contains a ${token.value}, which it never sends.`);
+        }
+        refuse("graphql_query accepts only query operations and fragments.");
+    }
+    if (operations === 0)
+        refuse("The GraphQL document has no query operation.");
+    if (options.strict) {
+        // One operation, so every variable default belongs to the query that
+        // runs; and every fragment reachable from it, defined, used, and acyclic,
+        // so the fields checked below are exactly the fields that execute.
+        if (operations !== 1)
+            refuse("A pinned connector sends one query operation per GraphQL document.");
+        const operation = definitions.find((definition) => definition.kind === "query");
+        if (options.operationName !== undefined && options.operationName !== operation.name) {
+            refuse(`operationName ${options.operationName} names no query in this document.`);
+        }
+        const fragments = new Map();
+        for (const definition of definitions) {
+            if (definition.kind !== "fragment")
+                continue;
+            if (!definition.name || definition.name === "on" || fragments.has(definition.name)) {
+                refuse("A GraphQL fragment must have one unique name.");
+            }
+            fragments.set(definition.name, definition);
+        }
+        const spreads = (range) => {
+            const names = [];
+            for (let at = range.start; at < range.end; at += 1) {
+                if (tokens[at].value === "..." && tokens[at + 1]?.kind === "name" && tokens[at + 1].value !== "on") {
+                    names.push(tokens[at + 1].value);
+                }
+            }
+            return names;
+        };
+        const used = new Set();
+        const visit = (range, path) => {
+            for (const name of spreads(range)) {
+                const fragment = fragments.get(name);
+                if (!fragment)
+                    refuse(`The GraphQL document spreads an undefined fragment ${name}.`);
+                if (path.includes(name))
+                    refuse(`The GraphQL fragment ${name} spreads itself.`);
+                used.add(name);
+                visit(fragment, [...path, name]);
+            }
+        };
+        visit(operation, []);
+        const unused = [...fragments.keys()].filter((name) => !used.has(name));
+        if (unused.length > 0)
+            refuse(`The GraphQL document defines unused fragments: ${unused.join(", ")}.`);
+    }
+    const accountTags = [];
+    const zoneTags = [];
+    const openTags = [];
+    const unscopedFields = [];
+    const UNRESOLVED = Symbol("unresolved");
+    // Variable declarations (`$zoneTag: String! = "…"`) are not filters; record
+    // their defaults so a variable resolves as the server would resolve it.
+    const defaults = new Map();
+    const declared = new Set();
+    const resolveVariable = (name) => Object.hasOwn(variables, name) ? variables[name] : defaults.has(name) ? defaults.get(name) : UNRESOLVED;
+    /** Parse one GraphQL input value at `at`, resolving variables; returns the value and the index after it. */
+    const parseValue = (at) => {
+        const token = tokens[at];
+        if (token === undefined)
+            return { value: UNRESOLVED, end: at };
+        if (token.kind === "string")
+            return { value: token.value, end: at + 1 };
+        if (token.kind === "number")
+            return { value: Number(token.value), end: at + 1 };
+        if (token.kind === "name") {
+            const literal = { true: true, false: false, null: null };
+            return { value: Object.hasOwn(literal, token.value) ? literal[token.value] : { enum: token.value }, end: at + 1 };
+        }
+        if (token.value === "$" && tokens[at + 1]?.kind === "name") {
+            return { value: resolveVariable(tokens[at + 1].value), end: at + 2 };
+        }
+        if (token.value === "[") {
+            const items = [];
+            let next = at + 1;
+            while (next < tokens.length && tokens[next].value !== "]") {
+                const item = parseValue(next);
+                if (item.end === next)
+                    return { value: UNRESOLVED, end: skipGroup(at) };
+                items.push(item.value);
+                next = item.end;
+            }
+            return { value: items, end: next + 1 };
+        }
+        if (token.value === "{") {
+            const object = {};
+            let next = at + 1;
+            while (next < tokens.length && tokens[next].value !== "}") {
+                const key = tokens[next];
+                if (key?.kind !== "name" || tokens[next + 1]?.value !== ":")
+                    return { value: UNRESOLVED, end: skipGroup(at) };
+                const item = parseValue(next + 2);
+                if (item.end === next + 2)
+                    return { value: UNRESOLVED, end: skipGroup(at) };
+                object[key.value] = item.value;
+                next = item.end;
+            }
+            return { value: object, end: next + 1 };
+        }
+        return { value: UNRESOLVED, end: at };
+    };
+    for (let at = 0; at + 2 < tokens.length; at += 1) {
+        const [dollar, name, colon] = [tokens[at], tokens[at + 1], tokens[at + 2]];
+        if (dollar.value !== "$" || name.kind !== "name" || colon.value !== ":")
+            continue;
+        declared.add(at + 1);
+        for (let scan = at + 3; scan < tokens.length; scan += 1) {
+            const token = tokens[scan];
+            if (token.kind === "punct" && (token.value === "$" || token.value === ")"))
+                break;
+            if (token.kind === "punct" && token.value === "=") {
+                const parsed = parseValue(scan + 1);
+                if (parsed.value !== UNRESOLVED)
+                    defaults.set(name.value, parsed.value);
+                break;
+            }
+        }
+    }
+    /**
+     * Validate one `zones` or `accounts` field's resolved `filter`: an object
+     * whose only keys are the tag equality or `_in`, with string values. Each
+     * field is checked on its own, so a valid alias cannot carry an unpinned one.
+     */
+    const checkField = (field, filter) => {
+        const prefix = field === "zones" ? "zone" : "account";
+        if (filter === UNRESOLVED || typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+            unscopedFields.push(field);
+            return;
+        }
+        const target = prefix === "zone" ? zoneTags : accountTags;
+        let tagged = false;
+        for (const [key, value] of Object.entries(filter)) {
+            if (key === `${prefix}Tag` && typeof value === "string") {
+                target.push(value);
+                tagged = true;
+            }
+            else if (key === `${prefix}Tag_in` &&
+                Array.isArray(value) &&
+                value.length > 0 &&
+                value.every((item) => typeof item === "string")) {
+                target.push(...value);
+                tagged = true;
+            }
+            else {
+                openTags.push(`${field}.${key}`);
+            }
+        }
+        if (!tagged)
+            unscopedFields.push(field);
+    };
+    for (let at = 0; at < tokens.length; at += 1) {
+        const token = tokens[at];
+        if (token.kind !== "name" || !SCOPED_FIELDS.has(token.value) || declared.has(at))
+            continue;
+        const previous = tokens[at - 1]?.value;
+        const next = tokens[at + 1];
+        if (previous === "$" || previous === "on" || previous === "...")
+            continue;
+        // `zones: accounts(…)` aliases, and object keys inside arguments.
+        if (next?.kind === "punct" && next.value === ":")
+            continue;
+        if (next?.kind !== "punct" || next.value !== "(") {
+            unscopedFields.push(token.value);
+            continue;
+        }
+        let filter = UNRESOLVED;
+        let cursor = at + 2;
+        while (cursor < tokens.length && tokens[cursor].value !== ")") {
+            const key = tokens[cursor];
+            if (key?.kind !== "name" || tokens[cursor + 1]?.value !== ":") {
+                filter = UNRESOLVED;
+                break;
+            }
+            const parsed = parseValue(cursor + 2);
+            if (parsed.end === cursor + 2)
+                break;
+            if (key.value === "filter")
+                filter = parsed.value;
+            cursor = parsed.end;
+        }
+        checkField(token.value, filter);
+    }
+    return { accountTags, zoneTags, openTags, unscopedFields };
+}

package/dist/providers/cloudflare/index.d.ts

@@ -1,29 +1,11 @@
-import { type RemoteMcpAuth } from "../../connectors/remote-mcp.js";
-import type { ConnectorCallAdmissionPolicy, ConnectorCredentialConfig } from "../../types.js";
-/** Cloudflare's v4 REST base. Override only for a proxy or a test double. */
-export declare const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
+import type { ConnectorCallAdmissionPolicy } from "../../types.js";
+import { type CloudflarePin } from "./rest.js";
+export { CLOUDFLARE_API_BASE } from "./rest.js";
+export type { CloudflarePin } from "./rest.js";
 /** Cloudflare's official whole-API hosted MCP endpoint. */
 export declare const CLOUDFLARE_MCP_ENDPOINT = "https://mcp.cloudflare.com/mcp";
-/** Authentication schemes accepted by Cloudflare's v4 API. */
-export type CloudflareAuthentication = "apiToken" | "globalApiKey";
-/**
- * The 21 record types Cloudflare accepts. Eight carry a single `content`
- * string; the other thirteen carry a per-type structured `data` object.
- * `list_dns_records` filters on all 21 because reading them costs nothing.
- */
-export declare const CLOUDFLARE_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CAA", "CERT", "CNAME", "DNSKEY", "DS", "HTTPS", "LOC", "MX", "NAPTR", "NS", "OPENPGPKEY", "PTR", "SMIMEA", "SRV", "SSHFP", "SVCB", "TLSA", "TXT", "URI"];
-/**
- * Content-valued types only, and the only types `create_dns_record` and
- * `update_dns_record` accept. Covering the thirteen structured-`data` types
- * would mean either a free-form `data` passthrough — the untyped body this
- * connection exists to avoid — or thirteen more hand-written schemas for record
- * types that are rare in day-to-day zone administration. They stay fully
- * readable; writing one goes through the approval-gated raw mutation tool with
- * Cloudflare's documented per-type `data` body.
- */
-export declare const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CNAME", "MX", "NS", "OPENPGPKEY", "PTR", "TXT"];
 interface CloudflareCommonOptions {
-    /** Human-readable display name; defaults identify the selected interface. */
+    /** Human-readable display name; defaults identify the implementation. */
     title?: string;
     /** Downstream auth ownership. Defaults to one shared deployment grant. */
     authScope?: "shared" | "personal";
@@ -34,44 +16,58 @@ interface CloudflareCommonOptions {
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
 }
-export interface CloudflareApiOptions extends CloudflareCommonOptions {
-    /** Select the REST complement explicitly; hosted MCP is the default. */
-    surface: "api";
+/** Cloudflare's hosted MCP server (`search` and `execute`) over OAuth. */
+export interface CloudflareOAuthOptions extends CloudflareCommonOptions {
+    auth: {
+        type: "oauth";
+    };
+    /** Optional per-runtime downstream call-admission policy. */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+}
+interface CloudflareKeyOptions extends CloudflareCommonOptions {
     /**
-     * Default account id for account-scoped tools. When set, `accountId` becomes
-     * an optional argument; when omitted, agents must pass one and can find it
-     * with `list_accounts`.
+     * Default account id: fills `{account_id}` in paths and verifies an
+     * account-owned token. Routing only; `pin` is the boundary.
      */
     accountId?: string;
-    /**
-     * Default zone id for zone-scoped tools. When set, `zoneId` becomes an
-     * optional argument; when omitted, agents must pass one and can find it with
-     * `list_zones`.
-     */
+    /** Default zone id: fills `{zone_id}` in paths. Routing only; `pin` is the boundary. */
     zoneId?: string;
     /** API base override for a proxy or a test double. Defaults to the v4 API. */
     baseUrl?: string;
-    /** Authentication scheme. Defaults to the recommended scoped API token. */
-    authentication?: CloudflareAuthentication;
-    /** Credential presentation override; credentials are always operator-managed. */
-    credential?: ConnectorCredentialConfig;
     /** Simultaneous downstream calls. Defaults to 6. */
     maxConcurrency?: number;
 }
-export interface CloudflareMcpOptions extends CloudflareCommonOptions {
-    surface?: "mcp";
-    /** OAuth by default, or a scoped API token for a headless deployment. */
-    auth?: RemoteMcpAuth;
-    /** Optional per-runtime downstream call-admission policy. */
-    callAdmission?: ConnectorCallAdmissionPolicy;
+/**
+ * Connecta's REST connector with one operator-managed, scoped API token. A
+ * `pin` restricts it further to named accounts and zones.
+ */
+export interface CloudflareApiTokenOptions extends CloudflareKeyOptions {
+    auth: {
+        type: "apiToken";
+    };
+    /** Accounts and zones this connector may touch, enforced on every call. */
+    pin?: CloudflarePin;
 }
-/** Backward-compatible API options; existing consumers may extend this interface. */
-export interface CloudflareOptions extends CloudflareApiOptions {
+/**
+ * Connecta's REST connector with a legacy Global API Key and its user's
+ * email. The key acts as the user everywhere, so the connector requires a
+ * `pin` unless `unpinned: true` states the whole estate is intended.
+ */
+export interface CloudflareGlobalApiKeyOptions extends CloudflareKeyOptions {
+    auth: {
+        type: "globalApiKey";
+    };
+    /** Accounts and zones this connector may touch; required unless `unpinned`. */
+    pin?: CloudflarePin;
+    /** Accept every account and zone the key's user can reach. */
+    unpinned?: true;
 }
-/** Select one Cloudflare interface when deployment configuration constructs it. */
-export type CloudflareConnectionOptions = CloudflareOptions | CloudflareMcpOptions;
-/** A maintained Cloudflare connection using the selected provider interface. */
-export declare const cloudflare: import("../../provider.js").ProviderFactory<CloudflareConnectionOptions>;
+export type CloudflareOptions = CloudflareOAuthOptions | CloudflareApiTokenOptions | CloudflareGlobalApiKeyOptions;
+/**
+ * A maintained Cloudflare connection. `auth` selects the implementation:
+ * OAuth reaches Cloudflare's hosted MCP server; an API token or a Global API
+ * Key reaches Connecta's REST connector to the v4 API.
+ */
+export declare const cloudflare: import("../../provider.js").ProviderFactory<CloudflareOptions>;
 /** @deprecated Read `cloudflare.definition.classify` instead. Kept for existing imports. */
 export declare const CLOUDFLARE_MCP_VETTED_CATALOG: import("../../catalog-drift.js").VettedCatalog;
-export {};