@grafserv/persisted 0.0.0-1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @grafserv/persisted
+
+## 0.0.0-1.1
+
+### Patch Changes
+
+- [#297](https://github.com/benjie/postgraphile-private/pull/297)
+  [`5a7396e2d`](https://github.com/benjie/postgraphile-private/commit/5a7396e2d1675f49b1d54cf6e748f2bc35aefe8a)
+  Thanks [@benjie](https://github.com/benjie)! - New @grafserv/persisted plugin
+  to add persisted operations support to Grafserv 🎉
+- Updated dependencies
+  [[`90ed0cb7a`](https://github.com/benjie/postgraphile-private/commit/90ed0cb7a78479b85115cd1ce045ac253107b3eb),
+  [`56be761c2`](https://github.com/benjie/postgraphile-private/commit/56be761c29343e28ba4980c62c955b5adaef25c0),
+  [`8d270ead3`](https://github.com/benjie/postgraphile-private/commit/8d270ead3fa8331e28974aae052bd48ad537d1bf),
+  [`1a012bdd7`](https://github.com/benjie/postgraphile-private/commit/1a012bdd7d3748ac9a4ca9b1f771876654988f25),
+  [`b4eaf89f4`](https://github.com/benjie/postgraphile-private/commit/b4eaf89f401ca207de08770361d07903f6bb9cb0)]:
+  - grafserv@0.0.1-1.3
+  - grafast@0.0.1-1.3
+  - graphile-config@0.0.1-1.2

package/README.md

@@ -0,0 +1,243 @@
+# @grafserv/persisted
+
+<span class="badge-patreon"><a href="https://patreon.com/benjie" title="Support Graphile development on Patreon"><img src="https://img.shields.io/badge/sponsor-via%20Patreon-orange.svg" alt="Patreon sponsor button" /></a></span>
+[![Discord chat room](https://img.shields.io/discord/489127045289476126.svg)](http://discord.gg/graphile)
+[![Package on npm](https://img.shields.io/npm/v/@grafserv/persisted.svg?style=flat)](https://www.npmjs.com/package/@grafserv/persisted)
+![MIT license](https://img.shields.io/npm/l/@grafserv/persisted.svg)
+[![Follow](https://img.shields.io/badge/twitter-@GraphileHQ-blue.svg)](https://twitter.com/GraphileHQ)
+
+Persisted operations (aka "persisted queries", "query allowlist", "persisted
+documents") support for [Grafserv](https://grafast.org/grafserv). Applies to
+both standard GET and POST requests and to websocket connections. Works for all
+operation types (queries, mutations and subscriptions).
+
+We recommend that all GraphQL servers (PostGraphile or otherwise) that only
+intend first party clients to use the GraphQL schema should use persisted
+operations to mitigate attacks against the GraphQL API and to help track the
+fields that have been used. This package is our solution for Grafserv, for other
+servers you will need different software.
+
+<!-- SPONSORS_BEGIN -->
+
+## Crowd-funded open-source software
+
+To help us develop this software sustainably under the MIT license, we ask all
+individuals and businesses that use it to help support its ongoing maintenance
+and development via sponsorship.
+
+### [Click here to find out more about sponsors and sponsorship.](https://www.graphile.org/sponsor/)
+
+And please give some love to our featured sponsors 🤩:
+
+<table><tr>
+<td align="center"><a href="https://surge.io/"><img src="https://graphile.org/images/sponsors/surge.png" width="90" height="90" alt="Surge" /><br />Surge</a> *</td>
+<td align="center"><a href="https://www.netflix.com/"><img src="https://graphile.org/images/sponsors/Netflix.png" width="90" height="90" alt="Netflix" /><br />Netflix</a> *</td>
+<td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td>
+<td align="center"><a href="https://qwick.com/"><img src="https://graphile.org/images/sponsors/qwick.png" width="90" height="90" alt="Qwick" /><br />Qwick</a> *</td>
+</tr><tr>
+<td align="center"><a href="http://chads.website"><img src="https://graphile.org/images/sponsors/chadf.png" width="90" height="90" alt="Chad Furman" /><br />Chad Furman</a> *</td>
+<td align="center"><a href="https://dovetailapp.com/"><img src="https://graphile.org/images/sponsors/dovetail.png" width="90" height="90" alt="Dovetail" /><br />Dovetail</a> *</td>
+<td align="center"><a href="https://www.enzuzo.com/"><img src="https://graphile.org/images/sponsors/enzuzo.png" width="90" height="90" alt="Enzuzo" /><br />Enzuzo</a> *</td>
+<td align="center"><a href="https://stellate.co/"><img src="https://graphile.org/images/sponsors/Stellate.png" width="90" height="90" alt="Stellate" /><br />Stellate</a> *</td>
+</tr></table>
+
+<em>\* Sponsors the entire Graphile suite</em>
+
+<!-- SPONSORS_END -->
+
+## Installation
+
+```sh
+yarn add @grafserv/persisted
+# or: npm install --save @grafserv/persisted
+```
+
+## Usage
+
+Import `PersistedPlugin` from `@grafserv/persisted` and then add it to the
+`plugins` list in your `graphile.config.ts` (or equivalent) file:
+
+```ts
+import "graphile-config";
+import PersistedPlugin from "@grafserv/persisted";
+
+const preset: GraphileConfig.Preset = {
+  plugins: [PersistedPlugin],
+  grafserv: {
+    /* add configuration options here, e.g. */
+    persistedOperationsDirectory: `${process.cwd()}/.persisted_operations`,
+  },
+};
+
+export default preset;
+```
+
+### Options
+
+This plugin adds the following options to the Grafserv options:
+
+````ts
+/**
+ * This function will be passed a GraphQL request object (normally
+ * `{query: string, variables?: any, operationName?: string, extensions?: any}`,
+ * but in the case of persisted operations it likely won't have a `query`
+ * property), and must extract the hash to use to identify the persisted
+ * operation. For Apollo Client, this might be something like:
+ * `request?.extensions?.persistedQuery?.sha256Hash`; for Relay something
+ * like: `request?.documentId`.
+ */
+hashFromPayload?(request: ParsedGraphQLBody): string | undefined;
+
+/**
+ * We can read persisted operations from a folder (they must be named
+ * `<hash>.graphql`). When used in this way, the first request for a hash
+ * will read the file, and then the result will be cached such that the
+ * **filesystem read** will only impact the first use of that hash. We
+ * periodically scan the folder for new files, requests for hashes that
+ * were not present in our last scan of the folder will be rejected to
+ * mitigate denial of service attacks asking for non-existent hashes.
+ */
+persistedOperationsDirectory?: string;
+
+/**
+ * An optional string-string key-value object defining the persisted
+ * operations, where the keys are the hashes, and the values are the
+ * operation document strings to use.
+ */
+persistedOperations?: { [hash: string]: string };
+
+/**
+ * If your known persisted operations may change over time, or you'd rather
+ * load them on demand, you may supply this function. Note this function is
+ * **performance critical** so you should use caching to improve
+ * performance of any follow-up requests for the same hash.
+ */
+persistedOperationsGetter?: PersistedOperationGetter;
+
+/**
+ * There are situations where you may want to allow arbitrary operations
+ * (for example using GraphiQL in development, or allowing an admin to
+ * make arbitrary requests in production) whilst enforcing Persisted
+ * Operations for the application and non-admin users. This function
+ * allows you to determine under which circumstances persisted operations
+ * may be bypassed.
+ *
+ * IMPORTANT: this function must not throw!
+ *
+ * @example
+ *
+ * ```
+ * app.use(postgraphile(DATABASE_URL, SCHEMAS, {
+ *   allowUnpersistedOperation(event) {
+ *     return process.env.NODE_ENV === "development" && event.request?.getHeader('referer')?.endsWith("/graphiql");
+ *   }
+ * });
+ * ```
+ */
+allowUnpersistedOperation?:
+  | boolean
+  | ((event: ProcessGraphQLRequestBodyEvent) => boolean);
+````
+
+All these options are optional; but you should specify exactly one of
+`persistedOperationsDirectory`, `persistedOperations` or
+`persistedOperationsGetter` for this plugin to be useful.
+
+## Generating Persisted Operations
+
+### Relay
+
+Relay has built-in support for persisted operations:
+
+https://relay.dev/docs/guides/persisted-queries/
+
+Pass `--persist-output ./path/to/server.json` to `relay-compiler` along with
+your normal options to have it generate the persisted operations file. You can
+then use the `addToPersistedOperations.js` script below to split this operations
+JSON file into one file per query that can be passed to
+`--persisted-operations-directory`.
+
+Then in your network config (`fetchQuery` function) you need to change the
+`query: operation.text` to `documentId: operation.id`
+[as shown in the relay docs](https://relay.dev/docs/guides/persisted-queries/#network-layer-changes).
+
+### GraphQL-Code-Generator
+
+For everything except Relay, we recommend that you generate persisted operations
+when you build your clients using the awesome
+[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator)
+project and the
+[graphql-codegen-persisted-query-ids](https://www.npmjs.com/package/graphql-codegen-persisted-query-ids)
+(tested with v0.1.2) plugin. A config might look like:
+
+```yaml
+schema: "schema.graphql"
+documents: "src/**/*.graphql"
+hooks:
+  afterAllFileWrite:
+    - node addToPersistedOperations.js
+generates:
+  client.json:
+    plugins:
+      - graphql-codegen-persisted-query-ids:
+          output: client
+          algorithm: sha256
+  server.json:
+    plugins:
+      - graphql-codegen-persisted-query-ids:
+          output: server
+          algorithm: sha256
+```
+
+We also recommend using the file `addToPersistedOperations.js` to write the
+`server.json` file contents out to separate GraphQL files every time the code is
+built for easier version control:
+
+```js
+// addToPersistedOperations.js
+const map = require("./server.json");
+const { promises: fsp } = require("fs");
+
+async function main() {
+  await Promise.all(
+    Object.entries(map).map(([hash, query]) =>
+      fsp.writeFile(
+        `${__dirname}/.persisted_operations/${hash}.graphql`,
+        query,
+      ),
+    ),
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+```
+
+Then you pass the `.persisted_operations` folder via the
+`persistedOperationsDirectory` option as shown in the usage example.
+
+#### Apollo Client
+
+You can configure Apollo Client to send the persisted operations generated by
+`graphql-codegen` with `apollo-link-persisted-queries`:
+
+```ts
+import { createPersistedQueryLink } from "apollo-link-persisted-queries";
+import { usePregeneratedHashes as withPregeneratedHashes } from "graphql-codegen-persisted-query-ids/lib/apollo";
+import { hashes } from "./path/to/client.json";
+
+const persistedLink = createPersistedQueryLink({
+  useGETForHashedQueries: false,
+  generateHash: withPregeneratedHashes(hashes),
+  disable: () => false,
+});
+
+// ...
+
+const client = new ApolloClient({
+  link: ApolloLink.from([persistedLink, httpLink]),
+  // ...
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { PersistedOperationGetter } from "./interfaces.js";
+declare const PersistedPlugin: GraphileConfig.Plugin;
+export default PersistedPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAIhE,QAAA,MAAM,eAAe,EAAE,cAAc,CAAC,MA8CrC,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const grafast_1 = require("grafast");
+const promises_1 = tslib_1.__importDefault(require("node:fs/promises"));
+const version = require("../package.json").version;
+const PersistedPlugin = {
+    name: "PersistedPlugin",
+    description: "Enables persisted operations in Grafserv",
+    version,
+    grafserv: {
+        hooks: {
+            processGraphQLRequestBody(info, event) {
+                const { body } = event;
+                const options = info.resolvedPreset.grafserv;
+                if (!options) {
+                    throw new grafast_1.SafeError("Persisted operations misconfigured; rejecting requests.", { statusCode: 500 });
+                }
+                const realQuery = persistedOperationFromPayload(body, options, shouldAllowUnpersistedOperation(options, event));
+                // Always overwrite
+                if (realQuery != null && typeof realQuery !== "string") {
+                    return realQuery.then((q) => {
+                        if (typeof q === "string") {
+                            body.query = q;
+                        }
+                        else {
+                            throw new grafast_1.SafeError("Persisted operations are enabled on this server, please provide an approved document id.", { statusCode: 400 });
+                        }
+                    });
+                }
+                else {
+                    if (typeof realQuery === "string") {
+                        body.query = realQuery;
+                    }
+                    else {
+                        throw new grafast_1.SafeError("Persisted operations are enabled on this server, please provide an approved document id.", { statusCode: 400 });
+                    }
+                }
+            },
+        },
+    },
+};
+exports.default = PersistedPlugin;
+/**
+ * This fallback hashFromPayload method is compatible with Apollo Client and
+ * Relay.
+ */
+function defaultHashFromPayload(payload) {
+    return (
+    // https://github.com/apollographql/apollo-link-persisted-queries#protocol
+    payload?.extensions?.persistedQuery?.sha256Hash ||
+        // https://relay.dev/docs/en/persisted-queries#network-layer-changes
+        payload?.documentId ||
+        // Benjie's memory
+        payload?.id);
+}
+/**
+ * Given a cache object, returns a persisted operation getter that looks up the
+ * given hash in said cache object.
+ */
+function persistedOperationGetterForCache(cache) {
+    return (key) => cache[key];
+}
+function makeGetterForDirectory(directory) {
+    // NOTE: We periodically scan the folder to see what files it contains so
+    // that we can reject requests to non-existent files to avoid DOS attacks
+    // having us make lots of requests to the filesystem.
+    let files = null;
+    /**
+     * This function must never reject.
+     */
+    async function scanDirectory() {
+        try {
+            const allFiles = await promises_1.default.readdir(directory);
+            files = allFiles.filter((name) => name.endsWith(".graphql"));
+        }
+        catch (e) {
+            console.error(`Error occurred whilst scanning '${directory}'`);
+            console.error(e);
+        }
+        finally {
+            // TODO: This interval should be configurable.
+            // TODO: This might not be needed in production, and if so should be able to be disabled.
+            // TODO: In dev watching the folder might be a better experience.
+            // We don't know how long the scanning takes, so rather than setting an
+            // interval, we wait 5 seconds between scans before kicking off the next
+            // one.
+            setTimeout(scanDirectory, 5000);
+        }
+    }
+    scanDirectory();
+    const operationFromHash = new Map();
+    function getOperationFromHash(hash) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(hash)) {
+            throw new Error("Invalid hash");
+        }
+        let operation = operationFromHash.get(hash);
+        if (!operation) {
+            const filename = `${hash}.graphql`;
+            if (files && !files.includes(filename)) {
+                throw new Error(`Could not find file for hash '${hash}'`);
+            }
+            operation = promises_1.default
+                .readFile(`${directory}/${filename}`, "utf8")
+                .catch(() => null);
+            operationFromHash.set(hash, operation);
+            // Once resolved, replace reference to string to avoid unnecessary ticks
+            operation.then((operationText) => {
+                operationFromHash.set(hash, operationText);
+            });
+        }
+        return operation;
+    }
+    return getOperationFromHash;
+}
+const directoryGetterByDirectory = new Map();
+/**
+ * Given a directory, get or make the persisted operations getter.
+ */
+function getterForDirectory(directory) {
+    let getter = directoryGetterByDirectory.get(directory);
+    if (!getter) {
+        getter = makeGetterForDirectory(directory);
+        directoryGetterByDirectory.set(directory, getter);
+    }
+    return getter;
+}
+/**
+ * Extracts or creates a persisted operation getter function from the
+ * PostGraphile options.
+ */
+function getterFromOptionsCore(options) {
+    const optionsSpecified = Object.keys(options).filter((key) => [
+        "persistedOperationsGetter",
+        "persistedOperationsDirectory",
+        "persistedOperations",
+    ].includes(key));
+    if (optionsSpecified.length > 1) {
+        // If you'd like support for more than one of these options; send a PR!
+        throw new Error(`'${optionsSpecified.join("' and '")}' were specified, at most one of these operations can be specified.`);
+    }
+    if (options.persistedOperationsGetter) {
+        return options.persistedOperationsGetter;
+    }
+    else if (options.persistedOperations) {
+        return persistedOperationGetterForCache(options.persistedOperations);
+    }
+    else if (options.persistedOperationsDirectory) {
+        return getterForDirectory(options.persistedOperationsDirectory);
+    }
+    else {
+        throw new Error("Server misconfiguration issue: persisted operations (operation allowlist) is in place, but the server has not been told how to fetch the allowed operations. Please provide one of the persisted operations configuration options.");
+    }
+}
+// TODO: use an LRU? For users using lots of new options objects this will
+// cause a memory leak. But LRUs have a performance cost... Maybe switch to LRU
+// once the size has grown?
+const getterFromOptionsCache = new Map();
+/**
+ * Returns a cached getter for performance reasons.
+ */
+function getterFromOptions(options) {
+    let getter = getterFromOptionsCache.get(options);
+    if (!getter) {
+        getter = getterFromOptionsCore(options);
+        getterFromOptionsCache.set(options, getter);
+    }
+    return getter;
+}
+function shouldAllowUnpersistedOperation(options, event) {
+    const { allowUnpersistedOperation } = options;
+    if (typeof allowUnpersistedOperation === "function") {
+        return allowUnpersistedOperation(event);
+    }
+    return !!allowUnpersistedOperation;
+}
+/**
+ * Given a payload, this method returns the GraphQL operation document
+ * (string), or null on failure. It **never throws**.
+ */
+function persistedOperationFromPayload(payload, options, allowUnpersistedOperation) {
+    try {
+        const hashFromPayload = options.hashFromPayload || defaultHashFromPayload;
+        const hash = hashFromPayload(payload);
+        if (typeof hash !== "string") {
+            if (allowUnpersistedOperation && typeof payload?.query === "string") {
+                return payload.query;
+            }
+            throw new Error("We could not find a persisted operation hash string in the request.");
+        }
+        const getter = getterFromOptions(options);
+        return getter(hash);
+    }
+    catch (e) {
+        console.error("Failed to get persisted operation from payload", payload, e);
+        // We must not throw, instead just overwrite the query with null (the error
+        // will be thrown elsewhere).
+        return null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/interfaces.d.ts

@@ -0,0 +1,70 @@
+import type { PromiseOrDirect } from "grafast";
+import type { ParsedGraphQLBody, ProcessGraphQLRequestBodyEvent } from "grafserv";
+/**
+ * Given a persisted operation hash, return the associated GraphQL operation
+ * document.
+ */
+export type PersistedOperationGetter = (hash: string) => PromiseOrDirect<string>;
+declare global {
+    namespace GraphileConfig {
+        interface GrafservOptions {
+            /**
+             * This function will be passed a GraphQL request object (normally
+             * `{query: string, variables?: any, operationName?: string, extensions?: any}`,
+             * but in the case of persisted operations it likely won't have a `query`
+             * property), and must extract the hash to use to identify the persisted
+             * operation. For Apollo Client, this might be something like:
+             * `request?.extensions?.persistedQuery?.sha256Hash`; for Relay something
+             * like: `request?.documentId`.
+             */
+            hashFromPayload?(request: ParsedGraphQLBody): string | undefined;
+            /**
+             * We can read persisted operations from a folder (they must be named
+             * `<hash>.graphql`). When used in this way, the first request for a hash
+             * will read the file, and then the result will be cached such that the
+             * **filesystem read** will only impact the first use of that hash. We
+             * periodically scan the folder for new files, requests for hashes that
+             * were not present in our last scan of the folder will be rejected to
+             * mitigate denial of service attacks asking for non-existent hashes.
+             */
+            persistedOperationsDirectory?: string;
+            /**
+             * An optional string-string key-value object defining the persisted
+             * operations, where the keys are the hashes, and the values are the
+             * operation document strings to use.
+             */
+            persistedOperations?: {
+                [hash: string]: string;
+            };
+            /**
+             * If your known persisted operations may change over time, or you'd rather
+             * load them on demand, you may supply this function. Note this function is
+             * **performance critical** so you should use caching to improve
+             * performance of any follow-up requests for the same hash.
+             */
+            persistedOperationsGetter?: PersistedOperationGetter;
+            /**
+             * There are situations where you may want to allow arbitrary operations
+             * (for example using GraphiQL in development, or allowing an admin to
+             * make arbitrary requests in production) whilst enforcing Persisted
+             * Operations for the application and non-admin users. This function
+             * allows you to determine under which circumstances persisted operations
+             * may be bypassed.
+             *
+             * IMPORTANT: this function must not throw!
+             *
+             * @example
+             *
+             * ```
+             * app.use(postgraphile(DATABASE_URL, SCHEMAS, {
+             *   allowUnpersistedOperation(event) {
+             *     return process.env.NODE_ENV === "development" && event.request?.getHeader('referer')?.endsWith("/graphiql");
+             *   }
+             * });
+             * ```
+             */
+            allowUnpersistedOperation?: boolean | ((event: ProcessGraphQLRequestBodyEvent) => boolean);
+        }
+    }
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EACV,iBAAiB,EACjB,8BAA8B,EAC/B,MAAM,UAAU,CAAC;AAGlB;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,IAAI,EAAE,MAAM,KACT,eAAe,CAAC,MAAM,CAAC,CAAC;AAE7B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,cAAc,CAAC;QACvB,UAAU,eAAe;YACvB;;;;;;;;eAQG;YACH,eAAe,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAC;YAEjE;;;;;;;;eAQG;YACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;YAEtC;;;;eAIG;YACH,mBAAmB,CAAC,EAAE;gBAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;aAAE,CAAC;YAEjD;;;;;eAKG;YACH,yBAAyB,CAAC,EAAE,wBAAwB,CAAC;YAErD;;;;;;;;;;;;;;;;;;;eAmBG;YACH,yBAAyB,CAAC,EACtB,OAAO,GACP,CAAC,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,CAAC;SAC1D;KACF;CACF"}

package/dist/interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@grafserv/persisted",
+  "version": "0.0.0-1.1",
+  "description": "Persisted operations support for Grafserv",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "prepack": "tsc -b",
+    "test": "true"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphile/heart.git"
+  },
+  "keywords": [
+    "persisted",
+    "queries",
+    "operations",
+    "documents",
+    "graphql",
+    "grafserv",
+    "server",
+    "grafast",
+    "graphile",
+    "fast",
+    "graphite"
+  ],
+  "author": "Benjie Gillam <code@benjiegillam.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/graphile/heart/issues"
+  },
+  "homepage": "https://github.com/graphile/heart/tree/main/grafast/grafserv-persisted",
+  "dependencies": {
+    "graphile-config": "^0.0.1-1.2",
+    "tslib": "^2.4.0"
+  },
+  "engines": {
+    "node": ">=16.10"
+  },
+  "peerDependencies": {
+    "grafast": "^0.0.1-1.3",
+    "grafserv": "^0.0.1-1.3"
+  },
+  "devDependencies": {
+    "grafast": "^0.0.1-1.3",
+    "grafserv": "^0.0.1-1.3",
+    "jest": "^28.1.3",
+    "jest-serializer-graphql-schema": "^5.0.0-1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.0-beta"
+  },
+  "files": [
+    "dist",
+    "index.js"
+  ]
+}