@waterlock/gateway 0.1.1 → 0.2.0

package/README.md

@@ -1,16 +1,26 @@
 # waterlock
-Be water, my friend
 
-Policy gateway for agent tool calls. Harness holds a session token; gateway holds the real credential, checks policy, forwards.
+Open source solution to [workos airlock](https://workos.com/blog/workos-airlock).
 
-```sh
-pnpm add @waterlock/gateway
-```
+** This repo is a work in progress. Not ready for production usage. If you would like to contribute, 
+please raise an issue and we can chat **
 
-```sh
-pnpm gen:gmail      # spec -> src/providers/gmail/generated.ts
-pnpm test
-pnpm build          # -> dist/
-```
+## Why use this?
 
-Release: bump `version` in package.json and merge. CI publishes to npm and creates the `v<version>` release.
+You don't want to inject real creds into your agents since most of the applications have
+really broad permissions. What waterlock gives you
+- A common language to work with permissions regardless of the application you choose
+- Full visibility into what the accesses were like / audit logs (upcoming)
+- A gateway to proxy forward your external resource calls, preventing rogue agents from
+  leaking your sensitive keys.
+- Static typescript functions that can work for validation.
+- Natural language for limiting what your agents can do for a more restrictive agents. For example,
+  if you are using gmail, you can simply say 'No billing info allowed in emails' and waterlock takes
+  care of working with you.
+- You own the integration logic. With workos, you are really coupled to their infra. This provides a
+  more variable approach to integration.
+- You own the ai layer, use ai-sdk, direct Anthropic's ai is fine as well. Waterlock just works.
+
+## Guide
+
+Install and usage: [wiki](https://github.com/waterlockcc/waterlock/wiki).

package/dist/codegen/cli.js

@@ -12,6 +12,7 @@ import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { fromDiscovery } from "./discovery.js";
 import { generate } from "./generate.js";
+import { generateGraphql } from "./graphql.js";
 import { fromOpenAPI } from "./openapi.js";
 async function main() {
     const args = process.argv.slice(2);
@@ -28,14 +29,28 @@ async function main() {
         const res = await fetch(config.source.url);
         if (!res.ok)
             throw new Error(`fetch ${config.source.url}: ${res.status}`);
-        await writeFile(specFile, JSON.stringify(await res.json(), null, 2) + "\n");
+        const text = config.source.kind === "graphql" ? await res.text() : JSON.stringify(await res.json(), null, 2) + "\n";
+        await writeFile(specFile, text);
         console.log(`pinned spec updated: ${specFile}`);
     }
-    const doc = JSON.parse(await readFile(specFile, "utf8"));
-    const spec = config.source.kind === "discovery"
-        ? fromDiscovery(doc)
-        : fromOpenAPI(doc, { provider: config.provider });
-    const { code, report, table } = generate(spec, config);
+    const source = await readFile(specFile, "utf8");
+    let code;
+    let report;
+    let summary;
+    if (config.source.kind === "graphql") {
+        const result = generateGraphql(source, config);
+        ({ code, report } = result);
+        summary = `${result.actions.length} actions`;
+    }
+    else {
+        const doc = JSON.parse(source);
+        const spec = config.source.kind === "discovery"
+            ? fromDiscovery(doc)
+            : fromOpenAPI(doc, { provider: config.provider });
+        const result = generate(spec, config);
+        ({ code, report } = result);
+        summary = `${spec.operations.length} actions, ${result.table.operations.length} routes`;
+    }
     const outFile = resolve(dir, config.out);
     const reportFile = config.report ? resolve(dir, config.report) : undefined;
     if (args.includes("--check")) {
@@ -50,7 +65,7 @@ async function main() {
     await writeFile(outFile, code);
     if (reportFile)
         await writeFile(reportFile, report);
-    console.log(`${config.provider}: ${spec.operations.length} actions, ${table.operations.length} routes -> ${outFile}`);
+    console.log(`${config.provider}: ${summary} -> ${outFile}`);
     if (reportFile)
         console.log(`  review: ${reportFile}`);
 }

package/dist/codegen/config.d.ts

@@ -3,17 +3,23 @@ export interface CodegenConfig {
     provider: string;
     /** Prefix for emitted TS types: `Gmail` -> `GmailAction`, `GmailParams`, ... */
     typePrefix: string;
-    /** Paths are relative to the config file. `file` is the pinned spec; `url` is used by `--fetch`. */
+    /**
+     * Paths are relative to the config file. `file` is the pinned spec (JSON, or SDL text for
+     * `graphql`); `url` is used by `--fetch`. `title` names a GraphQL schema in generated comments.
+     */
     source: {
-        kind: "discovery" | "openapi";
+        kind: "discovery" | "openapi" | "graphql";
         file: string;
         url?: string;
+        title?: string;
     };
     /** Output file for generated TS, relative to the config file. */
     out: string;
     /** Markdown report for reviewers, relative to the config file. */
     report?: string;
-    /** Import specifier for `OperationTable` in the generated file. */
+    /** Import specifier for `OperationTable` / `GraphqlTable` in the generated file. */
     typesImport?: string;
+    /** GraphQL only: TS types for custom scalars, e.g. `{ DateTime: "string" }`. Unlisted ones are `unknown`. */
+    scalars?: Record<string, string>;
 }
 export declare const defineCodegenConfig: (c: CodegenConfig) => CodegenConfig;

package/dist/codegen/graphql.d.ts

@@ -0,0 +1,14 @@
+import type { CodegenConfig } from "./config.js";
+export interface GenerateGraphqlResult {
+    code: string;
+    report: string;
+    /** Every action, e.g. `linear.mutation.issueCreate`. */
+    actions: string[];
+}
+/**
+ * GraphQL SDL -> action union, typed params and the schema the matcher validates against.
+ * Each top-level `query` and `mutation` field is one action (`<provider>.<operation>.<field>`);
+ * its arguments are the params. Subscriptions are skipped. The emitted SDL has descriptions
+ * stripped (they don't affect validation or coercion).
+ */
+export declare function generateGraphql(sdl: string, config: CodegenConfig): GenerateGraphqlResult;

package/dist/codegen/graphql.js

@@ -0,0 +1,116 @@
+import * as g from "graphql";
+const BUILTIN_TS = { String: "string", ID: "string", Int: "number", Float: "number", Boolean: "boolean" };
+/**
+ * GraphQL SDL -> action union, typed params and the schema the matcher validates against.
+ * Each top-level `query` and `mutation` field is one action (`<provider>.<operation>.<field>`);
+ * its arguments are the params. Subscriptions are skipped. The emitted SDL has descriptions
+ * stripped (they don't affect validation or coercion).
+ */
+export function generateGraphql(sdl, config) {
+    const schema = g.buildSchema(sdl);
+    const P = config.typePrefix;
+    const scalars = { ...BUILTIN_TS, ...config.scalars };
+    // Input and enum types reachable from top-level arguments: these get TS types.
+    const inputs = new Map();
+    const enums = new Map();
+    const custom = new Set();
+    const inputValue = (v) => ({ type: String(v.type), hasDefault: v.astNode?.defaultValue !== undefined });
+    const visit = (type) => {
+        const named = g.getNamedType(type);
+        if (inputs.has(named.name) || enums.has(named.name) || named.name in BUILTIN_TS)
+            return;
+        if (g.isEnumType(named)) {
+            enums.set(named.name, named.getValues().map((v) => v.name));
+        }
+        else if (g.isInputObjectType(named)) {
+            const fields = new Map();
+            inputs.set(named.name, fields);
+            for (const f of Object.values(named.getFields())) {
+                fields.set(f.name, inputValue(f));
+                visit(f.type);
+            }
+        }
+        else
+            custom.add(named.name);
+    };
+    const fields = [];
+    for (const operation of ["query", "mutation"]) {
+        const root = operation === "query" ? schema.getQueryType() : schema.getMutationType();
+        for (const f of Object.values(root?.getFields() ?? {})) {
+            const args = f.args.map((a) => {
+                visit(a.type);
+                return [a.name, inputValue(a)];
+            });
+            const description = f.description?.split("\n")[0].trim();
+            fields.push({ action: `${config.provider}.${operation}.${f.name}`, operation, args, ...(description ? { description } : {}) });
+        }
+    }
+    fields.sort((a, b) => byCodeUnit(a.action, b.action));
+    // TS for a type ref: lists and nullability from the SDL notation.
+    const ts = (ref) => {
+        const t = ref.endsWith("!") ? ref.slice(0, -1) : ref;
+        const base = t.startsWith("[") ? `${wrap(ts(t.slice(1, -1)))}[]` : named(t);
+        return ref.endsWith("!") || base === "unknown" ? base : `${base} | null`;
+    };
+    const wrap = (s) => (s.includes(" ") ? `(${s})` : s);
+    const named = (name) => (inputs.has(name) || enums.has(name) ? `${P}${name}` : (scalars[name] ?? "unknown"));
+    // Absent only if nullable without a default: graphql-js fills defaults in.
+    const member = (name, v) => `${name}${v.type.endsWith("!") || v.hasDefault ? "" : "?"}: ${ts(v.type)};`;
+    // Schema the gateway validates against, without descriptions.
+    const stripped = g.print(g.visit(g.parse(sdl, { noLocation: true }), {
+        enter: (node) => ("description" in node && node.description ? { ...node, description: undefined } : undefined),
+    }));
+    const out = [
+        `// GENERATED by waterlock codegen. Do not edit by hand.`,
+        `// Source: ${config.source.title ?? config.provider} GraphQL schema`,
+        `// Regenerate with the codegen CLI after changing ${config.provider}.config.ts or the pinned schema.`,
+        ``,
+        `export type ${P}Action =`,
+        ...fields.map((f, i) => `  | ${JSON.stringify(f.action)}${i === fields.length - 1 ? ";" : ""}`),
+        ``,
+        `/** Arguments of each top-level field, as seen by policy rules (defaults filled in). */`,
+        `export interface ${P}Params {`,
+        ...fields.map((f) => f.args.length === 0
+            ? `  ${JSON.stringify(f.action)}: Record<string, never>;`
+            : `  ${JSON.stringify(f.action)}: { ${f.args.map(([n, v]) => member(n, v)).join(" ")} };`),
+        `}`,
+        ``,
+        ...sorted(enums).map(([name, values]) => `export type ${P}${name} = ${values.map((v) => JSON.stringify(v)).join(" | ")};`),
+        ``,
+        ...sorted(inputs).map(([name, f]) => `export interface ${P}${name} { ${[...f].map(([n, v]) => member(n, v)).join(" ")} }`),
+        ``,
+        `/** The upstream schema (descriptions stripped). The matcher validates every request against it. */`,
+        `export const ${config.provider}Sdl = ${JSON.stringify(stripped)};`,
+        ``,
+    ];
+    const mutations = fields.filter((f) => f.operation === "mutation");
+    const queries = fields.filter((f) => f.operation === "query");
+    const unmapped = [...custom].filter((s) => !(s in scalars)).sort(byCodeUnit);
+    const list = (fs) => fs.map((f) => `- \`${f.action}\`${f.description ? ` ${f.description}` : ""}`);
+    const report = [
+        `# ${config.provider} codegen report`,
+        ``,
+        `Source: ${config.source.title ?? config.provider} GraphQL schema`,
+        ``,
+        `- ${fields.length} actions: ${mutations.length} mutations, ${queries.length} queries`,
+        `- Nested selections are not governed: an allowed query can read anything reachable from its field.`,
+        ...(unmapped.length ? [`- Custom scalars typed \`unknown\` (add to \`scalars\` in the config): ${unmapped.join(", ")}`] : []),
+        ``,
+        `## Mutations`,
+        ``,
+        ...list(mutations),
+        ``,
+        `## Queries`,
+        ``,
+        ...list(queries),
+        ``,
+    ];
+    return { code: out.join("\n"), report: report.join("\n"), actions: fields.map((f) => f.action) };
+}
+function sorted(m) {
+    return [...m].sort(([a], [b]) => byCodeUnit(a, b));
+}
+/** Locale-independent, so generated output is identical on every machine. */
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/codegen/index.d.ts

@@ -3,3 +3,4 @@ export { fromDiscovery, type DiscoveryDoc } from "./discovery.js";
 export { fromOpenAPI, type OpenAPIDoc } from "./openapi.js";
 export { generate, type GenerateResult } from "./generate.js";
 export type { NormalizedSpec, SpecOperation } from "./model.js";
+export { generateGraphql, type GenerateGraphqlResult } from "./graphql.js";

package/dist/codegen/index.js

@@ -2,3 +2,4 @@ export { defineCodegenConfig } from "./config.js";
 export { fromDiscovery } from "./discovery.js";
 export { fromOpenAPI } from "./openapi.js";
 export { generate } from "./generate.js";
+export { generateGraphql } from "./graphql.js";

package/dist/core/gateway.js

@@ -13,59 +13,88 @@ export function createGateway(opts) {
     const dup = ids.find((id, i) => ids.indexOf(id) !== i);
     if (dup)
         throw new Error(`provider "${dup}" is configured twice`);
-    const providers = new Map(opts.providers.map((p) => [
-        p.id,
-        {
-            def: p,
-            matcher: createMatcher(p.table, { allowedGlobalQueryParams: p.allowedGlobalQueryParams }),
-        },
-    ]));
+    const providers = new Map(opts.providers.map((p) => {
+        if (!p.table && !p.graphql)
+            throw new Error(`provider "${p.id}" has neither a REST table nor a GraphQL endpoint`);
+        const matcher = p.table && createMatcher(p.table, { allowedGlobalQueryParams: p.allowedGlobalQueryParams ?? [] });
+        return [p.id, { def: p, matcher }];
+    }));
     async function handle(req) {
         const url = new URL(req.url);
         const method = req.method.toUpperCase();
         // 1. Authenticate. The signed token names the provider; the agent can't pick another.
         const auth = await authenticate(req, opts.sessions);
         if ("error" in auth) {
-            return fail(401, "unauthenticated", "missing or invalid session token");
+            return failRest(401, "unauthenticated", "missing or invalid session token");
         }
         const session = auth.claims;
         const entry = providers.get(session.provider);
         if (!entry)
-            return fail(403, "unknown_provider", `this gateway has no provider "${session.provider}"`);
+            return failRest(403, "unknown_provider", `this gateway has no provider "${session.provider}"`);
         // The upstream host is fixed by config; the path is forwarded as-is.
         const upstreamPath = url.pathname;
         const override = METHOD_OVERRIDE_HEADERS.find((h) => req.headers.has(h));
         if (override)
-            return fail(400, "bad_request", `header ${override} not allowed`);
-        // 2. Match against the generated operation table.
-        const matched = entry.matcher.match(method, upstreamPath, url.searchParams);
-        if (!matched.ok)
-            return fail(matched.status, "policy_denied", matched.reason);
-        const { op } = matched;
-        // 3. Read body once: decode it for policy, forward the same bytes.
-        const body = await readBody(req, maxBody);
-        if (body === "too_large")
-            return fail(413, "bad_request", "body too large");
+            return failRest(400, "bad_request", `header ${override} not allowed`);
+        // 2. Match: the GraphQL endpoint on the body, everything else against the REST operation table.
+        const gql = entry.def.graphql && upstreamPath === entry.def.graphql.endpoint ? entry.def.graphql : undefined;
+        const fail = gql ? failGraphql : failRest;
+        const deny = (action, rules, reason) => fail(403, "policy_denied", reason, action, rules);
+        let action;
+        let params;
         let context = {};
-        const decoder = entry.def.decoders?.[op.action];
-        if (decoder) {
-            if (op.variant !== "standard") {
-                const reason = `${op.variant} route for ${op.action} not supported: body can't be inspected`;
-                return deny(op.action, [], reason);
-            }
-            try {
-                context = await decoder({ body, contentType: req.headers.get("content-type") });
-            }
-            catch (err) {
-                const reason = `could not decode request body: ${err instanceof Error ? err.message : String(err)}`;
-                return deny(op.action, [], reason);
+        let forwardBody;
+        const contentType = req.headers.get("content-type");
+        if (gql) {
+            if (method !== "POST")
+                return fail(405, "policy_denied", "GraphQL requests must be POST");
+            if (url.search)
+                return fail(400, "policy_denied", "query string not allowed on the GraphQL endpoint");
+            if (!/^application\/json\s*(;|$)/i.test(contentType ?? ""))
+                return fail(400, "bad_request", "content-type must be application/json");
+            const body = await readBody(req, maxBody);
+            if (body === "too_large")
+                return fail(413, "bad_request", "body too large");
+            const matched = gql.matcher.match(body);
+            if (!matched.ok)
+                return fail(matched.status, "policy_denied", matched.reason);
+            ({ action, params } = matched);
+            forwardBody = matched.body;
+        }
+        else {
+            if (!entry.matcher)
+                return fail(404, "policy_denied", `no ${entry.def.id} operation matches path`);
+            const matched = entry.matcher.match(method, upstreamPath, url.searchParams);
+            if (!matched.ok)
+                return fail(matched.status, "policy_denied", matched.reason);
+            const { op } = matched;
+            action = op.action;
+            params = matched.params;
+            // 3. Read body once: decode it for policy, forward the same bytes.
+            const body = await readBody(req, maxBody);
+            if (body === "too_large")
+                return fail(413, "bad_request", "body too large");
+            forwardBody = body;
+            const decoder = entry.def.decoders?.[op.action];
+            if (decoder) {
+                if (op.variant !== "standard") {
+                    const reason = `${op.variant} route for ${op.action} not supported: body can't be inspected`;
+                    return deny(op.action, [], reason);
+                }
+                try {
+                    context = await decoder({ body, contentType });
+                }
+                catch (err) {
+                    const reason = `could not decode request body: ${err instanceof Error ? err.message : String(err)}`;
+                    return deny(op.action, [], reason);
+                }
             }
         }
         // Built from the provider's own table and decoder, so it matches that provider's request type.
         const policyReq = {
             provider: entry.def.id,
-            action: op.action,
-            params: matched.params,
+            action,
+            params,
             context,
             session,
         };
@@ -77,7 +106,7 @@ export function createGateway(opts) {
             ...(opts.checkTimeoutMs ? { checkTimeoutMs: opts.checkTimeoutMs } : {}),
         });
         if (decision.effect === "deny") {
-            return deny(op.action, decision.rules, decision.reason);
+            return deny(action, decision.rules, decision.reason);
         }
         // 5. Forward with the real credential.
         const headers = new Headers();
@@ -86,12 +115,14 @@ export function createGateway(opts) {
             if (v !== null)
                 headers.set(h, v);
         }
+        if (gql)
+            headers.set("content-type", "application/json");
         let credential;
         try {
             credential = await entry.def.credentials({ session });
         }
         catch {
-            return fail(502, "upstream_auth", "could not obtain upstream credential", op.action);
+            return fail(502, "upstream_auth", "could not obtain upstream credential", action);
         }
         (entry.def.inject ?? bearer)({ headers, credential });
         const upstreamUrl = entry.def.upstream.replace(/\/$/, "") + upstreamPath + url.search;
@@ -100,12 +131,12 @@ export function createGateway(opts) {
             upstream = await fetch(upstreamUrl, {
                 method,
                 headers,
-                body: body.length > 0 && method !== "GET" ? body : undefined,
+                body: forwardBody.length > 0 && method !== "GET" ? forwardBody : undefined,
                 redirect: "manual",
             });
         }
         catch {
-            return fail(502, "upstream_unreachable", "upstream request failed", op.action);
+            return fail(502, "upstream_unreachable", "upstream request failed", action);
         }
         const resHeaders = new Headers(upstream.headers);
         for (const h of DROP_RESPONSE_HEADERS)
@@ -144,9 +175,14 @@ async function readBody(req, max) {
 function bearer({ headers, credential }) {
     headers.set("authorization", `Bearer ${credential.token}`);
 }
-function deny(action, rules, reason) {
-    return fail(403, "policy_denied", reason, action, rules);
+function failRest(status, code, message, action, rules) {
+    return Response.json({ error: errorFields(code, message, action, rules) }, { status });
+}
+/** GraphQL-style body, so GraphQL clients surface the message: `{ errors: [{ message, extensions: { code, ... } }] }`. */
+function failGraphql(status, code, message, action, rules) {
+    const { message: _, ...extensions } = errorFields(code, message, action, rules);
+    return Response.json({ errors: [{ message, extensions }] }, { status });
 }
-function fail(status, code, message, action, rules) {
-    return Response.json({ error: { code, message, ...(action ? { action } : {}), ...(rules?.length ? { rules } : {}) } }, { status });
+function errorFields(code, message, action, rules) {
+    return { code, message, ...(action ? { action } : {}), ...(rules?.length ? { rules } : {}) };
 }

package/dist/core/provider.d.ts

@@ -1,6 +1,6 @@
 import type { Credential, CredentialSource } from "./credentials.js";
 import type { AnyRequest } from "./policy.js";
-import type { OperationTable } from "./types.js";
+import type { GraphqlMatcher, OperationTable } from "./types.js";
 /**
  * Extracts policy-relevant fields from a request body. Throwing denies the
  * request: if the gateway can't read what a call does, it doesn't forward it.
@@ -14,10 +14,19 @@ export interface ProviderDefinition<R extends AnyRequest = AnyRequest> {
     id: string;
     /** Fixed upstream origin. The harness can never choose the host. */
     upstream: string;
-    table: OperationTable;
+    /** REST operations, matched on method + path. Omit for GraphQL-only providers. */
+    table?: OperationTable;
     /** Spec-level query params (e.g. Google's `fields`, `alt`) allowed on every call. Anything else unlisted is denied. */
-    allowedGlobalQueryParams: readonly string[];
-    /** Per-action body decoders. Only run on the standard route; upload variants of decoded actions are denied. */
+    allowedGlobalQueryParams?: readonly string[];
+    /**
+     * GraphQL endpoint (e.g. `/graphql`). Requests to it are matched on the body: the top-level
+     * field is the action. Build `matcher` with `createGraphqlMatcher` from `@waterlock/gateway/graphql`.
+     */
+    graphql?: {
+        endpoint: string;
+        matcher: GraphqlMatcher;
+    };
+    /** Per-action body decoders (REST only). Only run on the standard route; upload variants of decoded actions are denied. */
     decoders?: Partial<Record<string, Decoder>>;
     credentials: CredentialSource;
     /** Default: `Authorization: Bearer <token>`. */

package/dist/core/types.d.ts

@@ -38,3 +38,18 @@ export interface OperationTable {
     globalQueryParams: readonly ParamSpec[];
     operations: readonly Operation[];
 }
+export type GraphqlMatchResult = {
+    ok: true;
+    action: string;
+    /** Arguments of the top-level field: variables filled in, coerced to the schema, defaults applied. */
+    params: Record<string, unknown>;
+    /** JSON body to forward: the parsed document re-printed, so upstream runs exactly what was checked. */
+    body: string;
+} | {
+    ok: false;
+    status: 400 | 404;
+    reason: string;
+};
+export interface GraphqlMatcher {
+    match(body: Uint8Array): GraphqlMatchResult;
+}

package/dist/graphql/index.d.ts

@@ -0,0 +1,22 @@
+import { type GraphQLSchema } from "graphql";
+import type { GraphqlMatcher } from "../core/types.js";
+export type { GraphqlMatcher, GraphqlMatchResult } from "../core/types.js";
+export interface GraphqlMatcherOptions {
+    /** Provider id: actions are named `<provider>.<query|mutation>.<field>`. */
+    provider: string;
+    /** The upstream schema, or its SDL. */
+    schema: GraphQLSchema | string;
+    /** Parser token cap. Default 50k. */
+    maxTokens?: number;
+}
+/**
+ * Matches a GraphQL request body the way the REST matcher matches a URL: one request is one
+ * action, named after its top-level field (`linear.mutation.issueCreate`). Arguments, coerced
+ * by graphql-js exactly as the upstream server does, become `params`. Nested selections are not
+ * policy: they only shape the response, so reads reachable from an allowed field are limited
+ * by the upstream token's scopes, not by rules.
+ *
+ * Rejected rather than guessed at: anything that fails schema validation, batches, several
+ * operations or top-level fields in one request, subscriptions, persisted queries (no query text).
+ */
+export declare function createGraphqlMatcher(opts: GraphqlMatcherOptions): GraphqlMatcher;

package/dist/graphql/index.js

@@ -0,0 +1,130 @@
+import { buildSchema, getArgumentValues, getVariableValues, Kind, parse, print, validate, } from "graphql";
+/**
+ * Matches a GraphQL request body the way the REST matcher matches a URL: one request is one
+ * action, named after its top-level field (`linear.mutation.issueCreate`). Arguments, coerced
+ * by graphql-js exactly as the upstream server does, become `params`. Nested selections are not
+ * policy: they only shape the response, so reads reachable from an allowed field are limited
+ * by the upstream token's scopes, not by rules.
+ *
+ * Rejected rather than guessed at: anything that fails schema validation, batches, several
+ * operations or top-level fields in one request, subscriptions, persisted queries (no query text).
+ */
+export function createGraphqlMatcher(opts) {
+    const schema = typeof opts.schema === "string" ? buildSchema(opts.schema) : opts.schema;
+    const maxTokens = opts.maxTokens ?? 50_000;
+    const bad = (reason) => ({ ok: false, status: 400, reason });
+    const message = (err) => (err instanceof Error ? err.message : String(err));
+    return {
+        match(raw) {
+            try {
+                return match(raw);
+            }
+            catch (err) {
+                // Fail closed on anything unexpected (e.g. stack overflow on pathological documents).
+                return bad(`could not process GraphQL request: ${message(err)}`);
+            }
+        },
+    };
+    function match(raw) {
+        let json;
+        try {
+            json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+        }
+        catch {
+            return bad("body must be JSON");
+        }
+        if (Array.isArray(json))
+            return bad("batched requests not supported: send one operation per request");
+        if (!isObject(json))
+            return bad("body must be a JSON object");
+        const { query, variables, operationName } = json;
+        if (typeof query !== "string")
+            return bad("body.query must be the GraphQL document (persisted queries not supported)");
+        if (variables != null && !isObject(variables))
+            return bad("body.variables must be an object");
+        if (operationName != null && typeof operationName !== "string")
+            return bad("body.operationName must be a string");
+        let doc;
+        try {
+            doc = parse(query, { maxTokens, noLocation: true });
+        }
+        catch (err) {
+            return bad(`invalid GraphQL: ${message(err)}`);
+        }
+        let invalid;
+        try {
+            invalid = validate(schema, doc, undefined, { maxErrors: 1 });
+        }
+        catch (err) {
+            // graphql 17.0.2 overflows the stack on some fragment cycles instead of reporting them.
+            return bad(`invalid GraphQL: ${err instanceof RangeError ? "document too deeply nested or cyclic" : message(err)}`);
+        }
+        if (invalid.length)
+            return bad(`invalid GraphQL: ${invalid[0].message}`);
+        const ops = doc.definitions.filter((d) => d.kind === Kind.OPERATION_DEFINITION);
+        if (ops.length !== 1)
+            return bad(`send exactly one operation per request (got ${ops.length})`);
+        const op = ops[0];
+        if (operationName && op.name?.value !== operationName)
+            return bad(`operationName "${operationName}" not in document`);
+        if (op.operation === "subscription")
+            return bad("subscriptions not supported");
+        const root = schema.getRootType(op.operation);
+        if (!root)
+            return { ok: false, status: 404, reason: `${opts.provider} has no ${op.operation} type` };
+        const fragments = new Map(doc.definitions.filter((d) => d.kind === Kind.FRAGMENT_DEFINITION).map((d) => [d.name.value, d]));
+        const roots = [];
+        const err = collectRootFields(op.selectionSet, root.name, fragments, roots);
+        if (err)
+            return bad(err);
+        const real = roots.filter((f) => f.name.value !== "__typename");
+        if (real.length !== 1) {
+            const names = real.map((f) => f.name.value).join(", ");
+            return bad(`send one top-level field per request (got ${real.length}${names ? `: ${names}` : ""})`);
+        }
+        const node = real[0];
+        const field = root.getFields()[node.name.value]; // introspection fields (__schema, __type) aren't here: denied
+        if (!field)
+            return { ok: false, status: 404, reason: `no ${opts.provider} ${op.operation} field "${node.name.value}"` };
+        const vars = getVariableValues(schema, op.variableDefinitions ?? [], variables ?? {}, { maxErrors: 1 });
+        if (vars.errors)
+            return bad(vars.errors[0].message);
+        let params;
+        try {
+            params = getArgumentValues(field, node, vars.variableValues);
+        }
+        catch (err) {
+            return bad(message(err));
+        }
+        // Forward what was parsed, not the original text: no room for the two parsers to disagree.
+        const body = JSON.stringify({
+            query: print(doc),
+            ...(variables != null ? { variables } : {}),
+            ...(operationName ? { operationName } : {}),
+        });
+        return { ok: true, action: `${opts.provider}.${op.operation}.${field.name}`, params, body };
+    }
+}
+/**
+ * Top-level fields of an operation, including those inside fragments on the root type. Fields
+ * under `@skip`/`@include` count as present. Validation already rejected unknown and cyclic fragments.
+ */
+function collectRootFields(set, rootType, fragments, out) {
+    for (const sel of set.selections) {
+        if (sel.kind === Kind.FIELD) {
+            out.push(sel);
+            continue;
+        }
+        const frag = sel.kind === Kind.INLINE_FRAGMENT ? sel : fragments.get(sel.name.value);
+        const on = frag.typeCondition?.name.value;
+        if (on !== undefined && on !== rootType)
+            return `top-level fragment on ${on}, expected ${rootType}`;
+        const err = collectRootFields(frag.selectionSet, rootType, fragments, out);
+        if (err)
+            return err;
+    }
+    return undefined;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}