add warning regarding subscription and mutation redaction of relational fields

src/components/FeatureFlags/feature-flags.json

@@ -371,6 +371,26 @@
             "defaultExistingProject": false
           }
         ]
+      },
+      "subscriptionsInheritPrimaryAuth": {
+        "description": "Toggles whether subscriptions will inherit related authorization when relational fields are set as required",
+        "type": "Feature",
+        "valueType": "Boolean",
+        "versionAdded": "12.12.4",
+        "values": [
+          {
+            "value": "true",
+            "description": "Subscriptions will inherit the primary model authorization rules for the relational fields",
+            "defaultNewProject": false,
+            "defaultExistingProject": true
+          },
+          {
+            "value": "false",
+            "description": "Relational fields will be redacted in mutation response when there is a difference between auth rules between primary and related models.",
+            "defaultNewProject": true,
+            "defaultExistingProject": false
+          }
+        ]
       }
     }
   },

src/fragments/lib-v1/graphqlapi/ios/subscribe-data.mdx

@@ -82,7 +82,7 @@ func createSubscription() {
 
 </BlockSwitcher>
 
-### Unsubscribing from updates
+## Unsubscribing from updates
 
 #### Listener (iOS 11+)
 

src/fragments/lib/graphqlapi/flutter/subscribe-data.mdx

@@ -76,7 +76,7 @@ Amplify.Hub.listen(
 );
 ```
 
-#### SubscriptionStatus
+### SubscriptionStatus
 
 - **`connected`** - Connected and working with no issues
 - **`connecting`** - Attempting to connect (both initial connection and reconnection)

src/fragments/lib/graphqlapi/ios/subscribe-data.mdx

@@ -87,9 +87,9 @@ func createSubscription() {
 
 </BlockSwitcher>
 
-### Unsubscribing from updates
+## Unsubscribing from updates
 
-#### Async/Await
+### Async/Await
 
 To unsubscribe from updates, you can call `cancel()` on the subscription.
 
@@ -100,7 +100,7 @@ func cancelSubscription() {
 }
 ```
 
-#### Combine
+### Combine
 
 Calling `cancel()` on the sequence will disconnect the subscription from the backend. Any downstream subscribers will also be cancelled.
 

src/pages/[platform]/build-a-backend/data/data-modeling/relationships/index.mdx

@@ -24,14 +24,20 @@ export const getStaticPaths = async () => {
 export function getStaticProps(context) {
   return {
     props: {
-      
+
       meta
     }
   };
 }
 
 When modeling application data, you often need to establish relationships between different data models. In Amplify Data, you can create one-to-many, one-to-one, and many-to-many relationships in your Data schema. On the client-side, Amplify Data allows you to lazy or eager load of related data.
 
+{/* This component contains approved messaging and cannot be removed or modified without prior approval */}
+
+import { ProtectedRedactionGen2Message } from "@/protected/ProtectedRedactionMessage"
+
+<ProtectedRedactionGen2Message />
+
  ## Types of relationships
 
 |Relationship|Code|Description|Example|

src/pages/[platform]/build-a-backend/data/subscribe-data/index.mdx

@@ -38,6 +38,12 @@ Before you begin, you will need:
 - An [application connected to the API](/[platform]/build-a-backend/data/connect-to-API/)
 - Data already created to modify
 
+{/* This component contains approved messaging and cannot be removed or modified without prior approval */}
+
+import { ProtectedRedactionGen2Message } from "@/protected/ProtectedRedactionMessage"
+
+<ProtectedRedactionGen2Message />
+
 ## Set up a real-time list query
 
 The recommended way to fetch a list of data is to use `observeQuery` to get a real-time list of your app data at all times. You can integrate `observeQuery` with React's `useState` and `useEffect` hooks in the following way:

src/pages/gen1/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx

@@ -292,6 +292,12 @@ Create "has one", "has many", "belongs to", and "many to many" relationships bet
 | `@belongsTo` | Use a "belongs to" relationship to make a "has one" or "has many" relationship bi-directional. For example, a Project has one Team and a Team belongs to a Project. This allows you to query the team from the project record and vice versa. |
 | `@manyToMany` | Configures a "join table" between two models to facilitate a many-to-many relationship. For example, a Blog has many Tags and a Tag has many Blogs. |
 
+{/* This component contains approved messaging and cannot be removed or modified without prior approval */}
+
+import { ProtectedRedactionGen1Message } from "@/protected/ProtectedRedactionMessage"
+
+<ProtectedRedactionGen1Message />
+
 ### Has One relationship
 
 import gqlv2callout from '/src/fragments/cli/gqlv2callout.mdx';
@@ -794,11 +800,11 @@ You can use the `@default` directive to specify a default value for optional [sc
 ```graphql
 type Todo @model {
   content: String @default(value: "My new Todo")
-  # Note: all "value" parameters must be passed as a string value. 
+  # Note: all "value" parameters must be passed as a string value.
   # Under the hood, Amplify will parse the string values into respective types.
-  # For example, to set a default value for an integer field, 
+  # For example, to set a default value for an integer field,
   # you must pass in `"0"` instead of `0` without the double-quotes.
-  likes: Int @default(value: "0") # 
+  likes: Int @default(value: "0") #
 }
 ```
 

src/pages/gen1/[platform]/build-a-backend/graphqlapi/relational-models/index.mdx

@@ -29,6 +29,30 @@ API (GraphQL) has the capability to handle relationships between Models, such as
 
 By default, GraphQL APIs requests generate a selection set with a depth of 0. Connected relationship models are not returned in the initial request, but can be lazily loaded as needed with an additional API request. We provide mechanisms to customize the selection set, which allows connected relationships to be eagerly loaded on the initial request.
 
+<Callout warning>
+
+With versions of Amplify CLI `@aws-amplify/cli@12.12.2` and API Category `@aws-amplify/amplify-category-api@5.11.5`, an improvement was made to how relational field data is handled in subscriptions when different authorization rules apply to related models in a schema. The improvement redacts the values for the relational fields, displaying them as null or empty, to prevent unauthorized access to relational data.
+
+This redaction occurs whenever it cannot be determined that the child model will be protected by the same permissions as the parent model.
+
+Because subscriptions are tied to mutations and the selection set provided in the result of a mutation is then passed through to the subscription, relational fields in the result of mutations must be redacted.
+
+If an authorized end-user needs access to the redacted relational fields, they should perform a query to read the relational data.
+
+Additionally, subscriptions will inherit related authorization when relational fields are set as required. To better protect relational data, consider modifying the schema to use optional relational fields.
+
+- **Lazy and Eager Loading**: Lazy and eager loading relationships is no longer supported for Mutations and Subscriptions. However, you can continue to perform eager or lazy loading for Queries.
+
+- **Subscriptions and Related Models**: When performing a subscription and you need to retrieve the related model, perform a lazy or eager loaded query using the model identifier from the subscription event to continue to retrieve the related data.
+
+Based on the security posture of your application, you can choose to revert to the subscription behavior before this improvement was made.
+To do so, use the `subscriptionsInheritPrimaryAuth` feature flag under `graphqltransformer` in the `amplify/backend/cli.json` file.
+
+- If enabled, subscriptions will inherit the primary model authorization rules for the relational fields.
+- If disabled, relational fields will be redacted in mutation response when there is a difference between auth rules between primary and related models.
+
+</Callout>
+
 ## Prerequisites
 
 The following examples have a minimum version requirement of the following:

src/pages/gen1/[platform]/build-a-backend/graphqlapi/subscribe-data/index.mdx

@@ -49,6 +49,12 @@ Before you begin, you will need:
 
 </InlineFilter>
 
+{/* This component contains approved messaging and cannot be removed or modified without prior approval */}
+
+import { ProtectedRedactionGen1Message } from "@/protected/ProtectedRedactionMessage"
+
+<ProtectedRedactionGen1Message />
+
 ## Set up a real-time subscription
 
 Subscriptions is a GraphQL feature that allows the server to send data to its clients when a specific event happens. For example, you can subscribe to an event when a new record is created, updated, or deleted through the API. You can enable real-time data integration in your app with a subscription.

src/pages/gen1/[platform]/prev/build-a-backend/graphqlapi/subscribe-data/index.mdx

@@ -38,6 +38,12 @@ Before you begin, you will need:
 - An [application connected to the API](/gen1/[platform]/prev/build-a-backend/graphqlapi/connect-to-api/)
 - Data already created to modify
 
+{/* This component contains approved messaging and cannot be removed or modified without prior approval */}
+
+import { ProtectedRedactionGen1Message } from "@/protected/ProtectedRedactionMessage"
+
+<ProtectedRedactionGen1Message />
+
 ## Set up a real-time subscription
 
 Subscriptions is a GraphQL feature that allows the server to send data to its clients when a specific event happens. For example, you can subscribe to an event when a new record is created, updated, or deleted through the API. You can enable real-time data integration in your app with a subscription.

src/protected/ProtectedRedactionMessage/__tests__/ProtectedRedactionMessage.test.tsx

@@ -0,0 +1,81 @@
+import * as React from 'react';
+import { render } from '@testing-library/react';
+import {
+  ProtectedRedactionGen1Message,
+  ProtectedRedactionGen2Message
+} from '../index';
+import fs from 'fs';
+
+// REALTIME DATA
+const GEN1_V5_REALTIME_DATA_PAGE_PATH =
+  'src/pages/gen1/[platform]/prev/build-a-backend/graphqlapi/subscribe-data/index.mdx';
+
+const GEN1_V6_REALTIME_DATA_PAGE_PATH =
+  'src/pages/gen1/[platform]/build-a-backend/graphqlapi/subscribe-data/index.mdx';
+
+const GEN2_REALTIME_DATA_PAGE_PATH =
+  'src/pages/[platform]/build-a-backend/data/subscribe-data/index.mdx';
+
+// DATA MODELING
+
+const GEN1_V6_DATA_MODELING_PAGE_PATH =
+  'src/pages/gen1/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx';
+
+const GEN2_DATA_MODELING_PAGE_PATH =
+  'src/pages/[platform]/build-a-backend/data/data-modeling/relationships/index.mdx';
+
+describe('Protected Redaction Messages', () => {
+  /*
+        This test is to ensure that the ProtectedRedactionGen1Message component appears on the Gen 1 realtime data pages and cannot be removed or modified without approval.
+    */
+  it('should render ProtectedRedactionGen1Message component on the Gen 1 V5 realtime data page', async () => {
+    const pageData = fs.readFileSync(GEN1_V5_REALTIME_DATA_PAGE_PATH, {
+      encoding: 'utf8'
+    });
+    expect(pageData).toMatch(/<ProtectedRedactionGen1Message \/>/);
+  });
+
+  it('should render ProtectedRedactionGen1Message component on the Gen 1 V6 realtime data page', async () => {
+    const pageData = fs.readFileSync(GEN1_V6_REALTIME_DATA_PAGE_PATH, {
+      encoding: 'utf8'
+    });
+    expect(pageData).toMatch(/<ProtectedRedactionGen1Message \/>/);
+  });
+
+  it('should render ProtectedRedactionGen1Message component on the Gen 2 realtime data page', async () => {
+    const pageData = fs.readFileSync(GEN2_REALTIME_DATA_PAGE_PATH, {
+      encoding: 'utf8'
+    });
+    expect(pageData).toMatch(/<ProtectedRedactionGen2Message \/>/);
+  });
+
+  it('should render ProtectedRedactionGen1Message component on the Gen 1 V6 data modeling page', async () => {
+    const pageData = fs.readFileSync(GEN1_V6_DATA_MODELING_PAGE_PATH, {
+      encoding: 'utf8'
+    });
+    expect(pageData).toMatch(/<ProtectedRedactionGen1Message \/>/);
+  });
+
+  it('should render ProtectedRedactionGen1Message component on the Gen 2 data modeling page', async () => {
+    const pageData = fs.readFileSync(GEN2_DATA_MODELING_PAGE_PATH, {
+      encoding: 'utf8'
+    });
+    expect(pageData).toMatch(/<ProtectedRedactionGen2Message \/>/);
+  });
+
+  /*
+      This test is to ensure that the messaging on the ProtectedRedactionGen1Message component does not change
+      and cannot be removed or modified without approval.
+    */
+  it('should render the protected redaction message for Gen 1', async () => {
+    const { container } = render(<ProtectedRedactionGen1Message />);
+
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('should render the protected redaction message for Gen 2', async () => {
+    const { container } = render(<ProtectedRedactionGen2Message />);
+
+    expect(container.firstChild).toMatchSnapshot();
+  });
+});