WebOTP API

1. Introduction

This section is non-normative.

Many web sites need to verify credentials (e.g. phone numbers and email addresses) as part of their authentication flows. They currently rely on sending one-time-passwords (OTP) to these communication channels to be used as proof of ownership. The one-time-password is manually handed back by the user (typically by copying/pasting) to the web app which is onerous and erroneous.

This a proposal for a client side javascript API that enables web sites to request OTPs and a set of transport-specific conventions (we start with SMS while leaving the door open to others) that can be used in coordination with browsers.

1.1. The client side API

In this proposal, websites have the ability to call a browser API to request OTPs coming from specific transports (e.g. via SMS).

The browser intermediates the receipt of the SMS and the handing off to the calling website (typically asking for the user’s consent), so the API returns a promise asynchronously.

let {code, type} = await navigator.credentials.get({
  otp: {
    transport: ["sms"]
  }
});

1.2. The server side API

Once the client side API is called, the website’s server can send OTPs to the client via the requested transport mechanisms. For each of these transport mechanism, a server side convention is set in place to guarantee that the OTP is delivered safely and programatically.

For SMS, for example, servers should send origin-bound one-time code messages to clients. [sms-one-time-codes]

"Your authentication code is 123456.

@example.com #123456"

1.3. Feature Detection

Not all user agents necessarily need to implement the WebOTP API at the exact same moment in time, so websites need a mechanism to detect if the API is available.

Websites can check for the presence of the OTPCredential global interface:

if (!window.OTPCredential) {
  / feature not available
  return;
}

1.4. Web Components

For the most part, OTP verification largely relies on:

• input, forms and copy/paste, on the client side and

• third party frameworks to send SMS, on the server side.

We expect some of these frameworks to develop declarative versions of this API to facilitate the deployment of their customer’s existing code.

<script src="sms-sdk.js"></script>

<form>
  <input is="one-time-code" required />
  <input type="submit" />
</form>

And here is an example of how a framework could implement it using web components:

customElements.define("one-time-code",
  class extends HTMLInputElement {
    connectedCallback() {
      this.receive();
    }
    async receive() {
      let {code, type} = await navigator.credentials.get({
        otp: {
         transport: ["sms"]
        }
      });
      this.value = otp;
      this.form.submit();
    }
  }, {
    extends: "input"
});

1.5. Abort API

Many modern websites handle navigations on the client side. So, if a user navigates away from an OTP flow to another flow, the request needs to be cancelled so that the user isn’t bothered with a permission prompt that isn’t relevant anymore.

To facilitate that, an abort controller can be passed to abort the request:

const abort = new AbortController();

setTimeout(() => {
  / abort after two minutes
  abort.abort();
}, 2 * 60 * 1000);
  
let {code, type} = await navigator.credentials.get({
  signal: abort.signal,
  otp: {
    transport: ["sms"]
  }
});

2. Client Side API

Websites call navigator.credentials.get({otp:..., ...}) to retrieve an OTP.

The algorithm of Request a Credential abstract operation.

OTPCredential's [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors), and defines its own implementation of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors).

[SecureContext]
interface OTPCredential : Credential {
    readonly attribute DOMString code;
};

id

This attribute is inherited from Credential

[[type]]

The OTPCredential [[type]] internal slot's value is the string "otp".

code, of type DOMString, readonly

The retrieved one time password.

2.1.1. The [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) Method

This method is called every time navigator.credentials.get({otp:..., ...}) and is responsible for returning an OTP when one is requested (i.e. when options.otp is passed).

This internal method accepts three arguments:

origin

This argument is the origin, as determined by the calling Request a Credential abstract operation.

options

This argument is a CredentialRequestOptions object whose options.otp member contains a OTPCredentialRequestOptions object specifying the desired attributes of the OTP to retrieve.

sameOriginWithAncestors

This argument is a Boolean value which is true if and only if the caller’s same-origin with its ancestors. It is false if caller is cross-origin.

Note: Invocation of this internal method indicates that it was allowed by permissions policy, which is evaluated at the [CREDENTIAL-MANAGEMENT-1] level. See § 2.5 Permissions Policy integration.

1. Assert: options.otp is present.

2. Let options be the value of options.otp.

3. Let callerOrigin be origin. If callerOrigin is an NotAllowedError", and terminate this algorithm.

4. Let effectiveDomain be the callerOrigin’s effective domain. If SecurityError" and terminate this algorithm.

   Note: An host, which can be represented in various manners, such as opaque host, or empty host. Only the host is allowed here. This is for simplification and also is in recognition of various issues with using direct IP address identification in concert with PKI-based security.

5. If the options.AbortError" and terminate this algorithm.

6. TODO(goto): figure out how to connect the dots here with the transport algorithms.

partial dictionary CredentialRequestOptions {
    OTPCredentialRequestOptions otp;
};

dictionary OTPCredentialRequestOptions {
  sequence<OTPCredentialTransportType> transport = [];
};

enum OTPCredentialTransportType {
    "sms",
};

Your verification code is: MUAHAHAHA

@example.com #MUAHAHAHA