Merge pull request #149 from salcho/fm-coop-coep-docs
Adding documentation for Fetch Metadata, Cross-Origin Opener Poliy & Cross-Origin Embedder Policy
diff --git a/source/core-developers/coep-interceptor.md b/source/core-developers/coep-interceptor.md
new file mode 100644
index 0000000..55e6d2d
--- /dev/null
+++ b/source/core-developers/coep-interceptor.md
@@ -0,0 +1,40 @@
+---
+layout: default
+title: COEP Interceptor
+parent:
+ title: Interceptors
+ url: interceptors.html
+---
+
+# Fetch Metadata Interceptor
+
+## Description
+
+Interceptor that implements Cross-Origin Embedder Policy on incoming requests.
+
+COEP prevents the document from loading any framed documents which don't opt-in by setting the COEP header. (`Cross-Origin-Embedder-Policy: require-corp`). This provides protection for documents that don't restrict framing. A document that doesn't set COEP cannot be framed by another document with COEP. All descendents of a document with COEP will also enforce the same restrictions.
+
+COEP is now supported by all major browsers.
+
+
+
+[More information about COEP](https://web.dev/why-coop-coep/#coep).
+
+## Parameters
+
+- `exemptedPaths` - Set of opt out endpoints that are meant to serve cross-site traffic. Paths should contain leading slashes and must be relative. This field is empty by default.
+- `enforcingMode` - Boolean variable allowing the user to let COEP operate in `enforcing`, which blocks both resource and reports violations, or `report-only` mode, which only reports violations. Default value for field is `false`.
+- `disabled` - Boolean variable disabling and enabling COEP. Default value for field is `false`.
+
+## Examples
+
+```xml
+<action name="someAction" class="com.examples.SomeAction">
+ <interceptor-ref name="defaultStack">
+ <param name="coepInterceptor.exemptedPaths">/path1,/path2,/path3</param>
+ <param name="coepInterceptor.enforcingMode">false</param>
+ <param name="coepInterceptor.disabled">false</param>
+ </interceptor-ref>
+ <result name="success">good_result.ftl</result>
+</action>
+```
\ No newline at end of file
diff --git a/source/core-developers/coop-interceptor.md b/source/core-developers/coop-interceptor.md
new file mode 100644
index 0000000..29b24d8
--- /dev/null
+++ b/source/core-developers/coop-interceptor.md
@@ -0,0 +1,42 @@
+---
+layout: default
+title: COOP Interceptor
+parent:
+ title: Interceptors
+ url: interceptors.html
+---
+
+# Fetch Metadata Interceptor
+
+## Description
+
+Interceptor that implements Cross-Origin Opener Policy on incoming requests.
+
+COOP is a security mitigation that lets developers isolate their resources against side-channel attacks and information leaks. The COOP response header allows a document to request a new browsing context group to better isolate itself from other untrustworthy origins. Separating browsing contexts is necessary because at least two types of attacks are possible when a document shares a browsing context group and possibly an operating system process with cross-origin documents:
+
+- Cross-window attacks. A malicious document can open a victim document in a new window and later navigate the window to a look-alike document to trick the user, or attempt to exploit postMessage vulnerabilities in the victim document.
+- Process-wide attacks. Side channel and transient execution attacks like Spectre may provide an opportunity to the malicious document to get access to sensitive data from the victim document, if they share an OS process.
+
+The COOP header can have one of 3 values: `same-origin`, `same-origin-allow-popups`, `unsafe-none`. If the COOP values are the same, and the origins of the documents match the relationship declared in the COOP header value, documents can interact with each other. Otherwise if at least one of the documents sets COOP, the browser will create a new browsing context group severing the link between the documents. Sites can use `same-origin-allow-popups` to allow popups they open to be in their browsing context group (unless the popup's own COOP prevents this).
+
+COOP is now supported by all major browsers.
+
+
+[More information about COOP](https://web.dev/why-coop-coep/#coop).
+
+## Parameters
+
+- `exemptedPaths` - Set of opt out endpoints that are meant to serve cross-site traffic. Paths should contain leading slashes and must be relative. This field is empty by default.
+- `mode` - The policy mode COOP should follow. Available modes are `same-origin`, `same-origin-allow-popups`, `unsafe-none`. Default mode is `same-origin`.
+
+## Examples
+
+```xml
+<action name="someAction" class="com.examples.SomeAction">
+ <interceptor-ref name="defaultStack">
+ <param name="coopInterceptor.exemptedPaths">/path1,/path2,/path3</param>
+ <param name="coopInterceptor.mode">same-origin</param>
+ </interceptor-ref>
+ <result name="success">good_result.ftl</result>
+</action>
+```
\ No newline at end of file
diff --git a/source/core-developers/fetch-metadata-interceptor.md b/source/core-developers/fetch-metadata-interceptor.md
new file mode 100644
index 0000000..2ea61c9
--- /dev/null
+++ b/source/core-developers/fetch-metadata-interceptor.md
@@ -0,0 +1,39 @@
+---
+layout: default
+title: Fetch Metadata Interceptor
+parent:
+ title: Interceptors
+ url: interceptors.html
+---
+
+# Fetch Metadata Interceptor
+
+## Description
+
+An interceptor that implements Fetch Metadata on incoming requests used to protect against CSRF, XSSI, and cross-origin information leaks. Uses a default Resource Isolation Policy to programmatically reject cross-origin requests.
+
+A Resource Isolation Policy is a strong defense in-depth mechanism that prevents the resources on a server from being requested by external websites. This policy can be enabled either for all endpoints of the application and endpoints that are meant to be loaded in a cross-site context can be exempted from the policy.
+
+The browser provides information about the context of an HTTP request in a set of `Sec-Fetch-*` headers. This allows the server processing the request to make decisions on whether the request should be accepted or rejected based on the preferred resource isolation policy. Struts provides a default Resource Isolation Policy that rejects cross-origin requests that aren't top level navigations.
+
+```
+Sec-Fetch-Site == 'cross-site' AND (Sec-Fetch-Mode != 'navigate'/'nested-navigate' OR method NOT IN [GET, HEAD])
+```
+
+Refer to [Implementing a Resource Isolation Policy](https://web.dev/fetch-metadata/#implementing-a-resource-isolation-policy) for further information on implementing effective Resource Isolation Policies.
+Fetch Metadata is supported in all major browsers
+
+## Parameters
+
+- `exemptedPaths` - Set of opt out endpoints that are meant to serve cross-site traffic. Paths should contain leading slashes and must be relative. This field is empty by default.
+
+## Examples
+
+```xml
+<action name="someAction" class="com.examples.SomeAction">
+ <interceptor-ref name="defaultStack">
+ <param name="fetchMetadata.exemptedPaths">/path1,/path2,/path3</param>
+ </interceptor-ref>
+ <result name="success">good_result.ftl</result>
+</action>
+```
\ No newline at end of file
diff --git a/source/core-developers/interceptors.md b/source/core-developers/interceptors.md
index 866dc03..48278e2 100644
--- a/source/core-developers/interceptors.md
+++ b/source/core-developers/interceptors.md
@@ -116,15 +116,18 @@
|[Annotation Workflow Interceptor](annotation-workflow-interceptor.html)|annotationWorkflow|Invokes any annotated methods on the action.|
|[Chaining Interceptor](chaining-interceptor.html)|chain|Makes the previous Action's properties available to the current Action. Commonly used together with <result type="chain"> (in the previous Action).|
|[Checckbox Interceptor](checkbox-interceptor.html)|checkbox|Adds automatic checkbox handling code that detect an unchecked checkbox and add it as a parameter with a default (usually 'false') value. Uses a specially named hidden field to detect unsubmitted checkboxes. The default unchecked value is overridable for non-boolean value'd checkboxes.|
+|[COEP Interceptor](coep-interceptor.html)|coep|Implements the Cross-Origin Embedder Policy on incoming requests used to protect a document from loading any non-same-origin resources which don't explicitly grant the document permission to be loaded.|
|[Conversion Error Interceptor](conversion-error-interceptor.html)|conversionError|Adds conversion errors from the ActionContext to the Action's field errors|
|[Cookie Interceptor](cookie-interceptor.html)|cookie|Inject cookie with a certain configurable name / value into action. (Since 2.0.7.)|
|[Cookie Provider Interceptor](cookie-provider-interceptor.html)|cookieProvider|Transfer cookies from action to response (Since 2.3.15.)|
+|[COOP Interceptor](coop-interceptor.html)|coop|Implements the Cross-Origin Opener Policy on incoming requests used to isolate resources against side-channel attacks and information leaks.|
|[Create Session Interceptor](create-session-interceptor.html)|createSession|Create an HttpSession automatically, useful with certain Interceptors that require a HttpSession to work properly (like the TokenInterceptor)|
|[Clear Session Interceptor](clear-session-interceptor.html)|clearSession|This interceptor clears the HttpSession.|
|[Debugging Interceptor](debugging-interceptor.html)|debugging|Provides several different debugging screens to provide insight into the data behind the page.|
|[Default Workflow Interceptor](default-workflow-interceptor.html)|workflow|Calls the validate method in your Action class. If Action errors are created then it returns the INPUT view.|
|[Exception Interceptor](exception-interceptor.html)|exception|Maps exceptions to a result.|
|[Execute and Wait Interceptor](execute-and-wait-interceptor.html)|execAndWait|Executes the Action in the background and then sends the user off to an intermediate waiting page.|
+|[Fetch Metadata Interceptor](fetch-metadata-interceptor.html)|fetchMetadata|Implements the Resource Isolation Policies on incoming requests used to protect against CSRF, XSSI, and cross-origin information leaks.|
|[File Upload Interceptor](file-upload-interceptor.html)|fileUpload|An Interceptor that adds easy access to file upload support.|
|[I18n Interceptor](i18n-interceptor.html)|i18n|Remembers the locale selected for a user's session.|
|[Logging Interceptor](logging-interceptor.html)|logger|Outputs the name of the Action.|
diff --git a/source/security/index.md b/source/security/index.md
index d14b3e8..00ce3f4 100644
--- a/source/security/index.md
+++ b/source/security/index.md
@@ -289,3 +289,27 @@
This mechanism was introduced in version 2.5. It allows control what methods can be accessed with the bang "!" operator
via [Dynamic Method Invocation](../core-developers/action-configuration.html#dynamic-method-invocation). Please read
more in the Strict Method Invocation section of [Action Configuration](../core-developers/action-configuration.html).
+
+### Resource Isolation Using Fetch Metadata
+
+Fetch Metadata is a mitigation against common cross origin attacks such as Cross-Site Request Forgery (CSRF). It is a web platform security feature designed to help servers defend themselves against cross-origin attacks based on the preferred resource isolation policy. The browser provides information about the context of an HTTP request in a set of `Sec-Fetch-*` headers. This allows the server processing the request to make decisions on whether the request should be accepted or rejected based on the available resource isolation policies.
+
+A Resource Isolation Policy prevents the resources on a server from being requested by external websites. This policy can be enabled for all endpoints of the application or the endpoints that are meant to be loaded in a cross-site context can be exempted from applying the policy. Read more about Fetch Metadata and resource isolation [here](https://web.dev/fetch-metadata/).
+
+This mechanism is implemented in Struts using the [FetchMetadata Interceptor](../core-developers/fetch-metadata-interceptor.html). Refer to the documentation for [FetchMetadata Interceptor](../core-developers/fetch-metadata-interceptor.html) instructions on how to enable Fetch Metadata.
+
+### Cross Origin Isolation with COOP and COEP
+
+[Cross-Origin Opener Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) is a security mitigation that lets developers isolate their resources against side-channel attacks and information leaks. The COOP response header allows a document to request a new browsing context group to better isolate itself from other untrustworthy origins.
+
+[Cross-Origin Embedder Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) prevents a document from loading any cross-origin resources which don't explicitly grant the document permission to be loaded.
+
+COOP and COEP are independent mechanisms that can be enabled, tested and deployed separately. While enabling one doesn’t require developers to enable the other, when set together COOP and COEP allows developers to use powerful features (such as `SharedArrayBuffer`, `performance.measureMemory()` and the JS Self-Profiling API) securely, without worrying about side channel attacks like [Spectre](https://meltdownattack.com/). Further reading on [COOP/COEP](https://docs.google.com/document/d/1zDlfvfTJ_9e8Jdc8ehuV4zMEu9ySMCiTGMS9y0GU92k/edit#bookmark=id.uo6kivyh0ge2) and [why you need cross-origin isolation](https://web.dev/why-coop-coep/).
+
+The recommended configuration for the policies are:
+```
+Cross-Origin-Embedder-Policy: require-corp;
+Cross-Origin-Opener-Policy: same-origin;
+```
+
+COOP and COEP are implemented in Struts using [CoopInterceptor](../core-developers/coop-interceptor.html) and [CoepInterceptor](../core-developers/coep-interceptor.html).
