Forem: Achraf

Announcing GraphQL Security for all Developers

Achraf — Tue, 28 Jun 2022 15:32:47 +0000

When building production-ready applications, we developers rarely invest time on implementing proper security practices.

What do you do first?

logging?
analytics?
CI/CD?
e2e testing?

Security should be up there on the list!

Think about it: would you rather have your database hacked or you application down for a couple of hours because of an error you haven't handled yet?

That happened to Tristan - the cofounder of Escape.tech. One of his database got leaked in the darknet 😱

And like many others who were once convinced that security was actually a priority, he couldn't find a solution that met the standards of modern devtools.

That was the beginning of Escape's GraphQL Security Monitoring Platform: reinventing the security tools for all developers - knowledgeable about security or not!

Think about CI integration, Slack/Discord notifications, modern, readable and actionable dashboard, you name it.

This is just the beginning but we are thrilled to finally roll out general availability 📣

Head over to app.escape.tech/register to start a 14-day free trial.

How to Handle GraphQL Errors for a Secure API

Achraf — Wed, 25 May 2022 15:05:53 +0000

Error messages in GraphQL are rarely considered as a security matter... yet they 100% should!

The default error messages are way too verbose. They could disclose information about your internal infrastructure such as what database you use, or worse, leak your secret keys.

Error messages give direct feedback for hackers to run a fuzzy search (finding patterns through trial and error) on your API until they find vulnerabilities.

For example, if the error message contains information about the database schema and the query used to retrieve user information, a hacker could figure out a way to perform a SQL injection and get the information of EVERY user in your database, bypassing any access control 🤯

Handling error messages properly is one of the most essential step of building a secure GraphQL API (see 9 GraphQL security best practices).

Let's see how GraphQL errors work, how to mask verbose messages but also how to create your own custom errors by leveraging the flexible GraphQL spec.

This was originally posted on blog.escape.tech

How errors work in GraphQL

GraphQL errors are fundamentally different from REST errors. You no longer rely on status codes and status texts.

According to the latest spec, the response of a GraphQL endpoint should always contain either the data field or the errors field, and in some cases, both:

As you can see above, an error object has the following fields:

message: the error message - if you throw an error in the resolver, its message will appear here
locations: contains the line and column (starting from 1) of the syntax element that is concerned with the error (in the example above, this is the "a" of author. The column is 5 for the indent but would be 1 if we remove the indent in the query)
path: the path of the response field which experienced the error (firstPost → author).

Additionally, you can add the extensions field which is a map containing any custom field you see fit:

Note: it is recommended to use the extensions field for custom fields even though no error will be thrown when doing otherwise.

The code field of the extensions is usually implemented by the framework. For example, here are the default codes in Apollo:

GRAPHQL_PARSE_FAILED (SyntaxError)
GRAPHQL_VALIDATION_FAILED (ValidationError)
BAD_USER_INPUT (UserInputError)
UNAUTHENTICATED (AuthenticationError)
FORBIDDEN (ForbiddenError)
PERSISTED_QUERY_NOT_FOUND (PersistedQueryNotFoundError)
PERSISTED_QUERY_NOT_SUPPORTED (PersistedQueryNotSupportedError)
INTERNAL_SERVER_ERROR (None)

We’ll see below how you can define your own custom error at the end.

How to mask sensitive information and stack traces

Back to the initial problem: not giving up sensitive information to consumers of your API.

The errors in GraphQL are very comprehensive: they tell you what broke, where it broke both in the query and in your code. That is great for developer experience, but clearly not intended for the end-user.

Information like the stacktrace - the path tracing all the way back to the breaking point in your code - are usually found in the logs, not in the error message.

The solution to catch these default errors before they get sent to the end-user is to use a custom formatError function in your GraphQL server (framework agnostic), to:

log the error internally for debugging,
update the error that you don’t want to expose to clients in production,
send a user-friendly error.

// api.js

formatError: (err) => {
    // 1. Log the error for internal debugging
    logger(err, req, Date.now())

    // 2. Update the error message
    if (err.message.includes('Database Error')) {
        err.message = 'Internal server error'
    }

    // 3. Return the error message
    return {
        ...err
        stack: process.env.NODE_ENV === 'production' ? undefined : err.stack
    }
}

Cool, now our API is not going to betray us.

But we can do more.

Let’s see how we can leverage the GraphQL spec we saw above to create our own custom error.

How to write custom errors

There are three key components we can play with to build custom errors:

the message: giving more context to the user, eg. "password should have at least 6 characters",
the extensions code: an optional field, but a good practice in API error design to easily classify the different types of errors in the frontend (eg. with ⚠️ WARNING, ❌ ERROR or ℹ️ INFO callouts)
any other extensions field: this is where you can get creative and add any extra context, eg. the field name that cause an error in the case of a form submission.

Let's run through an example with real code!

The first step is to extend the GraphQLError class to create a custom error:

import {GraphQLError, GraphQLErrorExtensions} from 'graphql'

class InputValidationError extends GraphQLError {
    extensions: GraphQLErrorExtensions;
    constructor(message: string, field: string) {
        super(message);
        this.extensions = {
            statusCode: 500,
            code: "INPUT_VALIDATION_FAILED",
            field,
        };
    }
}

⚠️ The latest spec highly recommend putting any custom fields under extensions.

Now you can throw the error where necessary:

post: (_parent:null, {id}: QueryPostArgs, context: Context) => {
    if(id >= context.db.posts.length) {
        throw new InputValidationError("Index out of range", "id")
    }
    // Fetch and return the corresponding post
}

Finally, make sure to return the extensions field if you use a custom formatError function:

formatError: (err) => {
    return {
        message: err.message,
        extensions: err.extensions, // this is already returned by default
        stack: process.env.NODE_ENV === 'production' ? undefined : err.stack
    }
}

And voila!

Alternatively, most GraphQL frameworks have a GraphQLError wrapper that lets you throw custom errors on the fly without writing new ones.

import {ApolloError} from 'apollo-server-errors

throw new ApolloError('Index out of range', 'INPUT_VALIDATION_FAILED', {field: 'id'})

GraphQL Security

Error messages are just one of many GraphQL vulnerabilities. If you need an in-depth scan running dozens of security tests on your GraphQL endpoints, you should try out Escape!

Fullstack, Type safe application with React and GraphQL codegen

Achraf — Tue, 24 May 2022 09:23:05 +0000

There are 2 approaches to defining your schema in GraphQL: schema-first or code-first.

In schema-first, you write .graphql (or .gql) files, while in code-first you write resolver-like types in Javascript (or Typescript).

Now, if you're using Typescript, you might find yourself having to write types again for other purposed, your resolvers for example. That can quickly become a problem, not only because it feels like a waste of time, but also because it makes it that much harder to maintain. If your codebase and your schema grow in complexity, and you have a whole team working on it, a small type definition update can cause a huge mess!

If we look at a fullstack Typescript application, we have to duplicate our type definition at least 3 times:

in the schema file
in the backend resolvers
in the frontend for the GraphQL client
BONUS: for the ORM

Enters GraphQL code generator

GraphQL code generator is the solution to that problem: you write your schema file and the rest gets generated automatically!

Now let's see how it actually works 👇

This was originally posted on blog.escape.tech

Example: Building a (over-engineered) blog

I know you love using overly complicated tools to build your blog so let's just do that cause why not 🤷‍♂️

Here are the graph relations:

As mentioned above, with this stack we would normally have to:

write our type definitions in a schema file
write types for our backend resolvers
write model definitions for our ORM (using Prisma in this example)
write types for React Query on the frontend

Phew, that's a lot of effort!

Now imagine if in 4 months we decide to add tags to our posts. We would have to go through the same 4 steps to update the types!

But with GraphQL codegen, we have one single source of truth: the schema file!

Alright, enough teasing, let's jump into the code!

Backend with Express and Express GraphQL

If you start from scratch, you can simply install Express, Express GraphQL and Typescript (+ some other utilities):

npm install express express-graphql @graphql-tools/schema cors import-graphql-node
npm install -D @types/express

Then we can very easily setup the server:

import "import-graphql-node"
import express from "express"
import {GraphQLHTTP} from "express-graphql"
import cors from "cors"
import {makeExecutableSchema} from "@graphql-tools/schema"
import * as typeDefs from "./schema.graphql"


const app = express()
app.use(cors())

const schema = makeExecutableSchema({ typeDefs })

app.use("/", GraphQLHTTP({
  context: {db},
  schema: schema,
  graphql: true
}))

Note here that I'm using import-graphql-node to import .graphql files.

Checkout the repo for more details.

Frontend with React and React Query

We can bootstrap a React and Typescript project very easily with the Create React App boilerplate:

npx create-react-app client --template typescript

Next, let's add React Query:

npm install react-query

and set it up:

import "./style.css"
import React from "react"
import ReactDOM from "react-dom"
import App from "./App"
import {QueryClient, QueryClientProvider} from "react-query"

const client = new QueryClient()

ReactDOM.render(
  <React.StrictMode>
    <QueryClientProvider client={client}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>,
  document.getElementById("root")
)

Setting up GraphQL codegen

Setting up GraphQL codegen is super easy! First, install the CLI:

npm install -D @graphql-codegen/cli

Then launch the initialisation proces:

npx graphql-codegen init

This will prompt a series of questions to set it up for your needs. It's not super important as it's very easy to update the configuration later.

Here is (approximately) the config file that you'll end up with:

Let's go over each field to explain what it does and configure them exactly how we need it.

Schema

This should point to your schema definition. By default, it uses your GraphQL endpoint, but in general it's easier to put the path to your actual schema file:

schema: "server/schema.graphql"

Documents

This is part of the frontend configuration. Documents should point to some schema definition of your operations (queries and mutations). Here's an example:

query AllPosts {
  allPosts {
    id
    author {
      displayName
      picture
    }
    title
    publishedAt
    content
    comments {
      id
      text
      username
    }
  }
}

documents: "client/**/*.graphql"

The React Query Plugin

The installation process didn't gave us an option to add React Query. But we can easily integrate it thanks to the huge pugin hub!:

Fist, we need to install the right plugin:

npm install -D @graphql-codegen/typescript-react-query

Then we configure it in codegen.yml configuration file by adding it to the plugins of the frontend section:

generates:
  client/src/generated.tsx:
    documents: "client/**/*.graphql" # where the queries are written
    plugins:
      - "typescript"
      - "typescript-operations"
      - "typescript-react-query"

What's amazing about this plugin is that it's also going to take care of configuring the React Query client (endpoint, fetcher, etc) so that we can just use simple hooks, eg. useGetAllPostsQuery()

In order to make this work, we need to provide some configuration such as the GraphQL endpoint, but we can also add other things, e.g, an authorization header (with environment variables, how cool is that!):

plugins:
    - "typescript"
    - "typescript-operations"
    - "typescript-react-query"
config:
    fetcher:
        endpoint: "process.env.API_URI"
        fetchParams:
            headers:
                Content-Type: "application/json"
                Authorization: "Bearer process.env.HEADER_AUTH_TOKEN"

Putting everything together

We are now ready to go!

To generate the types, we can simply run the command:

npm run codegen

Use the generated types in the backend resolvers:

import type {QueryAuthorArgs} from "/generated"
import type {Context} from "./context"

const resolvers = {
    Query: {
        author: (
            _parent: null,
            { id }: QueryAuthorArgs,
            context: Context) => {
            // Do what you got to do to get the author...
        }
    }
    Mutation: {
        createPost: (
      _parent: null,
      { input }: MutationCreatePostArgs,
      ctx: Context
    ) => {
      // Save the post in the database!
    },
    }
}

And use the generated hooks in the frontend like so:

import { useAllPostsQuery } from "./generated";

function App() {
  const { status, error, data } = useAllPostsQuery();
  ...

Conclusion

If you decide to go down the code-first route (blue pill) good for you, but many teams decide to pick a schema-first approach to build their GraphQL API, and even though it's a great option, it can quickly become a burden to test and maintain your code.

But fortunately, graphql-codegen is an elegant solution to fix that problem of code duplication, making the schema file your single source of truth!

GraphQL Security

In one of our previous post, we shared how every GraphQL framework has zero security configured by default. Most GraphQL APIs are therefore subject to the most basic attacks (brute force, DoS, etc).

To compensate this lack of security in the GraphQL ecosystem, we built a quick scan that will get you started im your journey to shipping bullet proof applications!

You can run a dozen security scans on your GraphQL endpoint for free - no signup - at graphql.security

8 Steps to Become a GraphQL Expert

Achraf — Thu, 19 May 2022 12:07:01 +0000

The adoption of GraphQL is growing like crazy. And I love it!
But the learning curve is steep and getting started can be overwhelming.
In fact, there are many misconceptions about GraphQL - like people believing it’s an SQL alternative that speaks directly to the database...

GraphQL is a query language that rethinks the way a client interacts with the server. So you can think of it as a layer between a server and a client, not a query language for your database.

The number one advantage of GraphQL APIs is the ability to get only what you ask for. In practice, it means 2 things:

you get less unnecessary data (maybe you just want ids of your users, not all their information),
you can combine several queries in a single request (eg. get all your users and their comments in a single query instead of two).

The goal of this post is not to go explain every GraphQL concepts, but rather, to give you a list of steps and resources you can go through to step up your GraphQL game 🆙

This was originally posted on blog.escape.tech

Here are the 8 steps to go from newcomer to shipping production-ready GraphQL APIs 👇

Step 1 - Schema Definition Language

GraphQL introduced a query language - which lead people to think it was a SQL alternative. This new language let backend developers describe their data and clients to write efficient queries to ask for exactly the data they need.

Therefore this language appears in 2 places:

in the schema files describing the data - this acts as a contract between the backend and the frontend developers;
in the HTTP requests from the client to query data.

# server - describing resources
type User {
    id: ID!
    username: String!
    email: String!
    comments: [Comment]
}

type Comment {
    id: ID!
    text: String!
    author: User!
    createdAt: Date!
    replyTo: Comment
}

# client - querying resources
query UserWithComments($id: ID!) {
  user(id: $id) {
    username
        comments {
            id
            text
            createdAt
        }
    }
}

The second big point for GraphQL is that it’s a strongly-typed language. That means easier to maintain, test and debug, fewer bugs, and better (automated) documentation.

The language comes with the usual built-in types - Int, Float, String, Boolean - along with some modifiers to specify if the field is required (!) or a list ([String]) - (checkout this cool cheatsheet for more details).

On the client side, 3 operations are supported:

queries allow you to ask for resources (like GET requests),
mutations allow you to modify resources (like POST, PUT, PATCH and DELETE requests),
subscriptions allow you to establish a 2-sided connection for real-time interactions (with websockets).

Step 2 - GraphQL servers

As we said above, GraphQL is an abstraction layer that stands between the incoming HTTP requests and the controllers.

This layer is responsible for translating the query, calling the corresponding resolvers to get the requested resources, and formatting the output following the same GraphQL structure.

Happily, we have some libraries to take care of all that heavy lifting for us! They are called GraphQL engines or servers. These libraries are frameworks that let you create a GraphQL API in just a few lines of code - here’s an example with Apollo in NodeJS:

const { ApolloServer, gql } import 'apollo-server'

const typeDefs = gql`
  type Query {
    hello: String
  }
`
const resolvers = {
  Query: {
    hello: () => {
        return 'Hello World!';
    }
  }
};

const server = new ApolloServer({typeDefs, resolvers})

server.listen(4000)

Checkout this official page for a comprehensive list of servers for every language.

Step 3 - GraphQL Clients

We’ve covered how to handle incoming requests. How about sending requests to the API?

This should be the first step really because GraphQL has been designed with consumers of the API in mind. It makes the life of frontend developers easier:

don’t bother finding the right endpoint, there’s only one;
just ask what you want and we’ll figure out how to mix, match and filter to give you just what you need.

What’s cool about it, is that you don’t have to draw complex libraries to manage requests. You can. But you don’t have to.

Here’s what the first request above looks like with fetch - the built-in browser API to send HTTP requests:

// app.ts
const query = `query UserWithComments($id: ID!) {
    user(id: $id) {
        username
        comments {
            id
            text
            createdAt
        }
    }
}`
const variables = { id: 0 }
fetch('<https://example.com/api/graphql>',
    method: 'POST',
    headers: {'Content-Type': 'application/json'}
    body: JSON.stringify({query, variables})
)

Checkout the official website for a comprehensive list of clients.

Step 4 - Extending the language with Fragments, Unions and Directives

My favourite part about GraphQL is how flexible it is! The language is simple enough to get you started but offers some powerful features like Fragments, Unions and Directives to up your game 🆙

These features help you set up complex access control rules, fully-typed error handling, and much more. Here are some quick videos about each of these topics:

Talking about error handling...

Step 5 - Error Handling

This is the annoying part, right? Well, it doesn’t have to be that way!

GraphQL errors have a clear structure defined in the spec and let you define your own custom errors. In development mode, you can easily enable the stack trace to see exactly where your errors come from.

https://spec.graphql.org/October2021/#example-8b658

Did you know that errors can be a huge security vulnerability? Checkout our previous post about handling errors from a security point of view

Do you know how to avoid breaking errors in production? Testing your code!

Step 6 - Testing

You didn’t think you could skip that part, did you?

Testing is an essential part of building reliable and scalable APIs. And because of the structural difference between REST and GraphQL, strategies for testing your APIs are going to be different.

describe('Queries', () => {
            let tester
            beforeAll(() => {
                tester = new EasyGraphQLTester(schemaCode)
            })
            test('Should get friends with a nested query', () => {
            const query = `
                query GET_FRIENDS($userId: ID!){
                    user(id: $userId) {
                        id
                        friends {
                            id
                        }
                    }
                }
            `
            tester.test(true, query, { userId: '0' })
        })
})

Checkout our previous post to learn how to test your GraphQL API, from unit tests to integration tests

The TLDR is:

you need to test every layer of your API: schema definition, operations (queries and mutations) and resolvers;
some great libraries help you isolate these different parts: linters help you test your type definitions and EasyGraphQL lets you test and execute queries without a running server;
resolvers are just functions so you can test them as usual.

Step 7 - Security

Yet another often neglected part of building product-ready APIs: security.

But it’s even more relevant for GraphQL!

Why? every GraphQL server library is vulnerable by default!

If you don’t take the time to secure your API, it’s dead simple to break it or worse, leak your users’ data.

Here’s another TLDR for you:

disable introspection and the GraphQL playground,
limit access control with authentication and authorization,
set a request timeout,
limit the rate of incoming requests,
limit the depth of queries,
limit requested resources with a cost analysis,
handle errors,
validate inputs,
use GraphQL over POST not GET requests.

Guess what? The community is fantastic and has built some amazing libraries and plugins to implement these steps in just a few lines of code!

Learn more in our previous post - 9 GraphQL Security Best Practices - and run a dozen security scan on your GraphQL API at graphql.security. It’s free. No account required. (we built it 😇)

Step 8 - Caching

If you want to scale your API and make it blazingly fast ⚡️ you’re gonna need to set up caching.

No, GraphQL doesn’t “break caching”! There are tons of solutions out there.

But first, we need to know what we’re talking about. There are two sides to the equation: client-side caching and server-side caching.

For client-side caching, you can use GraphQL client libraries like Apollo client which also handles caching.

For server-side caching, you have neat solutions like GraphCDN or plugins (eg. the envelop plugin with GraphQL Yoga)

Other resources

GraphQL is moving fast!

New tools, libraries and features pop up every week! Mastering the fundamental concepts is great, but keeping up to date will make you an expert and avoid some bad practices regarding performance, security, and maintainability.

Here are my favourite sources to learn and stay up to date:

GraphQL Weekly - the weekly newsletter of everything GraphQL. You get the top 3 posts of the week, 1 OSS news, 1 video and 1 event in your inbox every week.
Jamie’s short 5-min videos on very specific GraphQL topics.
The GraphQL subreddit and discord group to ask questions and stay up to date with the latest news.

How to write unit, integration and e2e tests for your GraphQL API

Achraf — Wed, 18 May 2022 12:15:45 +0000

GraphQL is becoming more and more popular to build amazing products with a modern stack, and that makes total sense (that’s the path we took at Escape as well 😎)

But as with any new technology, it comes with the downside of not having a lot of good resources.

So today, we address one of the most critical aspect: testing your GraphQL API!

This was originally posted on blog.escape.tech

Why bother testing?

Testing your API is important to make sure that the business logic of your software is running properly.

Writing tests will allow you to reveal bugs before they make it to production - which we absolutely want to avoid (especially if you deploy on Fridays 😬).

With tests, you can verify functionalities, reliability, performance, security, and all sorts of potential issues.

Finally, keeping a good testing coverage will ensure that future updates of your API are not breaking the frontend applications consuming it.

How is it different from REST?

The primary difference is that REST APIs have several endpoints to test, but in GraphQL you only have one (in most cases). Therefore, the structure of your tests will be different from the usual REST APIs.

Another important difference is that GraphQL is a strongly-typed language that makes it extremely convenient to detect bugs as you code, especially when working on a massive codebase.

These differences make testing REST and GraphQL APIs fundamentally different. Now let’s see how it actually works!

How to test GraphQL APIs

GraphQL APIs have 3 different layers to test:

schema: testing your type definitions,
operations: testing the definition of your queries, mutations and subscriptions (in isolation from the actual execution logic),
resolvers: testing the last bit, the Javascript functions that resolve the operations (queries, mutations and subscriptions)

Our Example

Let's build the next Facebook (such a boomer move...)

Our graph of entities is going to look something like this:

And our application will need features like sending a friend request (a mutation), and displaying a feed based on a users's friends' posts (a query - get latest posts from friends).

Github Repository

If you want to follow along, you can clone the repository here: https://github.com/achrafash/graphql-testing
and follow the instructions from the README file to install and run the project locally.

Testing schema

GraphQL is a strongly-typed language, which makes it very handy to detect errors directly from your IDE.

To validate our schema we can use two libraries:

eslint-plugin-graphql: a linter to extend our Eslint rules,
graphql-schema-linter: a CLI tool to validate our schema definition.

Here's how to install them:

npm i -D eslint-plugin-graphql graphql-schema-linter

Testing queries and mutations

You can start with basic, manual testing on GraphiQL. But at some point, automated tests are a must.

The best way to isolate your queries and mutations is to use EasyGraphQL Tester, a library to run your GraphQL code without firing up a server.

npm i -D easygraphql-tester

We are not yet looking at how we are going to execute these queries and mutations to get or modify data, just their definition:

name of the operation,
their arguments (name and type),
the returned type.

Here’s what it looks like:

describe('Queries', () => {
            let tester
            beforeAll(() => {
                tester = new EasyGraphQLTester(schemaCode)
            })

            test('Should get friends with a nested query', () => {
            const query = `
                query GET_FRIENDS($userId: ID!){
                    user(id: $userId) {
                        id
                        friends {
                            id
                            firstname
                            lastname
                        }
                    }
                }
            `
            tester.test(true, query, { userId: '0' })
        })
})

Testing resolvers

Resolvers are simply Javascript functions that we can test like any other Javascript code. Let’s go through an example with our resolver that gets the friends of a user:

it('Should get friends of user from their id', () => {
      const userId = 0
      const friends = getFriends(db, userId)
      expect(friends.length).toBe(1)
      expect(friends[0]).toHaveProperty('id')
      expect(friends[0]).toHaveProperty('firstname')
      expect(friends[0].firstname).toBe('Eduardo')
})

Integration tests

Now we can put it all together with an integration test to make sure that all the components - schema, the query, and the resolver - are working properly:

it('Should return friends of the user with given id', async () => {
        const query = `
            query GET_FRIENDS($userId: ID!) {
                user(id: $userId) {
                    id
                    friends {
                        id
                    }
                }
            }
        `
        const args = { userId: '0' }
        const result = await tester.graphql(query, undefined, { db }, args)

        expect(result.data.user.id).toBe(args.userId)
        expect(result.data.user.friends).toBeInstanceOf(Array)
        expect(result.data.user.friends).toContainEqual({ id: '1' })
})

E2E test

We’ve seen how to test the GraphQL part of our API, but we left off an important aspect of it: the HTTP server.

The frontend applications will consume our API through HTTP requests, and it wouldn’t be a proper API testing tutorial without covering that part as well.

This last part includes:

testing the request headers and body,
testing the response status and payload.

This time, we need a running server. We can use supertest, a library that does just that:

npm i -D supertest

Now we can use it to run our server and send HTTP requests in our tests:

const supertest = require('supertest')
const app = require('./app')

app.server = app.listen(5000)

describe('Server', () => {
    afterEach(() => app.server.close())

    it('Should listen to HTTP requests', (done) => {
        const userId = '0'
        request(app)
            .post('/graphql')
            .send({
                query: `{ user(id: ${userId}) { id, friends{ id } }  }`,
            })
            .set('Accept', 'application/json')
            .expect(200)
            .end((err, res) => {
                if (err) return done(err)
                expect(res.body && typeof res.body === 'object').toBe(true)
                expect(res.body).toHaveProperty('data')
                expect(res.body.data).toHaveProperty('user')
                expect(res.body.data.user).toHaveProperty('id')
                expect(res.body.data.user.id).toBe(userId)

                expect(res.body.data.user).toHaveProperty('friends')
                expect(res.body.data.user.friends).toContainEqual({ id: '1' })
                return done()
            })
    })
})

BONUS: Running tests in the CI/CD with Github Actions

Finally, a good practice is to run your tests in the CI/CD to make sure you don't deploy broken code to production. Github Actions are a quick and easy way to run your tests every time your push a new commit, and will break your pipeline if not all the tests are green ✅

name: Run tests
on: [push]
jobs:
    tests:
        name: Run tests
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v2

            - name: Install dependencies
              run: npm install
                        - name: Schema linter
                            run: npm run graphql:lint

            - name: Run tests
              run: npm run test

Conclusion

Let’s recap.

We saw why testing your app is not an option, and how you can test your GraphQL API:

test your schema with eslint-plugin-prettier and schema-graphql-linter,
test your operations with EasyGraphQL Tester
test your resolvers like you would with any standard function,
test end-to-end using supertest.

And if you want an in-depth security check of your GraphQL endpoint, head over to graphql.security to run a dozen of security scans. Completely free of charge, no login required.

Getting Started with GraphQL Security

Achraf — Wed, 30 Mar 2022 15:16:36 +0000

GraphQL has been adopted by the biggest platforms out there - Facebook, Twitter, Github, Pinterest, Walmart - big businesses that can’t compromise on security.
But even though GraphQL can be a very secure option for your API, it does not come secure out of the box. It’s actually quite the opposite: all doors are open even for the most novice hackers.
Plus, GraphQL has its own set of new considerations that, if you come from REST, you might have missed!

This was originally posted on Escape's blog

What’s the risk

The primary categories of attacks that you must absolutely protect your application from are:

injections (SQL, XSS, CCS, etc) — using unexpected/random inputs to crash your application or access private data
access control — too loose restrictions on queries and mutation allowing anybody to take actions without the necessary role
brute-force attacks — submitting a shit load of (leaked) credentials with the hope of guessing correctly
DoS (Denial of Service) — flooding your API to make it crash
CSRF — induce users to perform unwanted actions by simply clicking a malicious link to your API

Note that these attacks are so basic that they can be performed automatically and at scale. In other words, regardless of the success or domain of your application, you are prone to be the target of a script running on thousands of scraped API endpoints.

Fortunately, there are some very simple strategies you can adopt to protect your API. Read more to learn how you can implement them 👇

1. Introspection

Most attacks specific to GraphQL start from running an introspection — this is a built-in query that returns your whole data schema. Anyone can know exactly what are the valid queries and mutations of your API and send attacks accordingly until they find a breach.
This feature is enabled by default. If you can (private API) make sure that you disable it.
You can do it with your GraphQL framework (e.g. Apollo):

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: process.env.NODE_ENV !== 'production'
});

Or you can use a plugin like graphql-disable-introspection:

app.use("/graphql", bodyParser.json(), graphqlExpress({
    schema: myGraphQLSchema,
    validationRules: [NoIntrospection]
}));

Same thing goes with GraphiQL.

2. Limit Access control with Authorization and Authentication

Another classic API security concern is access control. In most applications, features are accessible based on your authentication status and your role (user, admin).
Not having the right authorization-check layer will expose private data and higher access features to unauthorized users, e.g. deleting an asset without the admin role.
In REST, we can use a simple middleware approach to protect all sub-routes of an API:

app.use('/api/admin', isAdmin())

In GraphQL, we can perform the same thing with the context hook:

const server = new ApolloServer({
    typeDefs,
    resolvers,
    context: async ({ req, res }) => {
        // Check authorization from the headers
        const authHeader = req.headers.authorization || '';
        const token = authHeader.replace('Bearer ', '');
        if (!token) {
            throw new Error('Unauthorized');
        }
        let user = null;
        try {
            user = await verifyJwt(token);
        } catch (e) {
            throw new Error('JWT verification failed');
        }
        // Add user to the context object
        return { user };
    }
});

But throwing an error at this stage would block EVERY unauthenticated request! You might have different queries/mutations with different levels of authentication/authorization.
You guessed it, it’s gonna happen at the resolver level. We can use a cleaner approach with a resolver middleware:

const server = new ApolloServer({
    typeDefs,
    resolvers,
    context: async ({ req, res }) => {
        // Check authorization from the headers
        const authHeader = req.headers.authorization || '';
        const token = authHeader.replace('Bearer ', '');
        if (!token) {
            return { user }
        }
        let user = null;
        try {
            user = await verifyJwt(token);
        } catch (e) {
            throw new Error('JWT verification failed');
        }
        // Add user to the context object
        return { user };
    }
});

// Authentication middleware
const authMiddleware = (next) => (parent, args, context) => {
    if(!context.user) {
        throw new Error("Unauthenticated")
    }
    return next(parent, args, context)
}

const resolvers = {
    Mutation: {
        deleteAsset: authMiddleware(async (parents, {{name, address}}, context) => {
            if (context.user && context.user.role !== "admin") {
                throw new ForbiddenError("Missing role")
            }
            const newAsset = {id: uuid(), name, address}
            context.db.assets.push(newAsset)
            return newAsset
        })
    }
}

Now that we’ve built the first layer of security (access control) the next type of attack are based on death by overload (DoS). Let’s go over different strategies that tackle the threat from different angles but combined together can make your API unshakable 💪

3. Timeout

The easiest strategy to defend your API against large (stress-inducing 😣) queries is to simply configure a maximum time to process a query.
This is actually not specific to GraphQL so it happens in your backend framework (example with Express):

const server = new ApolloServer({ typeDefs, resolvers });

const app = express();
server.applyMiddleware({ app });

app.listen(5000, () => {
    console.log(`Server running at http://localhost:5000`)
}).setTimeout(1000*60*10)

The advantage is that it doesn’t require prior knowledge about the incoming queries.
But, damage can already be done by the time you reach that limit. This is the final layer of protection if the strategies below fail to block evil queries 👹

4. Query Whitelisting

Another very generic - but efficient - strategy is to whitelist allowed queries. This way you know exactly what you’re going to get. As with timeout, this is a simple strategy that let you constrain the possibilities for hackers.
You can use persistgraphql by Apollo to auto-generate a list of approved queries at build time.
This might not work for you if you have a complex API, so let’s get fancier!

4. Depth Limiting

One of the specificities of GraphQL is nested queries. They can be awesome, but used excessively they can demand enormous processing resources and become a prison of your own making...
The advantage of this strategy is that a deep query will not even be executed, not putting any load on your server.
The advantage of this strategy - as opposed to timeout - is that a deep query will not even be executed, and thus will not put any load on your server.
You can use the very light graphql-depth-limit library to easily limit the depth of queries. First, check how deep you expect queries to be, and then set a maximum depth accordingly

app.use("/api", graphqlServer({validationRules: [depthLimit(10)]}))

Now, it can’t be perfect right?

Indeed, this strategy does not consider domain-specific queries that might be too expensive without using excessive depth.

So we are still exposed to DoS attacks...

5. Resource Limitations with Complexity Analysis

Resolving even a simple query can, in some cases, be very expensive. Maybe it requires running a big machine learning model or complex algorithms. The timeout above will help limit this effect but as we said above, the damage is already done.
The best way to approach this challenge is to run a complexity analysis (sometimes also called Cost Analysis).
The general idea is to allocate a number to each object returned as well as a maximum complexity limit for queries (see how Github is doing it for their GraphQL API)

There are some packages that might help you in case you need to go down that route. You can start with something simple like graphql-validation-complexity. If you need more control for different use cases you can checkout graphql-cost-analysis.

The limit of this strategy is the difficulty of implementing it. How do you even estimate the complexity of a query? and how do you keep these numbers up to date (scaling/changing infrastructures)?
This is a strategy that usually makes sense once you have implemented all of the above and need a more advanced approach to limiting expensive queries.

We’ve now dealt with large, dirty queries. But what if our attacker comes with a load of small ones - also known as the brute force attack!

6. Rate Limiting to block Brute Force attacks

Aaah Brute Force, the old kid on the block...
How it works: attackers use a list of 700M+ emails and 20M+ passwords (real ones that leaked, reported by Troy Hunt 😱) to hit your login mutation.

Fortunately, this also has an easy way out called rate limiting. If you limit the number of possible login submissions, this attack is (almost) obsolete.

Use the graphql-limit-plugin to specify this limit on your queries and mutations.
The best way to set it up is to set a large time window between queries/mutations when they are highly vulnerable (like a sign in) and a shorted one for less vulnerable queries/mutations. That way you only limit attackers and not your users.

7. Verbose Errors

Alright, we’ve gone a long way already. But don’t lower your guard, we’re not done yet!

By default, GraphQL is very talkative (like me 🤗). As developers, we love that! It helps us debug errors easily. But when running in production it might be a bit quick to give up sensible information
Uniqueness violation. duplicate key value violates unique constraint user_provider_token

The message might give out information about your database or worse your backend services like Elasticsearch. Again, this is really helpful if you’re the developer trying to figure out what’s going on, but pretty dangerous if it falls into the hand of someone more ill-intended.
The strategy here is not specific to GraphQL. You can use a middleware to wrap your whole server and proxy these too-expressive error messages:
instead, write them in your logs
replace them with more adapted messages:

app.use("/api", graphqlServer({validationRules: [depthLimit(10)]}))
// at the very end
app.use((err, req, res, next) => {
  // log the errors for debugging
    console.error(err.stack)
    // return a more user-friendly error
  res.status(500).send('Something broke!')
})

8. Injections

Another boomer attack that is also a threat for GraphQL is the category of injections.
Here’s a simple SQL injection to get user info from a simple (allowed) query. Here’s how someone could bypass your login and get all your users’ details

The best way to protect your API from injections is to use input validation for all incoming requests, write custom validators for domain-specific and more complex validations.

9. POST vs GET requests

Fiouuu! Alright last one!
GraphQL can be sent over GET and POST HTTP requests.
If you think it’s the same thing, that’s bad!!!
Here is a valid mutation over a GET request:
http://badgraphqlapi.com/graphql?mutation={...}&variables={...}&operation=...

Imagine I’m a bad guy, I can build a link that changes the email of an account. I can then put my email as the new value and put that on the web. Even though the mutation requires the user to be authenticated because this is a GET request, an authenticated user might just click without knowing the consequences... and BAM I have control over their account!

In some GraphQL frameworks like Apollo mutation can’t be done over GET requests but, as they say, trust but verify - make sure mutations can’t be performed over GET request with automated tests (learn how to test a GraphQL API).

Conclusion

Because of the paradigm shift introduced with GraphQL, it’s easy to forget the basic security practices when moving over to GraphQL. From similar patterns (authorization/authentication) to new considerations (disabling introspection, rate limiting, etc). Here is your checklist:

✅ Disable introspection (and GraphiQL)
✅ Authorization and authentication to limit access to your API
✅ Set a timeout
✅ Create a whitelist of queries
✅ Set a maximum depth limit of queries
✅ Setup a cost analysis to limit complex/expensive queries
✅ Set a maximum rate limit for requests
✅ Stop default verbose errors
✅ Add input validations

And if you want to run a security check of your GraphQL API, checkout graphql.security — a free quick scan looking for a dozen vulnerabilities.