docs(core): add an error details page for unsafe <iframe> bindings (#…

…48027) (#48029)

PR Close #48027

PR Close #48029

aio/content/errors/NG0910.md

@@ -0,0 +1,71 @@
+@name Unsafe bindings on an iframe element
+@category runtime
+@shortDescription Unsafe bindings on an iframe element
+
+@description
+You see this error when Angular detects an attribute binding or a property binding on an `<iframe>` element using the following property names:
+
+* sandbox
+* allow
+* allowFullscreen
+* referrerPolicy
+* csp
+* fetchPriority
+
+The mentioned attributes affect the security model setup for `<iframe>`s
+and it's important to apply them before setting the `src` or `srcdoc` attributes.
+To enforce that, Angular requires these attributes to be set on `<iframe>`s as
+static attributes, so the values are set at the element creation time and they
+remain the same throughout the lifetime of an `<iframe>` instance.
+
+The error is thrown when a property binding with one of the mentioned attribute names is used:
+```html
+<iframe [sandbox]="'allow-scripts'" src="..."></iframe>
+```
+
+or when it's an attribute bindings:
+
+```html
+<iframe [attr.sandbox]="'allow-scripts'" src="..."></iframe>
+```
+
+Also, the error is thrown when a similar pattern is used in Directive's host bindings:
+
+```typescript
+@Directive({
+  selector: 'iframe',
+  host: {
+    '[sandbox]': `'allow-scripts'`,
+    '[attr.sandbox]': `'allow-scripts'`,
+  }
+})
+class IframeDirective {}
+```
+
+@debugging
+
+The error message includes the name of the component with the template where
+an `<iframe>` element with unsafe bindings is located.
+
+The recommended solution is to use the mentioned attributes as static ones, for example:
+
+```html
+<iframe sandbox="allow-scripts" src="..."></iframe>
+```
+
+If you need to have different values for these attributes (depending on various conditions),
+you can use an `*ngIf` or an `*ngSwitch` on an `<iframe>` element:
+
+```html
+<iframe *ngIf="someConditionA" sandbox="allow-scripts" src="..."></iframe>
+<iframe *ngIf="someConditionB" sandbox="allow-forms" src="..."></iframe>
+<iframe *ngIf="someConditionC" sandbox="allow-popups" src="..."></iframe>
+```
+
+<!-- links -->
+
+<!-- external links -->
+
+<!-- end links -->
+
+@reviewed 2022-05-27

goldens/public-api/core/errors.md

@@ -67,7 +67,7 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     UNKNOWN_ELEMENT = 304,
     // (undocumented)
-    UNSAFE_IFRAME_ATTRS = 910,
+    UNSAFE_IFRAME_ATTRS = -910,
     // (undocumented)
     UNSAFE_VALUE_IN_RESOURCE_URL = 904,
     // (undocumented)

packages/core/src/errors.ts

@@ -63,7 +63,7 @@ export const enum RuntimeErrorCode {
   INVALID_INHERITANCE = 903,
   UNSAFE_VALUE_IN_RESOURCE_URL = 904,
   UNSAFE_VALUE_IN_SCRIPT = 905,
-  UNSAFE_IFRAME_ATTRS = 910,
+  UNSAFE_IFRAME_ATTRS = -910,
 }
 
 /**

packages/core/test/acceptance/security_spec.ts

@@ -47,7 +47,7 @@ describe('comment node text escaping', () => {
 
 describe('iframe processing', () => {
   function getErrorMessageRegexp() {
-    const errorMessagePart = 'NG0' + RuntimeErrorCode.UNSAFE_IFRAME_ATTRS.toString();
+    const errorMessagePart = 'NG0' + Math.abs(RuntimeErrorCode.UNSAFE_IFRAME_ATTRS).toString();
     return new RegExp(errorMessagePart);
   }