From 1940d1a8c07891285eedf15e1795e535b9639db1 Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Fri, 26 Jul 2024 18:10:22 -0400 Subject: [PATCH 01/12] Add security and compatibility notes --- spec/GraphQLOverHTTP.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index e1b40e7..3be3c0a 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -745,3 +745,35 @@ payload is `application/json` then the client MUST NOT rely on the body to be a well-formed _GraphQL response_ since the source of the response may not be the server but instead some intermediary such as API gateways, proxies, firewalls, etc. + +# Additional Notes + +## Security + +In this specification, GET requests are not supported for mutations due to +security concerns. GET requests expose variables to logging mechanisms and +intermediaries due to the URL encoding of parameters, which can lead to +sensitive data being inadvertently logged. Furthermore, GET requests are +considered "basic requests" under CORS (Cross-Origin Resource Sharing), +meaning they bypass preflight checks that add a layer of security. + +On the other hand, using `application/json` for request bodies mandates a CORS +preflight request, adding a security layer by ensuring the client has explicit +permission from the server before sending the actual request. This is +particularly important in mitigating cross-site request forgery (CSRF) attacks. + +Additionally, supporting form data requests (`application/x-www-form-urlencoded` +or `multipart/form-data`) could pose significant security risks. Form data requests +may be vulnerable to CSRF and other attacks due to the lack of CORS preflight checks. +As a result, the use of form data for GraphQL queries or mutations is discouraged. + +For more detailed security considerations, please refer to [RFC 7231](https://tools.ietf.org/html/rfc7231), +[RFC 6454](https://tools.ietf.org/html/rfc6454), and other relevant RFCs. + +## Format Compatibility + +Supporting formats not described by this specification, such as XML or protobuf, +may conflict with future versions of this specification, as ongoing development +aims to standardize and ensure the security and interoperability of GraphQL over +HTTP. For this reason, it is recommended to adhere to the officially recognized +formats outlined here. From 0e15911cc8597c7cff7837c96e0fdc4e18ad68e5 Mon Sep 17 00:00:00 2001 From: Shane32 Date: Fri, 26 Jul 2024 18:15:07 -0400 Subject: [PATCH 02/12] Update formatting --- spec/GraphQLOverHTTP.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 3be3c0a..1021033 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -754,8 +754,8 @@ In this specification, GET requests are not supported for mutations due to security concerns. GET requests expose variables to logging mechanisms and intermediaries due to the URL encoding of parameters, which can lead to sensitive data being inadvertently logged. Furthermore, GET requests are -considered "basic requests" under CORS (Cross-Origin Resource Sharing), -meaning they bypass preflight checks that add a layer of security. +considered "basic requests" under CORS (Cross-Origin Resource Sharing), meaning +they bypass preflight checks that add a layer of security. On the other hand, using `application/json` for request bodies mandates a CORS preflight request, adding a security layer by ensuring the client has explicit @@ -763,11 +763,13 @@ permission from the server before sending the actual request. This is particularly important in mitigating cross-site request forgery (CSRF) attacks. Additionally, supporting form data requests (`application/x-www-form-urlencoded` -or `multipart/form-data`) could pose significant security risks. Form data requests -may be vulnerable to CSRF and other attacks due to the lack of CORS preflight checks. -As a result, the use of form data for GraphQL queries or mutations is discouraged. +or `multipart/form-data`) could pose significant security risks. Form data +requests may be vulnerable to CSRF and other attacks due to the lack of CORS +preflight checks. As a result, the use of form data for GraphQL queries or +mutations is discouraged. -For more detailed security considerations, please refer to [RFC 7231](https://tools.ietf.org/html/rfc7231), +For more detailed security considerations, please refer to +[RFC 7231](https://tools.ietf.org/html/rfc7231), [RFC 6454](https://tools.ietf.org/html/rfc6454), and other relevant RFCs. ## Format Compatibility From 9d9bef959caa32498150c42bfd3217a089fa719a Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Fri, 26 Jul 2024 18:16:57 -0400 Subject: [PATCH 03/12] Update GraphQLOverHTTP.md --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 1021033..6832a7f 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -774,7 +774,7 @@ For more detailed security considerations, please refer to ## Format Compatibility -Supporting formats not described by this specification, such as XML or protobuf, +Supporting formats not described by this specification, such as XML or Protobuf, may conflict with future versions of this specification, as ongoing development aims to standardize and ensure the security and interoperability of GraphQL over HTTP. For this reason, it is recommended to adhere to the officially recognized From 943596d42651f4cf05f7c0c13978585e90b8418a Mon Sep 17 00:00:00 2001 From: Shane32 Date: Fri, 26 Jul 2024 18:19:42 -0400 Subject: [PATCH 04/12] Update cspell.yml --- cspell.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell.yml b/cspell.yml index 0473944..d34c534 100644 --- a/cspell.yml +++ b/cspell.yml @@ -15,6 +15,7 @@ words: # Software - ical - WebDAV + - Protobuf # Deliberate typos - qeury - __typena From 68d029773271278c7cf5ea2545ab303829b0db59 Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Fri, 26 Jul 2024 22:08:03 -0400 Subject: [PATCH 05/12] Update spec/GraphQLOverHTTP.md Co-authored-by: Jayden Seric --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 6832a7f..dd3bfb5 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -754,7 +754,7 @@ In this specification, GET requests are not supported for mutations due to security concerns. GET requests expose variables to logging mechanisms and intermediaries due to the URL encoding of parameters, which can lead to sensitive data being inadvertently logged. Furthermore, GET requests are -considered "basic requests" under CORS (Cross-Origin Resource Sharing), meaning +considered "simple requests" under CORS (Cross-Origin Resource Sharing), meaning they bypass preflight checks that add a layer of security. On the other hand, using `application/json` for request bodies mandates a CORS From 2a526be21e9f1098f4b6700ed03092d2cbcb7b06 Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 10:27:26 -0400 Subject: [PATCH 06/12] Update spec/GraphQLOverHTTP.md Co-authored-by: Martin Bonnin --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index dd3bfb5..4b777ea 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -746,7 +746,7 @@ well-formed _GraphQL response_ since the source of the response may not be the server but instead some intermediary such as API gateways, proxies, firewalls, etc. -# Additional Notes +# Non-Normative Notes ## Security From 0193d26bad53c551c520cec34c5d5138ec922c1c Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 10:46:50 -0400 Subject: [PATCH 07/12] format --- spec/GraphQLOverHTTP.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4b777ea..8a2f6e4 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -762,11 +762,18 @@ preflight request, adding a security layer by ensuring the client has explicit permission from the server before sending the actual request. This is particularly important in mitigating cross-site request forgery (CSRF) attacks. -Additionally, supporting form data requests (`application/x-www-form-urlencoded` -or `multipart/form-data`) could pose significant security risks. Form data -requests may be vulnerable to CSRF and other attacks due to the lack of CORS -preflight checks. As a result, the use of form data for GraphQL queries or -mutations is discouraged. +It's important to note that "simple requests" like those using +`application/x-www-form-urlencoded` or `multipart/form-data` do not have the +same CORS behavior, and thus do not undergo the same preflight checks. +Implementers should be aware of the security implications of using these types +of requests. While they can be secured with the right headers enforced by the +server, it is crucial to understand and properly account for the security risks +involved. + +To mitigate these risks, it is recommended that servers require a custom header +to ensure requests are not "simple." For instance, a `GraphQL-Require-Preflight` +header can be used to indicate that a preflight check has occurred, providing an +additional layer of security. For more detailed security considerations, please refer to [RFC 7231](https://tools.ietf.org/html/rfc7231), From 52215ccf9b06365760b8bdfd055cf35306d3afde Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 10:57:11 -0400 Subject: [PATCH 08/12] Update compatibility note --- spec/GraphQLOverHTTP.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 8a2f6e4..207acb2 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -779,10 +779,11 @@ For more detailed security considerations, please refer to [RFC 7231](https://tools.ietf.org/html/rfc7231), [RFC 6454](https://tools.ietf.org/html/rfc6454), and other relevant RFCs. -## Format Compatibility +## Request Format Compatibility Supporting formats not described by this specification, such as XML or Protobuf, -may conflict with future versions of this specification, as ongoing development -aims to standardize and ensure the security and interoperability of GraphQL over -HTTP. For this reason, it is recommended to adhere to the officially recognized -formats outlined here. +may have potential conflicts with future versions of this specification as +ongoing development aims to standardize and ensure the security and +interoperability of GraphQL over HTTP. While it is recommended to primarily +adhere to the officially recognized formats outlined here, experimentation with +other encodings is encouraged to explore their potential benefits. From c16c637ada8ed53c0e437a085560aab4446bbaa1 Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 11:13:26 -0400 Subject: [PATCH 09/12] Update spec/GraphQLOverHTTP.md --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 207acb2..4b5ff04 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -779,7 +779,7 @@ For more detailed security considerations, please refer to [RFC 7231](https://tools.ietf.org/html/rfc7231), [RFC 6454](https://tools.ietf.org/html/rfc6454), and other relevant RFCs. -## Request Format Compatibility +## Request format compatibility Supporting formats not described by this specification, such as XML or Protobuf, may have potential conflicts with future versions of this specification as From 231338b3481f7bccdc9fecd1830e3e1967defa6c Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 11:13:56 -0400 Subject: [PATCH 10/12] Update spec/GraphQLOverHTTP.md --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4b5ff04..613ddfc 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -746,7 +746,7 @@ well-formed _GraphQL response_ since the source of the response may not be the server but instead some intermediary such as API gateways, proxies, firewalls, etc. -# Non-Normative Notes +# Non-normative notes ## Security From de9d7ad50df56531247a0b7d7b729aa8ae5c991a Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 11:15:02 -0400 Subject: [PATCH 11/12] Update spec/GraphQLOverHTTP.md Co-authored-by: Martin Bonnin --- spec/GraphQLOverHTTP.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 613ddfc..6e97a32 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -784,6 +784,5 @@ For more detailed security considerations, please refer to Supporting formats not described by this specification, such as XML or Protobuf, may have potential conflicts with future versions of this specification as ongoing development aims to standardize and ensure the security and -interoperability of GraphQL over HTTP. While it is recommended to primarily -adhere to the officially recognized formats outlined here, experimentation with -other encodings is encouraged to explore their potential benefits. +interoperability of GraphQL over HTTP. For this reason, it is recommended to adhere to the officially recognized +formats outlined here. From befb96f052cd1227436918f443716ff108a78726 Mon Sep 17 00:00:00 2001 From: Shane Krueger Date: Sat, 27 Jul 2024 11:15:27 -0400 Subject: [PATCH 12/12] Reformat --- spec/GraphQLOverHTTP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 6e97a32..c22a5d6 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -784,5 +784,5 @@ For more detailed security considerations, please refer to Supporting formats not described by this specification, such as XML or Protobuf, may have potential conflicts with future versions of this specification as ongoing development aims to standardize and ensure the security and -interoperability of GraphQL over HTTP. For this reason, it is recommended to adhere to the officially recognized -formats outlined here. +interoperability of GraphQL over HTTP. For this reason, it is recommended to +adhere to the officially recognized formats outlined here.