From 09c37be367561ae16ff25889b57728501f37b992 Mon Sep 17 00:00:00 2001 From: Andrea Dao Date: Thu, 9 May 2024 15:09:43 -0500 Subject: [PATCH 1/5] draft inline scripts --- docs/api-docs/storefront/scripts-overview.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/api-docs/storefront/scripts-overview.mdx b/docs/api-docs/storefront/scripts-overview.mdx index 918bcf72b..5f88e110f 100644 --- a/docs/api-docs/storefront/scripts-overview.mdx +++ b/docs/api-docs/storefront/scripts-overview.mdx @@ -127,6 +127,24 @@ You can add up to five SRI hashes and remove hashes when they are no longer vali If there is a change to the host script, you must update or add a valid hash. If no hashes match the contents of the script, the browser console will show an error that the script failed to execute. +### Inline scripts + +Merchants can opt-in to this feature in storefront settings. After that, scripts will fail if... + + +Inline scripts use a `nonce` attribute in the `script` tag that has a uniquely generated value. +On every page load, BigCommerce generates a nonce value and passes it to browsers through the content security policy header. +For any scripts that the merchant adds through Script Manager or the Scripts API, BigCommerce automatically injects the nonce value for them on every page load. + +Browsers first check for the integrity hashes before checking nonce values. + +If you are editing custom scripts in the Stencil theme files (i.e. outside of script manager or the Scripts API), you need to add a nonce handlebar. +E.g. added script to checkout page. + +Inline scripts may contain handlebar template variables. +Since their values change dynamically and a script contents must match an integrity hash, you can't use intgrity hashes for inline scripts. + + ## Troubleshooting Your app installation may find itself unexpectedly missing one or more scripts. Below are some possible causes of this issue. From d0ff5ae03c69c9f7f149997baa0e0a75c2cb24d1 Mon Sep 17 00:00:00 2001 From: Andrea Dao Date: Tue, 21 May 2024 15:07:18 -0500 Subject: [PATCH 2/5] change heading levels --- docs/api-docs/storefront/scripts-overview.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api-docs/storefront/scripts-overview.mdx b/docs/api-docs/storefront/scripts-overview.mdx index 5f88e110f..128d0e474 100644 --- a/docs/api-docs/storefront/scripts-overview.mdx +++ b/docs/api-docs/storefront/scripts-overview.mdx @@ -106,7 +106,9 @@ Solutions that add dynamic script support using revisions to or additions of scr Release notes can work for all storefronts. Changes to the [OAuth scopes](/docs/start/authentication/api-accounts#oauth-scopes) of apps that use [app-level API accounts](/docs/start/authentication/api-accounts#app-level-api-accounts) require the store owner or other authorized user to accept the new scopes, which could provide a mechanism to trigger release note display. Store owners aren't prompted to reauthorize until they next open an app in the control panel, so direct contact may be advisable from a conversion perspective. You can't change the OAuth scopes for a [store-level API account](/docs/start/authentication/api-accounts#store-level-api-accounts), so directly contacting the store or stores that you want to change may be your only option for disclosure. -## Subresource integrity +## PCI compliance + +### Subresource integrity [Subresource integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) is a security feature browsers use to verify that attackers have not manipulated external hosted resources, including scripts. From 94d184d3c04ced477529a45cafdfbf43e4295903 Mon Sep 17 00:00:00 2001 From: Andrea Dao Date: Tue, 21 May 2024 16:30:56 -0500 Subject: [PATCH 3/5] edit PCI compliance section & Inline script section --- docs/api-docs/storefront/scripts-overview.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/api-docs/storefront/scripts-overview.mdx b/docs/api-docs/storefront/scripts-overview.mdx index 128d0e474..3c103a02c 100644 --- a/docs/api-docs/storefront/scripts-overview.mdx +++ b/docs/api-docs/storefront/scripts-overview.mdx @@ -108,6 +108,12 @@ Release notes can work for all storefronts. Changes to the [OAuth scopes](/docs/ ## PCI compliance +To comply with PCI standards, BigCommerce implements the [Subresource Integrity (SRI)]() feature for external scripts and [Content Security Policy (CSP)]() standards for inline scripts. + +You can [opt into these security features]() in the control panel in storefront settings. + +The following sections describe what you need to provide after you opt-in to ensure the integrity of scripts. + ### Subresource integrity [Subresource integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) is a security feature browsers use to verify that attackers have not manipulated external hosted resources, including scripts. @@ -129,23 +135,20 @@ You can add up to five SRI hashes and remove hashes when they are no longer vali If there is a change to the host script, you must update or add a valid hash. If no hashes match the contents of the script, the browser console will show an error that the script failed to execute. -### Inline scripts +### Content security policy -Merchants can opt-in to this feature in storefront settings. After that, scripts will fail if... +[Content Security Policy (CSP)]() is a standard that uses [`nonce` global attributes]() to allowlist non-static inline scripts. +Since inline scripts may contain dynamic handlebar template variables, BigCommerce uses `nonce` values instead of `intgrity` hashes to validate inline scripts. Browsers first check for `integrity` hashes before checking `nonce` values. -Inline scripts use a `nonce` attribute in the `script` tag that has a uniquely generated value. -On every page load, BigCommerce generates a nonce value and passes it to browsers through the content security policy header. +The `nonce` attribute in the `script` tag has a uniquely generated value. +On every page load, BigCommerce generates a nonce value and passes it to browsers through the HTTP `Content-Security-Policy` response header. For any scripts that the merchant adds through Script Manager or the Scripts API, BigCommerce automatically injects the nonce value for them on every page load. -Browsers first check for the integrity hashes before checking nonce values. If you are editing custom scripts in the Stencil theme files (i.e. outside of script manager or the Scripts API), you need to add a nonce handlebar. E.g. added script to checkout page. -Inline scripts may contain handlebar template variables. -Since their values change dynamically and a script contents must match an integrity hash, you can't use intgrity hashes for inline scripts. - ## Troubleshooting From 35f5e9fd3d25ec7494ea83080504abe2624d3877 Mon Sep 17 00:00:00 2001 From: Andrea Dao Date: Tue, 21 May 2024 16:44:57 -0500 Subject: [PATCH 4/5] code blocks and caps --- docs/api-docs/storefront/scripts-overview.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/api-docs/storefront/scripts-overview.mdx b/docs/api-docs/storefront/scripts-overview.mdx index 3c103a02c..3f119e6e7 100644 --- a/docs/api-docs/storefront/scripts-overview.mdx +++ b/docs/api-docs/storefront/scripts-overview.mdx @@ -139,16 +139,13 @@ You can add up to five SRI hashes and remove hashes when they are no longer vali [Content Security Policy (CSP)]() is a standard that uses [`nonce` global attributes]() to allowlist non-static inline scripts. -Since inline scripts may contain dynamic handlebar template variables, BigCommerce uses `nonce` values instead of `intgrity` hashes to validate inline scripts. Browsers first check for `integrity` hashes before checking `nonce` values. +Since inline scripts may contain dynamic handlebar template variables, BigCommerce uses `nonce` values instead of `integrity` hashes to validate inline scripts. Browsers first check for `integrity` hashes before checking `nonce` values. The `nonce` attribute in the `script` tag has a uniquely generated value. -On every page load, BigCommerce generates a nonce value and passes it to browsers through the HTTP `Content-Security-Policy` response header. -For any scripts that the merchant adds through Script Manager or the Scripts API, BigCommerce automatically injects the nonce value for them on every page load. - - -If you are editing custom scripts in the Stencil theme files (i.e. outside of script manager or the Scripts API), you need to add a nonce handlebar. -E.g. added script to checkout page. +On every page load, BigCommerce generates a `nonce` value and passes it to browsers through the HTTP `Content-Security-Policy` response header. +For any scripts that the merchant adds through Script Manager or the Scripts API, BigCommerce automatically injects the `nonce` value for them on every page load. +If you are editing custom scripts in the Stencil theme files (i.e. outside of Script Manager or the Scripts API), you need to add a `nonce` handlebar. ## Troubleshooting From 8f8ac19aa5e089709c31a6149fd62a6de759d169 Mon Sep 17 00:00:00 2001 From: Andrea Dao Date: Tue, 4 Jun 2024 17:01:30 -0500 Subject: [PATCH 5/5] revise --- docs/api-docs/storefront/scripts-overview.mdx | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/api-docs/storefront/scripts-overview.mdx b/docs/api-docs/storefront/scripts-overview.mdx index 3f119e6e7..69bb6f55c 100644 --- a/docs/api-docs/storefront/scripts-overview.mdx +++ b/docs/api-docs/storefront/scripts-overview.mdx @@ -108,15 +108,15 @@ Release notes can work for all storefronts. Changes to the [OAuth scopes](/docs/ ## PCI compliance -To comply with PCI standards, BigCommerce implements the [Subresource Integrity (SRI)]() feature for external scripts and [Content Security Policy (CSP)]() standards for inline scripts. +To ensure the integrity of your scripts, BigCommerce implements the [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) feature for _external_ scripts and [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) standards for _inline_ scripts. -You can [opt into these security features]() in the control panel in storefront settings. +You can [opt into these security features]() in the control panel in storefront settings. -The following sections describe what you need to provide after you opt-in to ensure the integrity of scripts. +After you opt in, your scripts must meet additional requirements to successfully execute in the browser. The following sections describe what you and BigCommerce need to provide to meet security requirements after you opt in. ### Subresource integrity -[Subresource integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) is a security feature browsers use to verify that attackers have not manipulated external hosted resources, including scripts. +[Subresource integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) is a security feature browsers use to verify that attackers have not manipulated _external_ hosted resources, including scripts. All scripts on the checkout page need at least one SRI hash to meet [PCI 4.0 - 6.4.3 requirements](https://pcipolicies.com/blogs/news/how-to-comply-with-the-new-pci-dss-requirement-6-4-3). @@ -137,15 +137,13 @@ You can add up to five SRI hashes and remove hashes when they are no longer vali ### Content security policy -[Content Security Policy (CSP)]() is a standard that uses [`nonce` global attributes]() to allowlist non-static inline scripts. +[Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is a standard that can use [`nonce` global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) to allowlist _non-static inline_ scripts. -Since inline scripts may contain dynamic handlebar template variables, BigCommerce uses `nonce` values instead of `integrity` hashes to validate inline scripts. Browsers first check for `integrity` hashes before checking `nonce` values. +Since the inline scripts you inject may contain dynamic handlebar template variables, BigCommerce uses `nonce` values instead of `integrity` hashes to validate inline scripts. Browsers first check for `integrity` hashes before checking `nonce` values. -The `nonce` attribute in the `script` tag has a uniquely generated value. -On every page load, BigCommerce generates a `nonce` value and passes it to browsers through the HTTP `Content-Security-Policy` response header. -For any scripts that the merchant adds through Script Manager or the Scripts API, BigCommerce automatically injects the `nonce` value for them on every page load. +If you add a script through Script Manager or the Scripts API, BigCommerce automatically generates and injects a unique `nonce` value for the script on every page load. We then pass it to browsers through the HTTP `Content-Security-Policy` response header. -If you are editing custom scripts in the Stencil theme files (i.e. outside of Script Manager or the Scripts API), you need to add a `nonce` handlebar. +If you have custom scripts in the Stencil theme files (i.e. outside of Script Manager or the Scripts API), you need to add a `nonce` handlebar to the script. ## Troubleshooting