feat: filtered introspection queries

docs/auth-context.md

@@ -37,6 +37,7 @@ const resolvers = {
   }
 }
 
+const app = Fastify()
 app.register(mercurius, {
   schema,
   resolvers

docs/schema-filtering.md

@@ -0,0 +1,128 @@
+# GraphQL Schema Filtering
+
+Using mercurius you can optionally filter the GraphQL schema based on the user's permissions.
+This feature limits the [Introspection queries](https://graphql.org/learn/introspection/) visibility.
+Doing so, the user will only be able to see the fields that are accessible to them.
+
+To enable this feature, you can use the `filterSchema` plugin's option:
+
+```js
+const Fastify = require('fastify')
+const mercurius = require('mercurius')
+const mercuriusAuth = require('mercurius-auth')
+
+const schema = `
+  directive @hasPermission (grant: String!) on OBJECT | FIELD_DEFINITION
+
+  type Message {
+    title: String!
+    message: String!
+    notes: String @hasPermission(grant: "see-all")
+  }
+
+  type Query {
+    publicMessages: [Message!]
+  }
+`
+
+const app = Fastify()
+app.register(mercurius, {
+  schema,
+  resolvers
+})
+
+app.register(mercuriusAuth, {
+  filterSchema: true,
+  authDirective: 'hasPermission',
+  authContext: function (context) {
+    return { permission: context.reply.request.headers['x-permission'] }
+  },
+  applyPolicy: async function hasPermissionPolicy (authDirectiveAST, parent, args, context, info) {
+    const needed = authDirectiveAST.arguments.find(arg => arg.name.value === 'grant').value.value
+    const hasGrant = context.auth.permission === needed
+    if (!hasGrant) {
+      throw new Error(`Needed ${needed} grant`)
+    }
+    return true
+  }
+})
+
+app.listen(3000)
+```
+
+After starting the server, you can use the following GraphQL query to test the filtering:
+
+```graphql
+{
+  __type (name:"Message") {
+    name
+    fields {
+      name
+    }
+  }
+}
+```
+
+You should get the following response:
+
+```json
+{
+  "data": {
+    "__type": {
+      "name": "Message",
+      "fields": [
+        {
+          "name": "title"
+        },
+        {
+          "name": "message"
+        }
+      ]
+    }
+  }
+}
+```
+
+The `notes` field is not accessible to the user because the user doesn't have the `see-all` permission.
+
+Adding the Request Headers as follows:
+
+```json
+{
+  "x-permission": "see-all"
+}
+```
+
+Will make the user able to see the `notes` field.
+
+## Implementations details
+
+You must be informed about some details about the filtering feature.
+
+- During the introspection query, the `applyPolicy` function is executed once per single GraphQL object.
+- The `applyPolicy` function doesn't have the input `parent` and `args` arguments set during the introspection run.
+- When the HTTP request payload contains an introspection query and a user-land query, you will not get auth errors because the introspection query is executed before the user-land query and filters the schema. Note that the protected fields will **not** be returned as expected, without any security implications. Here is an example of a GraphQL query that will not throw an error:
+
+```graphql
+{
+  __type (name:"Message") {
+    name
+    fields {
+      name
+    }
+  }
+
+  publicMessages {
+    notes
+  }
+}
+```
+
+### Special usages
+
+Depending on the [`DirectiveLocations`](https://github.com/graphql/graphql-spec/blob/main/spec/Section%203%20--%20Type%20System.md#directives) you will have two main behaviors:
+
+- The normal behaviour is when the `DirectiveLocations` is hidden from the introspection query.
+- The augmented behaviour is when the schema has additional hidden entities from the introspection query. It happens when:
+  - The directive is `on INPUT_FIELD_DEFINITION`: the whole `input` item is hidden
+  - The `Query` is hidden if the user doesn't have access to the `input` or `output` object types.

index.d.ts

@@ -62,6 +62,10 @@ export interface MercuriusAuthDirectiveOptions<TParent=any, TArgs=any, TContext=
    * The name of the directive that the Mercurius auth plugin will look for within the GraphQL schema in order to identify protected fields. For example, for directive definition `directive @auth on OBJECT | FIELD_DEFINITION`, the corresponding name would be auth.
    */
   authDirective: string;
+  /**
+   * When set to true, the plugin will automatically hide the auth directive to the GraphQL schema if the policy is not satisfated.
+   */
+  filterSchema?: boolean;
 }
 
 export interface MercuriusAuthExternalPolicyOptions<TParent=any, TArgs=any, TContext=MercuriusContext, TPolicy=any> extends MercuriusAuthBaseOptions<TParent, TArgs, TContext, TPolicy> {

index.js

@@ -3,6 +3,7 @@
 const fp = require('fastify-plugin')
 const Auth = require('./lib/auth')
 const { validateOpts } = require('./lib/validation')
+const filterSchema = require('./lib/filter-schema')
 
 const plugin = fp(
   async function (app, opts) {
@@ -21,11 +22,18 @@ const plugin = fp(
     app.graphql.addHook('onGatewayReplaceSchema', async (instance, schema) => {
       const authSchema = auth.getPolicy(schema)
       auth.registerAuthHandlers(schema, authSchema)
+      if (opts.filterSchema === true) {
+        filterSchema.updatePolicy(app, authSchema, opts)
+      }
     })
 
     if (typeof opts.authContext !== 'undefined') {
       app.graphql.addHook('preExecution', auth.authContextHook.bind(auth))
     }
+
+    if (opts.filterSchema === true) {
+      filterSchema(app, authSchema, opts)
+    }
   },
   {
     name: 'mercurius-auth',

lib/filter-schema.js

@@ -0,0 +1,166 @@
+'use strict'
+
+const {
+  wrapSchema,
+  PruneSchema,
+  FilterTypes,
+  TransformObjectFields,
+  FilterInputObjectFields
+} = require('@graphql-tools/wrap')
+const { GraphQLObjectType } = require('graphql')
+
+const kDirectiveGrouping = Symbol('mercurius-auth.filtering.group')
+
+module.exports = filterIntrospectionSchema
+
+function filterIntrospectionSchema (app, policy, { applyPolicy: policyFunction }) {
+  if (!app[kDirectiveGrouping]) {
+    app[kDirectiveGrouping] = []
+
+    // the filter hook must be the last one to be executed (after all the authContextHook ones)
+    app.ready(err => {
+      /* istanbul ignore next */
+      if (err) throw err
+      app.graphql.addHook('preExecution', filterGraphQLSchemaHook.bind(app))
+    })
+  }
+
+  app[kDirectiveGrouping].push({
+    policy,
+    policyFunction
+  })
+}
+
+filterIntrospectionSchema.updatePolicy = function (app, policy, { applyPolicy: policyFunction }) {
+  const storedPolicy = app[kDirectiveGrouping].find(({ policyFunction: storedPolicy }) => storedPolicy === policyFunction)
+  storedPolicy.policy = policy
+}
+
+async function filterGraphQLSchemaHook (schema, document, context) {
+  if (!isIntrospection(document)) {
+    return
+  }
+
+  const filteredSchema = await filterSchema(schema,
+    this[kDirectiveGrouping],
+    context)
+
+  return {
+    schema: filteredSchema
+  }
+}
+
+function isIntrospection (document) {
+  for (const queryType of document.definitions) {
+    if (queryType.operation !== 'query') {
+      // if there is a mutation or subscription, we can skip the introspection check
+      break
+    }
+
+    // if there is an introspection operation, we must filter the schema
+    if (queryType.selectionSet.selections.some(sel => (
+      sel.name.value === '__schema' ||
+      sel.name.value === '__type'
+    ))) {
+      return true
+    }
+  }
+  return false
+}
+
+async function filterSchema (graphQLSchema, policies, context) {
+  const filterDirectiveMap = {}
+
+  // each `policies` item is a directive
+  let skipFiltering = true
+  for (const { policy, policyFunction } of policies) {
+    // each `policy` contains all the GraphQL OBJECT and FIELDS that are affected by the directive
+    for (const [typeName, typePolicy] of Object.entries(policy)) {
+      // different `policies` item can affect the same GraphQL OBJECT
+      if (filterDirectiveMap[typeName] === undefined) {
+        filterDirectiveMap[typeName] = {}
+      } else if (filterDirectiveMap[typeName] === false) {
+        // if the object has already been filtered, we can skip the field processing
+        continue
+      }
+
+      const schemaType = graphQLSchema.getType(typeName)
+      const schemaTypeFields = typeof schemaType.getFields === 'function'
+        ? schemaType.getFields()
+        : {}
+      for (const [fieldName, fieldPolicy] of Object.entries(typePolicy)) {
+        // each `fieldName` is a single GraphQL item associated with the directive
+
+        if (filterDirectiveMap[typeName] === false || filterDirectiveMap[typeName][fieldName] === false) {
+          // if we have already decided to filter out this field
+          // it does not need to be checked again
+          continue
+        }
+
+        let canShowDirectiveField = true
+        const isObjectPolicy = fieldName === '__typePolicy'
+        try {
+          // https://github.com/graphql/graphql-js/blob/main/src/type/definition.ts#L974
+          // TODO check gq.typeFromAST
+          const info = {
+            fieldName,
+            fieldNodes: schemaType.astNode.fields,
+            returnType: isObjectPolicy ? '' : schemaTypeFields[fieldName].type, // TODO
+            parentType: schemaType,
+            schema: graphQLSchema,
+            fragments: {},
+            rootValue: {},
+            operation: { kind: 'OperationDefinition', operation: 'query' },
+            variableValues: {}
+          }
+          // The null parameters are: https://graphql.org/learn/execution/#root-fields-resolvers
+          // - parent: it is not possible know it since the resolver is not executed yet
+          // - args: it is not expected that the introspection query will have arguments for the directives policies
+          canShowDirectiveField = await policyFunction(fieldPolicy, null, null, context, info)
+          if (canShowDirectiveField instanceof Error || !canShowDirectiveField) {
+            canShowDirectiveField = false
+          }
+        } catch (error) {
+          canShowDirectiveField = false
+        }
+
+        skipFiltering = skipFiltering && canShowDirectiveField
+        if (canShowDirectiveField === false && isObjectPolicy) {
+          // the directive is assigned to a GraphQL OBJECT so we need to filter out all the fields
+          filterDirectiveMap[typeName] = canShowDirectiveField
+        } else {
+          filterDirectiveMap[typeName][fieldName] = canShowDirectiveField
+        }
+      }
+    }
+  }
+
+  if (skipFiltering) {
+    return graphQLSchema
+  }
+
+  return wrapSchema({
+    schema: graphQLSchema,
+    transforms: [
+      new FilterTypes(type => {
+        // should we filter out this whole type?
+        return filterDirectiveMap[type.name] !== false
+      }),
+      new TransformObjectFields(filterField),
+      new FilterInputObjectFields(filterField),
+      new PruneSchema({
+        skipPruning (type) {
+          // skip pruning if the type is the Query or Mutation object
+          return type instanceof GraphQLObjectType && (type.name === 'Query' || type.name === 'Mutation')
+        }
+      })
+    ]
+  })
+
+  function filterField (typeName, fieldName, fieldConfig) {
+    if (filterDirectiveMap[typeName] && filterDirectiveMap[typeName][fieldName] === false) {
+      return null // omit the field
+    }
+    return undefined // unchanged
+  }
+}

lib/validation.js

@@ -26,6 +26,10 @@ function validateOpts (opts) {
         }
       }
     }
+
+    if (opts.filterSchema === true) {
+      throw new MER_AUTH_ERR_INVALID_OPTS('opts.filterSchema cannot be used when mode is external.')
+    }
     // Default mode
   } else {
     // Mandatory

package.json

@@ -38,7 +38,7 @@
     "autocannon": "^7.0.5",
     "concurrently": "^6.1.0",
     "fastify": "^3.0.2",
-    "mercurius": "^8.0.0",
+    "mercurius": "github:mercurius-js/mercurius#master",
     "pre-commit": "^1.2.2",
     "snazzy": "^9.0.0",
     "standard": "^16.0.3",
@@ -48,6 +48,7 @@
     "wait-on": "^6.0.0"
   },
   "dependencies": {
+    "@graphql-tools/wrap": "^8.3.2",
     "fastify-error": "^0.3.0",
     "fastify-plugin": "^3.0.0",
     "graphql": "^15.4.0"