Merge changes from master into 2.0.0

docs/asciidoc/auth/setup.adoc

@@ -1,67 +1,119 @@
 [[auth-setup]]
 = Setup
 
-The auth implementation uses JWT tokens. You are expected to pass a JWT into the request. The accepted token type should be Bearer where the header should be authorization;
+== Configuration
 
-[source]
-----
-POST / HTTP/1.1
-authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJyb2xlcyI6WyJ1c2VyX2FkbWluIiwicG9zdF9hZG1pbiIsImdyb3VwX2FkbWluIl19.IY0LWqgHcjEtOsOw60mqKazhuRFKroSXFQkpCtWpgQI
-content-type: application/json
-----
+If you want the Neo4j GraphQL Library to perform JWT decoding and verification for you, you must pass the configuration option `jwt` into the `Neo4jGraphQL` or `OGM` constructor, which has the following arguments:
 
-== Config
+- `secret` - The secret to be used to decode and verify JWTs
+- `noVerify` (optional) - Disable verification of JWTs, defaults to _false_
+- `rolesPath` (optional) - A string key to specify where to find roles in the JWT, defaults to "roles"
 
-Auth centric values on the Config object passed to Neo4jGraphQL or OGM.
+The simplest construction of a `Neo4jGraphQL` instance would be:
 
-.Auth Config
-|===
-|Variable | Usage
-
-|`secret`
-| Specify JWT secret
-
-|`noVerify`
-| Disable the verification of the JWT
+[source, javascript]
+----
+const neoSchema = new Neo4jGraphQL({
+    typeDefs,
+    config: {
+        jwt: {
+            secret
+        }
+    }
+});
+----
 
-|`rolesPath`
-| Specify where on the JWT the roles key is
-|===
+It is also possible to pass in JWTs which have already been decoded, in which case the `jwt` option is _not necessary_. This will be covered in the section <<auth-setup-passing-in>>.
 
-== Server Construction
+=== Auth Roles Object Paths
+If you are using a 3rd party auth provider such as Auth0 you may find your roles property being nested inside an object:
 
-*An object key `req` or `request` must be passed into the context before you can use auth.* This object must contain request headers, including the authorization header containing the JWT for each request.
+[source, json]
+----
+{
+    "https://auth0.mysite.com/claims": {
+        "https://auth0.mysite.com/claims/roles": ["admin"]
+    }
+}
+----
 
-Here is an example using Apollo Server:
+In order to make use of this, you must pass it in as a "dot path" into the `rolesPath` option:
 
 [source, javascript]
 ----
 const neoSchema = new Neo4jGraphQL({
     typeDefs,
     config: {
         jwt: {
-            secret
+            secret,
+            rolesPath: "https://auth0.mysite.com/claims\\.https://auth0.mysite.com/claims/roles"
         }
     }
 });
+----
+
+[[auth-setup-passing-in]]
+== Passing in JWTs
+
+If you wish to pass in an encoded JWT, this must be included in the `Authorization` header of your requests, in the format:
+
+[source]
+----
+POST / HTTP/1.1
+authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJyb2xlcyI6WyJ1c2VyX2FkbWluIiwicG9zdF9hZG1pbiIsImdyb3VwX2FkbWluIl19.IY0LWqgHcjEtOsOw60mqKazhuRFKroSXFQkpCtWpgQI
+content-type: application/json
+----
 
+Note the string "Bearer" before the inclusion of the JWT.
+
+Then, using Apollo Server as an example, you must include the request in the GraphQL context, as follows (using the `neoSchema` instance from the example above):
+
+[source, javascript]
+----
 const server = new ApolloServer({
     schema: neoSchema.schema,
     context: ({ req }) => ({ req }),
 });
 ----
 
-We expect there to be a `headers` key within either a `req` or `request` object in the context. If for example, you are using `apollo-server-lambda` to host a GraphQL API as a lambda function, the context function will have an `event` object which will need to be renamed to `req`. For example:
+Note that the request key `req` is appropriate for Express servers, but different middlewares use different keys for request objects. You can more details at https://www.apollographql.com/docs/apollo-server/api/apollo-server/#middleware-specific-context-fields.
+
+=== Decoded JWTs
+
+Alternatively, you can pass a key `jwt` of type `JwtPayload` into the context, which has the following definition:
+
+[source, typescript]
+----
+// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+interface JwtPayload {
+    [key: string]: any;
+    iss?: string | undefined;
+    sub?: string | undefined;
+    aud?: string | string[] | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    jti?: string | undefined;
+}
+----
+
+_Do not_ pass in the header or the signature.
+
+For example, you might have a function `decodeJWT` which returns a decoded JWT:
 
 [source, javascript]
 ----
+const decodedJWT = decodeJWT(encodedJWT)
+
 const server = new ApolloServer({
     schema: neoSchema.schema,
-    context: ({ event }) => ({ req: event }),
+    context: { jwt: decodedJWT.payload },
 });
 ----
 
-== `rules`
+== `@auth` directive
+
+=== `rules`
 
 You can have many rules for many operations. We fall through each rule, on the corresponding operation, until we find a match. On no match found, an error is thrown. You can think of rules as a big OR.
 
@@ -74,9 +126,9 @@ You can have many rules for many operations. We fall through each rule, on the c
 ])
 ----
 
-== `operations`
+=== `operations`
 
-Operations is an array, you can re-use the same rule for many operations.
+Operations is an array which allows you to re-use the same rule for many operations.
 
 [source, graphql]
 ----
@@ -86,22 +138,18 @@ Operations is an array, you can re-use the same rule for many operations.
 ])
 ----
 
-> The absence of an `operations` argument will imply all operations
+NOTE: Note that the absence of an `operations` argument will imply _all_ operations.
 
-Many different operations can be called in one query take the below mutation;
+Many different operations can be called at once, for example in the following Mutation:
 
 [source, graphql]
 ----
 mutation {
     createPosts(
         input: [
             {
-                content: "I like GraphQL"
-                creator: {
-                    connect: {
-                        where: { node: { id: "user-01" } }
-                    }
-                }
+                content: "I like GraphQL",
+                creator: { connect: { where: { id: "user-01" } } }
             }
         ]
     ) {
@@ -112,44 +160,16 @@ mutation {
 }
 ----
 
-In the above example; First we do a `create` operation then we do a `connect` operation.
+In the above example, we perform a `CREATE` followed by a `CONNECT`, so our auth rule must allow our user to perform both of these operations.
 
-The full list of operations are;
+The full list of operations are:
 
-1. read - `MATCH`
-2. create - `CREATE`
-3. update - `SET`
-4. delete - `DELETE`
-5. connect - `MATCH` & `MERGE`
-6. disconnect - `MATCH` & `DELETE`
-
-
-== Auth Roles Object Paths
-If you are using 3rd party Auth solutions such as Auth0 you may find your roles property being nested inside an object;
-
-[source, json]
-----
-{
-    "https://auth0.mysite.com/claims": {
-        "https://auth0.mysite.com/claims/roles": ["admin"]
-    }
-}
-----
-
-Specify the key at construction:
-
-[source, javascript]
-----
-const neoSchema = new Neo4jGraphQL({
-    typeDefs,
-    config: {
-        jwt: {
-            secret,
-            rolesPath: "https://auth0.mysite.com/claims\\.https://auth0.mysite.com/claims/roles"
-        }
-    }
-});
-----
+- read - `MATCH`
+- create - `CREATE`
+- update - `SET`
+- delete - `DELETE`
+- connect - `MATCH` & `MERGE`
+- disconnect - `MATCH` & `DELETE`
 
 == Auth Value Plucking
 
@@ -158,70 +178,51 @@ const neoSchema = new Neo4jGraphQL({
 
 == Auth Custom Resolvers
 
-You cant put the auth directive on a custom resolver. We do make life easier by injecting the auth param into it. It will be available under the `context.auth` property;
+You can't use the `@auth` directive on a custom resolver, however, we do make life easier by injecting the auth parameter into it. It will be available under the `context.auth` property. For example, the following custom resolver returns the `sub` field from the JWT:
 
 [source, javascript]
 ----
-const { Neo4jGraphQL } = require("@neo4j/graphql")
-const neo4j = require("neo4j-driver");
-const { ApolloServer } = require("apollo-server")
-
 const typeDefs = `
-    type User {
-        id: ID!
-        email: String!
-        password: String!
-    }
     type Query {
         myId: ID!
     }
 `;
 
-const driver = neo4j.driver(
-    "bolt://localhost:7687",
-    neo4j.auth.basic("admin", "password")
-);
-
 const resolvers = {
     Query: {
         myId(root, args, context) {
             return context.auth.jwt.sub
         }
     }
 };
-
-const neoSchema = new Neo4jGraphQL({ typeDefs, resolvers, config: { jwt } });
-
-const server = new ApolloServer({
-    schema: neo4jGraphQL.schema,
-    context: ({ req }) => ({ req, driver }),
-});
-
-server.listen(4000).then(() => console.log("online"));
 ----
 
 == Auth on `@cypher`
 
-You can put the `@auth` directive on a field with the `@cypher` directive. Functionality like allow and bind will not work but you can still utilize `isAuthenticated` and `roles`.
+You can put the `@auth` directive on a field with the `@cypher` directive. Functionality like `allow` and `bind` will not work but you can still utilize `isAuthenticated` and `roles`. Additionally, you don't need to specify operations for `@auth` directives on `@cypher` fields.
+
+The following example uses the `isAuthenticated` rule to ensure a user is authenticated, before returning the `User` associated with the JWT:
 
 [source, graphql]
 ----
 type User @exclude {
     id: ID
     name: String
 }
+
 type Query {
-    users: [User] @cypher(statement: "MATCH (a:User) RETURN a") @auth(rules: [{ isAuthenticated: true }])
+    me: User @cypher(statement: "MATCH (u:User { id: $auth.jwt.sub }) RETURN u") @auth(rules: [{ isAuthenticated: true }])
 }
 ----
 
-Notice you don't need to specify operations for `@auth` directives on `@cypher` fields.
+In the following example, the current user must have role "admin" in order to query the `history` field on the type `User`:
 
 [source, graphql]
 ----
 type History @exclude {
     website: String!
 }
+
 type User {
     id: ID
     name: String

docs/asciidoc/type-definitions/relationships.adoc

@@ -119,11 +119,11 @@ We then need to create the actor in our example, and connect them to the new Mov
 [source, graphql]
 ----
 mutation CreateActor {
-    createActors(input: [
+    createPeople(input: [
         {
             name: "Tom Hanks"
             born: 1956
-            movies: {
+            actedInMovies: {
                 connect: {
                     where: {
                         node: { title: "Forrest Gump" }

packages/graphql/package.json

@@ -41,7 +41,7 @@
         "@types/faker": "5.1.7",
         "@types/is-uuid": "1.0.0",
         "@types/jest": "26.0.8",
-        "@types/jsonwebtoken": "8.5.0",
+        "@types/jsonwebtoken": "^8.5.4",
         "@types/node": "14.0.27",
         "@types/pluralize": "0.0.29",
         "@types/randomstring": "1.1.6",

packages/graphql/src/classes/Neo4jGraphQL.ts

@@ -137,7 +137,9 @@ class Neo4jGraphQL {
 
             context.resolveTree = getNeo4jResolveTree(resolveInfo);
 
-            context.jwt = getJWT(context);
+            if (!context.jwt) {
+                context.jwt = getJWT(context);
+            }
 
             context.auth = createAuthParam({ context });
         });

packages/graphql/src/translate/create-auth-and-params.ts

@@ -67,6 +67,10 @@ function createAuthPredicate({
     }
     const { jwt } = context;
 
+    if (!jwt) {
+        throw new Error("Can't generate auth predicate - no JWT in context");
+    }
+
     const result = Object.entries(rule[kind] as any).reduce(
         (res: Res, [key, value]) => {
             if (key === "AND" || key === "OR") {

packages/graphql/src/translate/create-auth-param.ts

@@ -34,11 +34,7 @@ function createAuthParam({ context }: { context: Context }) {
 
     const jwtConfig = context.neoSchema.config?.jwt;
 
-    if (!jwtConfig) {
-        return param;
-    }
-
-    if (jwtConfig.rolesPath) {
+    if (jwtConfig?.rolesPath) {
         param.roles = dotProp.get(jwt, jwtConfig.rolesPath);
     } else if (jwt.roles) {
         param.roles = jwt.roles;