FF123 updates for permission publickey-credentials-create (#32135)

* FF123 updates for permission publickey-credentials-create

* Add req for transient activation

* Apply suggestions from code review

* Clarify transient activation in the Permission-Policy docs

* Update files/en-us/web/api/web_authentication_api/index.md

* Update files/en-us/web/api/web_authentication_api/index.md

* CredentialsContainer.create() - webauthn add transient activation req.

* Update files/en-us/web/api/credentialscontainer/create/index.md

Co-authored-by: wbamberg <[email protected]>

* Add link from iframe allow attribute to exmaples

* Update files/en-us/web/api/web_authentication_api/index.md

* Transient activation only required for create() cross-platform calls

* Update files/en-us/web/api/web_authentication_api/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

---------

Co-authored-by: wbamberg <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

files/en-us/web/api/credentialscontainer/create/index.md

@@ -313,8 +313,11 @@ A {{jsxref("Promise")}} that resolves with an {{domxref("PublicKeyCredential")}}
 
 ### Exceptions
 
-- `SecurityError` {{domxref("DOMException")}}
-  - : Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Possible causes include:
+    - Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+    - The function is called cross-origin but the iframe's [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy.
+    - The function is called cross-origin and the `<iframe>` does not have {{glossary("transient activation")}}.
 
 ## Examples
 

files/en-us/web/api/credentialscontainer/get/index.md

@@ -336,7 +336,7 @@ A {{jsxref("Promise")}} that resolves with an {{domxref("PublicKeyCredential")}}
 
 ### Exceptions
 
-- `SecurityError` {{domxref("DOMException")}}
+- `NotAllowedError` {{domxref("DOMException")}}
   - : Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
 
 ### Examples

files/en-us/web/api/web_authentication_api/index.md

@@ -121,9 +121,12 @@ The availability of WebAuthn can be controlled using a [Permissions Policy](/en-
 - {{httpheader("Permissions-Policy/publickey-credentials-create", "publickey-credentials-create")}}: Controls the availability of {{domxref("CredentialsContainer.create", "navigator.credentials.create()")}} with the `publicKey` option.
 - {{httpheader("Permissions-Policy/publickey-credentials-get", "publickey-credentials-get")}}: Controls the availability of {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} with the `publicKey` option.
 
-Both directives have a default allowlist value of `"self"`, meaning that by default these methods can be used in top-level document contexts. In addition, `get()` can be used in nested browsing contexts loaded from the same origin as the top-most document; `create()` on the other hand cannot be used in {{htmlelement("iframe")}}s.
+Both directives have a default allowlist value of `"self"`, meaning that by default these methods can be used in top-level document contexts.
+In addition, `get()` can be used in nested browsing contexts loaded from the same origin as the top-most document.
+`get()` and `create()` can be used in nested browsing contexts loaded from the different origins to the top-most document (i.e. in cross-origin `<iframes>`), if allowed by the [`publickey-credentials-get`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get) and [`publickey-credentials-create`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-create) `Permission-Policy` directives, respectively.
+For cross-origin `create()` calls, where the permission was granted by [`allow=` on an iframe](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes), the frame must also have {{glossary("Transient activation")}}.
 
-> **Note:** Where a policy forbids use of these methods, the {{jsxref("Promise", "promises")}} returned by them will reject with a `SecurityError` {{domxref("DOMException")}}.
+> **Note:** Where a policy forbids use of these methods, the {{jsxref("Promise", "promises", "", "nocode")}} returned by them will reject with a `NotAllowedError` {{domxref("DOMException")}}.
 
 ### Basic access control
 
@@ -134,28 +137,44 @@ Permissions-Policy: publickey-credentials-get=("https://subdomain.example.com")
 Permissions-Policy: publickey-credentials-create=("https://subdomain.example.com")
 ```
 
-### Allowing embedded `get()` calls in an `<iframe>`
+### Allowing embedded `create` and `get()` calls in an `<iframe>`
 
-If you wish to authenticate with `get()` in an `<iframe>`, there are a couple of steps to follow:
+If you wish to authenticate with `get()` or `create()` in an `<iframe>`, there are a couple of steps to follow:
 
 1. The site embedding the relying party site must provide permission via an `allow` attribute:
 
-   ```html
-   <iframe
-     src="https://auth.provider.com"
-     allow="publickey-credentials-get *" />
-   ```
+   - If using `get()`:
+
+     ```html
+     <iframe
+       src="https://auth.provider.com"
+       allow="publickey-credentials-get *">
+     </iframe>
+     ```
+
+   - If using `create()`:
+
+     ```html
+     <iframe
+       src="https://auth.provider.com"
+       allow="publickey-credentials-create 'self' https://a.auth.provider.com https://b.auth.provider.com">
+     </iframe>
+     ```
+
+     The `<iframe>` must also have {{glossary("Transient activation")}} if `create()` is called cross-origin.
 
 2. The relying party site must provide permission for the above access via a `Permissions-Policy` header:
 
    ```http
    Permissions-Policy: publickey-credentials-get=*
+   Permissions-Policy: publickey-credentials-create=*
    ```
 
    Or to allow only a specific URL to embed the relying party site in an `<iframe>`:
 
    ```http
    Permissions-Policy: publickey-credentials-get=("https://subdomain.example.com")
+   Permissions-Policy: publickey-credentials-create=("https://*.auth.provider.com")
    ```
 
 ## Interfaces

files/en-us/web/html/element/iframe/index.md

@@ -23,6 +23,8 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
   - : Specifies a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) for the `<iframe>`. The policy defines what features are available to the `<iframe>` (for example, access to the microphone, camera, battery, web-share, etc.) based on the origin of the request.
 
+    See [iframes](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes) in the `Permissions-Policy` topic for examples.
+
     > **Note:** A Permissions Policy specified by the `allow` attribute implements a further restriction on top of the policy specified in the {{httpheader("Permissions-Policy")}} header. It doesn't replace it.
 
 - `allowfullscreen`

files/en-us/web/http/headers/permissions-policy/publickey-credentials-create/index.md

@@ -11,7 +11,8 @@ browser-compat: http.headers.Permissions-Policy.publickey-credentials-create
 
 The HTTP {{HTTPHeader("Permissions-Policy")}} header `publickey-credentials-create` directive controls whether the current document is allowed to use the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) to create new WebAuthn credentials, i.e., via {{domxref("CredentialsContainer.create","navigator.credentials.create({publicKey})")}}.
 
-Specifically, where a defined policy blocks use of this feature, the {{jsxref("Promise")}} returned by `navigator.credentials.create({publicKey})` will reject with a `SecurityError` {{domxref("DOMException")}}.
+Specifically, where a defined policy blocks use of this feature, the {{jsxref("Promise")}} returned by `navigator.credentials.create({publicKey})` will reject with a `NotAllowedError` {{domxref("DOMException")}}.
+If the method is called cross-origin. the {{jsxref("Promise")}} will also reject with a `NotAllowedError` if the feature is granted by [`allow=` on an iframe](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes) and the frame does not also have {{glossary("Transient activation")}}.
 
 ## Syntax
 

files/en-us/web/http/headers/permissions-policy/publickey-credentials-get/index.md

@@ -9,7 +9,7 @@ browser-compat: http.headers.Permissions-Policy.publickey-credentials-get
 
 The HTTP {{HTTPHeader("Permissions-Policy")}} header `publickey-credentials-get` directive controls whether the current document is allowed to access the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) to retrieve public-key credentials, i.e., via {{domxref("CredentialsContainer.get","navigator.credentials.get({publicKey})")}}.
 
-Specifically, where a defined policy blocks the use of this feature, the {{jsxref("Promise")}} returned by `navigator.credentials.get({publicKey})` will reject with a `SecurityError` {{domxref("DOMException")}}.
+Specifically, where a defined policy blocks the use of this feature, the {{jsxref("Promise")}} returned by `navigator.credentials.get({publicKey})` will reject with a `NotAllowedError` {{domxref("DOMException")}}.
 
 ## Syntax