Manager for hasura allow-list

Automatically Populate the Hasura allow-list from found GraphQL operations in a path, including queries, mutations, and subscriptions. Supports update and versioning.

More on Hasura allow-list

Why

From hasura:

In production instances: Enabling the allow-list is highly recommended when running the GraphQL engine in production.

Allow list is a important security feature that restrict the GraphQL engine so that it executes only those operations that are present in the list. But managing allow-list manually can be tendious and prone to error.

How it works

The local queries, mutations, and subscriptions defined in .graphql or .gql files will be compared with the remote Hasura server. The allow list manager will fetch all allowed queries from the remote Hasura instance, add new queries, update existing ones and store the final query_collection files locally. Make sure to apply the new metadata to hasura after the allow list manager ran.

Versioning behavior

• -v --version <version> allows to version queries instead of updating them. This is especially useful for mobile app where client can take several weeks to update.
• The current behavior is to never remove past queries. When a query with the same name and different query is detected, it will create a new query to the allow list collection with the current timestamp and version.
• The version query name format is the following: $NAME___($TIMESTAMP-$VERSION)
• If you start versioning, you must continue versioning.

Installation

npm install --save-dev @herojourneyclub/hasura-allow-list-manager

or yarn

yarn add --dev @herojourneyclub/hasura-allow-list-manager

Usage

hasura-allow-list-manager [options]
hasura apply-metadata

Options

• -h | --host <uri> Hasura host URI
• -s | --admin-secret <key> Hasura admin secret
• -p | --path <path> Source path with gql or graphql files
• -f | --force-replace Replace change queries, not prompt and asking for continue
• -i | --allow-instrospection Send the Introspection query with your queries
• -r | --reset Delete all allow lists before running insert
• -v | --version <version> Version queries instead of replacing them. Incompatible with -f
• --version-max-version Maximum number of versions to keep per query. Will always keep at least 1
• --version-max-day Maximum age (in days) of query versions to keep. Will always keep at least 1
• --query-collection-path Path were the final query_collection will be stored

Examples

With update:

hasura-allow-list-manager -h http://localhost:8080 -s my-admin-secret -p './**/*.graphql' -f

With versionning:

GIT_VERSION=$(git log --pretty=format:"%h" -1)
hasura-allow-list-manager -h http://localhost:8080 -s my-admin-secret -p './**/*.graphql' -v ${GIT_VERSION}

--version-max-version and --version-max-age examples:

All queries are stored in the format of <query_name>__(<timestamp>-<version>). In the example the timestamp is a simple integer value.

{
    "GetProfile__(1_version-1)": "query GetProfile { Users { id } }",
    "GetProfile__(2_version-2)": "query GetProfile { Users { id, firstName } }",
    "GetProfile__(3_version-3)": "query GetProfile { Users { id, lastName } }"
}

Running the allow list manager with --version-max-version 2 would result in keeping the 2 most recent versions, so:

{
    "GetProfile__(2_version-2)": "query GetProfile { Users { id, firstName } }",
    "GetProfile__(3_version-3)": "query GetProfile { Users { id, lastName } }"
}

Running the allow list manager with --version-max-age 1 would keep all queries in the list that are 1 day old. If they are all older it would keep the most recent one. If we assume that todays timestamp is 4 then we would keep this:

{
    "GetProfile__(3_version-3)": "query GetProfile { Users { id, lastName } }"
}

Development

In order to run it locally you'll need to fetch some dependencies and run the cli.

1. Install dependencies:

npm install

or

yarn install

2. To run the cli:

npm run dev -- -h http://localhost:8080 -s my-admin-secret -p '**/*.graphql'

or

yarn dev -h http://localhost:8080 -s my-admin-secret -p '**/*.graphql'

Contributing

Contribution are welcome. Send us your PR or open a issue ticket. Let's build together.

Credits

Fork from:

• hasura-allowed-queries
• hasura-allow-operations-in by Rhys Bartels-Waller