add warning regarding subscription and mutation redaction of relational fields

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

@@ -24,14 +24,26 @@ 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.
 
+<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.
+</Callout>
+
  ## Types of relationships
 
 |Relationship|Code|Description|Example|

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

@@ -38,6 +38,18 @@ 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
 
+<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.
+</Callout>
+
 ## 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,25 @@ 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. |
 
+<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.
+
+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>
+
 ### Has One relationship
 
 import gqlv2callout from '/src/fragments/cli/gqlv2callout.mdx';
@@ -794,11 +813,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,25 @@ Before you begin, you will need:
 
 </InlineFilter>
 
+<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.
+
+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>
+
 ## 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.