structure + some text, missing examples

Author: rsill-neo4j

modules/ROOT/pages/security/securing-a-graphql-api.adoc

@@ -4,21 +4,228 @@
 
 Lorem ipsum.
 
+
 == Prerequisites
 
+Set up a new AuraDB instance.
+Refer to link:https://neo4j.com/docs/aura/getting-started/create-instance/[Creating a Neo4j Aura instance].
+
+
+== Security-related directives
+
+Lorem ipsum.
+
+
+=== Authentication
+
 Lorem ipsum.
+Explanation on different auth options.
+
+
+==== JWT
+
+Lorem ipsum.
+
+
+==== Lorem?
+
+ipsum.
 
-== Directives
 
 === Authorization
 
 Validate versus filter.
 We want to ensure we don't report back database internals to end users. Validate throws an error, which could be a hint of what exists or not.
 
-== Further reading
 
-Explanation on different auth options
+== Best practice checklist
+
+Besides authentication and authorization considerations, there are a couple of worthwhile best practices to increase your API's security.
+
+
+=== Avoid introspection and data field suggestions
+
+While the xref:getting-started/graphql-aura.adoc[Getting started page for GraphQL and Aura Console] advocates to both **Enable introspection** as well as **Enable field suggestions**, this is not recommended when considering security.
+
+Both potentially expose information that can be used to gain insight on specifics of your GraphQL schema and execute targeted malicious opLorem ipsumerations.
+Be sure to deactivate both in a customer-facing real-life scenario.
+
+
+=== Catch internal errors
+
+For the same reason it is advisable to avoid introspection and data field suggestions, it can make your API more secure to catch internal errors and redact which information you want to pass on to the end user.
+
+For example, the following error reveals information XY:
+
+[source, json, indent=0]
+----
+"data": {
+  "field": "value"
+}
+----
+
+You can use Apollo Server's link:https://www.apollographql.com/docs/apollo-server/data/errors[Error Handling] to catch such internal errors and then decide how to pass this on to your users:
+
+[source, typescript, indent=0]
+----
+import { ApolloServerErrorCode } from '@apollo/server/errors';
+
+if (error.extensions?.code === ApolloServerErrorCode.GRAPHQL_PARSE_FAILED) {
+  // respond to the syntax error
+
+} else if (error.extensions?.code === "MY_CUSTOM_CODE") {
+  // do something else
+
+}
+----
+
+
+=== Limit query depth
+
+Limiting query depth disallows potentially harmful queries such as the following recursive query:
+
+[source, graphql, indent=0]
+----
+query {
+  order(id: 42) {
+    products {
+      order {
+        products {
+          order {
+            products {
+              order {
+                # and so on...
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+This can be achieved with a package such as link:https://www.npmjs.com/package/graphql-depth-limit[graphql-depth-limit]:
+
+[source, typescript, indent=0]
+----
+import depthLimit from 'graphql-depth-limit'
+import express from 'express'
+import graphqlHTTP from 'express-graphql'
+import schema from './schema'
+ 
+const app = express()
+ 
+app.use('/graphql', graphqlHTTP((req, res) => ({
+  schema,
+  validationRules: [ depthLimit(10) ]
+})))
+----
 
-Security best practices
 
-link:https://neo4j.com/docs/operations-manual/current/authentication-authorization/manage-privileges/[Role-based access control]
+=== Paginate list fields
+
+Returning large query result lists can negatively affect server performance.
+For example, a query like the following would return a siginificant number of nodes:
+
+[source, graphql, indent=0]
+----
+query {
+  order(first: 1000) {
+    orderID
+    products(last: 100) {
+      productName
+      productCategory
+    }
+  }
+}
+----
+
+To avoid this, you can cap the input number directly in your resolvers, for example like this:
+
+[source, graphql, indent=0]
+----
+// example
+----
+
+Alternatively, use a library such as link:https://github.com/joonhocho/graphql-input-number[graphql-input-number]:
+
+[source, typescript, indent=0]
+----
+import {
+  GraphQLInputInt,
+  GraphQLInputFloat,
+} from 'graphql-input-number';
+
+const argType = GraphQLInputInt({
+  name: 'OneToNineInt',
+  min: 1,
+  max: 9,
+});
+
+new GraphQLObjectType({
+  name: 'Query',
+  fields: {
+    input: {
+      type: GraphQLInt,
+      args: {
+        number: {
+          type: argType,
+        },
+      },
+      resolve: (_, {number}) => {
+
+        // 'number' IS AN INT BETWEEN 1 to 9.
+
+      };
+    },
+  },
+});
+----
+
+
+=== Rate-limit your API
+
+Rate-limiting an API means setting an upper bound to how many requests a client can send in a certain amount of time or how costly those requests may be.
+There is more than one approach.
+Several are outlined in the following sections.
+
+
+==== Rate limit scores
+
+Refer to GitHub's link:https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users[Rate limits for the REST API].
+
+
+==== Query cost points
+
+The link:https://shopify.dev/docs/api/usage/limits#the-leaky-bucket-algorithm[leaky bucket algorithm].
+
+==== Query cost analysis
+
+link:https://github.com/pa-bru/graphql-cost-analysis[raphql-cost-analysis]
+
+
+=== Use timeouts
+
+To prevent the API from not responding or falling victim to denial of service attacks, it is feasible to make use of timeouts.
+This way, subsequent queries will not be blocked by a long-running previous query.
+
+There are many ways and places to use timeouts.
+Here are a few examples.
+
+// examples
+
+
+=== Validate user input
+
+User input may potentially be malicious, for example, it could contain code snippets which get executed when running queries against the database.
+
+Follow the input validation methods summarized in the link:https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#input-validation[OWASP Cheat Sheet Series].
+
+// Examples?
+
+
+
+== Further reading
+
+Neo4j  has a link:https://neo4j.com/docs/operations-manual/current/authentication-authorization/manage-privileges/[Role-based access control] mechanism that can be leveraged to increase security even further.