Normalize CredentialsContainer.create() method

files/en-us/glossary/authentication/index.md

@@ -0,0 +1,23 @@
+---
+title: Authentication
+slug: Glossary/Authentication
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+**Authentication** is in general the process of proving that some fact is genuine. More specifically, in web security, it is the process of verifying the claimed identity of some entity, such as a user. This then makes it possible to decide whether to grant the user the access that they are requesting, such as being signed into a particular account.
+
+Authentication is typically performed by having a user present a user identifier along with a {{glossary("credential")}}, such as a password, a one-time SMS code, or an assertion signed with a private key. The system then checks the binding between the user identifier and the credential, so it can decide whether or not to authenticate the user.
+
+Types of authentication information, also called _authentication factors_, are commonly presented in three categories:
+
+- Something the user knows, such as a password.
+- Something the user has, such as a phone.
+- Something the user is, such as a thumbprint.
+
+Multi-factor authentication (MFA) systems require the user to provide more than one factor: for example, a password combined with a one-time code sent to the user's phone.
+
+## See also
+
+- {{rfc("4949", "Internet Security Glossary")}}

files/en-us/glossary/credential/index.md

@@ -0,0 +1,22 @@
+---
+title: Credential
+slug: Glossary/Credential
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+A **credential** is an object which enables a system to make an {{glossary("authentication")}} decision: for example, to decide whether to sign a user into an account.
+
+In web security, types of credential include:
+
+- a password
+- biometric data
+- a token entered from a one-time SMS code
+- the key used to make authentication assertions in a public-key system such as [Web Authentication](/en-US/docs/Web/API/Web_Authentication_API)
+
+The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) enables develepers to create, store, and retrieve various types of credential.
+
+## See also
+
+- {{rfc("4949", "Internet Security Glossary")}}

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

@@ -0,0 +1,55 @@
+---
+title: FederatedCredentialInit
+slug: Web/API/FederatedCredentialInit
+page-type: web-api-interface
+spec-urls: https://w3c.github.io/webappsec-credential-management/#dom-federatedcredential-federatedcredential
+---
+
+{{APIRef("Credential Management API")}}{{SecureContext_Header}}
+
+The **`FederatedCredentialInit`** dictionary represents the object passed to {{domxref("CredentialsContainer.create()")}} as the value of the `federated` option: that is, when using `create()` to create a federated identify provider credential.
+
+Note that the [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) supersedes this credential type.
+
+## Instance properties
+
+- `iconURL` {{optional_inline}}
+  - : A string representing the URL of an icon or avatar to be associated with the credential.
+- `id`
+  - : A string representing a unique ID for the credential.
+- `name` {{optional_inline}}
+  - : A string representing the credential username.
+- `origin`
+  - : A string representing the credential's origin. {{domxref("FederatedCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
+- `protocol` {{optional_inline}}
+  - : A string representing the protocol of the credentials' federated identity provider (for example, `"openidconnect"`).
+- `provider`
+  - : A string representing the credentials' federated identity provider (for example `"https://www.facebook.com"` or `"https://accounts.google.com"`).
+
+## Examples
+
+### Creating a federated identity credential
+
+```js
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  protocol: "openidconnect",
+  provider: "https://provider.example.org",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    federated: credInit,
+  });
+  console.log(cred.name);
+  console.log(cred.provider);
+});
+```
+
+## Specifications
+
+{{Specifications}}

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

@@ -0,0 +1,163 @@
+---
+title: PasswordCredentialInit
+slug: Web/API/PasswordCredentialInit
+page-type: web-api-interface
+spec-urls: https://w3c.github.io/webappsec-credential-management/#typedefdef-passwordcredentialinit
+---
+
+{{APIRef("Credential Management API")}}{{SecureContext_Header}}
+
+The **`PasswordCredentialInit`** dictionary represents the object passed to {{domxref("CredentialsContainer.create()")}} as the value of the `password` option: that is, when using `create()` to create a password credential.
+
+## Initialization from a form
+
+Instead of passing this dictionary directly, a website can pass an {{domxref("HTMLFormElement")}}, and the implementation of `create()` will populate the credential's data from the values of the form's submittable elements, based on the value of the element's [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute.
+
+| `autocomplete` value                     | Credential property targeted |
+| ---------------------------------------- | ---------------------------- |
+| `"username"`                             | `id`                         |
+| `"name"` or `"nickname"`                 | `name`                       |
+| `"new-password"` or `"current-password"` | `password`                   |
+| `"photo"`                                | `iconURL`                    |
+
+If the form contains both `"new-password"` and `"current-password"` elements, the value for `"new-password"` will be used.
+
+The `origin` property is set to the origin of the document the {{domxref("HTMLFormElement")}} is contained within.
+
+## Instance properties
+
+- `iconURL` {{optional_inline}}
+  - : A string representing the URL of an icon or avatar to be associated with the credential.
+- `id`
+  - : A string representing a unique ID for the credential.
+- `name` {{optional_inline}}
+  - : A string representing the credential username.
+- `origin`
+  - : A string representing the credential's origin. {{domxref("PasswordCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
+- `password`
+  - : A string representing the credential password.
+
+## Examples
+
+### Creating a password credential from an object literal
+
+This example constructs an object literal to initialize a password credential.
+
+```js
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  password: "the last visible dog",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    password: credInit,
+  });
+  console.log(cred.name);
+  // Serpentina
+  console.log(cred.password);
+  // the last visible dog
+});
+```
+
+### Creating a password credential from a form
+
+This example uses a form to initialize a password credential.
+
+#### HTML
+
+The HTML declares a {{HTMLElement("form")}} containing three submittable elements, representing the user ID, user's display name, and password.
+
+```html
+<form>
+  <div>
+    <label for="userid">Enter your user ID: </label>
+    <input type="text" name="userid" id="userid" autocomplete="username" />
+  </div>
+  <div>
+    <label for="username">Enter your username: </label>
+    <input type="text" name="username" id="username" autocomplete="name" />
+  </div>
+  <div>
+    <label for="password">Enter your password: </label>
+    <input
+      type="password"
+      name="password"
+      id="password"
+      autocomplete="new-password" />
+  </div>
+</form>
+
+<button id="make-credential">Make credential</button>
+
+<pre id="log"></pre>
+```
+
+```css hidden
+form {
+  display: table;
+}
+
+div {
+  display: table-row;
+}
+
+label,
+input {
+  display: table-cell;
+  margin-bottom: 10px;
+}
+
+label {
+  padding-right: 10px;
+}
+
+#log {
+  height: 60px;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+#### JavaScript
+
+The JavaScript passes the form into `create()`, and logs some of the values of the resulting credential.
+
+The promise returned by `create()` will reject if the form does not contain values for the mandatory credential properties.
+
+```js
+const makeCredential = document.querySelector("#make-credential");
+const formCreds = document.querySelector("form");
+
+makeCredential.addEventListener("click", async () => {
+  try {
+    const credential = await navigator.credentials.create({
+      password: formCreds,
+    });
+    log(
+      `New credential:\nname: ${credential.name}, password: ${credential.password}`,
+    );
+  } catch (e) {
+    if (e.name === "TypeError") {
+      log("Error creating credential\nMake sure you filled in all the fields");
+    }
+  }
+});
+
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = text;
+}
+```
+
+#### Result
+
+{{EmbedLiveSample("Creating a password credential from a form", "", "260")}}
+
+## Specifications
+
+{{Specifications}}

files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md

@@ -10,7 +10,7 @@ browser-compat: api.PublicKeyCredential.parseCreationOptionsFromJSON_static
 
 {{APIRef("Web Authentication API")}} {{SeeCompatTable}}{{securecontext_header}}
 
-The **`parseCreationOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface converts a {{glossary("JSON type representation")}} into its corresponding [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+The **`parseCreationOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface creates a {{domxref("PublicKeyCredentialCreationOptions")}} object from a JSON representation of its properties.
 
 The method is a convenience function for converting credential options information provided by a relying party server to the form that a web app can use to [create a credential](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user).
 
@@ -24,25 +24,25 @@ PublicKeyCredential.parseCreationOptionsFromJSON(options)
 
 - `options`
 
-  - : An object with the same structure as the Web Authentication API [`publicKey` create credentials options object](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure), but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties.
+  - : An object with the same structure as a {{domxref("PublicKeyCredentialCreationOptions")}}, but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties.
 
 ### Return value
 
-An object with the Web Authentication API [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+A {{domxref("PublicKeyCredentialCreationOptions")}} object.
 
 ### Exceptions
 
 - `EncodingError` {{domxref("DOMException")}}
-  - : Thrown if any part of the `options` object cannot be converted into the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+  - : Thrown the `options` object cannot be converted into a {{domxref("PublicKeyCredentialCreationOptions")}} object.
 
 ## Description
 
 The Web Authentication process for [creating a key pair and registering a user](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user) involves a relying party server sending the web app information needed to create a credential, including details about the user identity, the relying party, and a "challenge".
-The web app passes this information to an authenticator to create the credential, by calling [`navigator.credentials.create()`](/en-US/docs/Web/API/CredentialsContainer/create) with an argument that contains the server-supplied data in the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+The web app passes this information to an authenticator to create the credential, by calling [`navigator.credentials.create()`](/en-US/docs/Web/API/CredentialsContainer/create) with a {{domxref("PublicKeyCredentialCreationOptions")}} object as an argument.
 
 The specification does not define how the information needed for creating a credential is sent.
-A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the [`publicKey` create credentials options object](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure) that mirrors its structure but encodes buffer properties such as the `challenge` and `user.id` as [base64url](/en-US/docs/Glossary/Base64) strings.
-This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure) using **`parseCreationOptionsFromJSON()`**.
+A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the {{domxref("PublicKeyCredentialCreationOptions")}} object that mirrors its structure but encodes buffer properties such as the `challenge` and `user.id` as [base64url](/en-US/docs/Glossary/Base64) strings.
+This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to a {{domxref("PublicKeyCredentialCreationOptions")}} object using **`parseCreationOptionsFromJSON()`**.
 
 ## Examples