Using CredentialsContainer.get() instead of Payment Request API

[tblachowicz]

The initial proposal assumed that Payment Request API (PR API) should be used to trigger the SPC flow. The client code would use PR API providing the payment method as predefined value e.g. "secure-payment-confirmation" and the necessary parameters such as total amount, cryptographic nonce, fallback URL, and so on.

Alternatively, the same SPC flow could be triggered simply by invoking the Credential Management API CredentialsContianer.get() method as it happens for other types of credentials. Example SPRC request:

navigator.credentials. get({
  spc:{
    credentialIds: 'array of credential identifiers',
    amount: 'amount w/currency',
    nonce: 'server-side generated cryptographic nonce',
    fallbackUrl: 'URL of the fallback page',
    timeout: 'timeout for the request'
})

Similarly, the SPCCredential or PaymentCredential would extend the Credential interface to be consistent with the Credential Management API.

Are there any clear benefits of using Payment Request API instead of Credential Management API?

[stephenmcgruer]

I am not aware of any clear benefits of using the Payment Request API over the Credential Management API, but I'm also not aware of clear benefits of using the Credential Management API over the Payment Request API :D.

In either case, we need to bring together payment information and authentication information. As you note, in the initial proposal (and in what we implemented and trialed in Chromium), we brought authentication information into Payment Request. We did this because it was the Web Payments team that was working on this API, not the folks who are involved with the Credential Management API.

Do you see a clear benefit to using the Credential Management API?

(cc @equalsJeffH @mikewest )

[tblachowicz]

At the moment I cannot really point out any clear technical benefits of using CM API over PR API. However, I think the SPC is closer conceptually to CM API than it is to PR API, especially if we also consider enrollment of the payment instrument as well.

Credential Management API provides a way for the website to store/create and retrieve the different types of credentials via the convenient API. When we consider SPC it's also about storing and retrieving the credentials of a specific type. CM API provides abstract classes and interfaces that are extended to support the specific types of credentials e.g. password or public key. I can imagine SPC extending the CM API to allow the client to provide SPC-specific parameters to both create and retrieve the SPC-specific credentials.

If we'd decide to use PR API to trigger retrieval of the SPC Credentials we still need to consider how to create/store the credentials in the user-agent. If I'm not mistaken the initial proposal actually suggests using Credential Management API to do so. Therefore, why not use Credential Management API also for storing/creating the credentials?

[adrianhopebailie]

The purpose of using the Payment Request API is that this provides a structured data object with the transaction details.

It's natural for a developer to request a payment via a payment API, where SPC is part of that flow. Admittedly it might be the only required part of that flow but it is also possible that the flow includes invocation of a Payment Handler or prompting the user to select between multiple payment instruments that match the conditions provided in the request.

[equalsJeffH]

I agree with @adrianhopebailie: use a payments-focused API for payments.

[tblachowicz]

OK. It seems people favor Payment APIs over Credential Management APIs. I think it's difficult to construct objective arguments, so this is based on preferences. Good to have a discussion anyways!

[adrianhopebailie]

@tblachowicz I wouldn't say it's just personal preference. By using payment specific APIs we solve a lot of privacy challenges for the browser.

When a website invokes a payment API (as opposed to a general purpose API) then the browser can assume the context is a payment and can do things like show payment specific UI that would expose malicious websites that attempt to use the API for non-payment uses cases (tracking or farming data).

[ianbjacobs]

Labeled after-v1 based on 3 March 2022 WG discussion https://www.w3.org/2022/03/03-wpwg-minutes

[stephenmcgruer]

Hey folks,

The following is a proposal as to what moving to navigator.credentials.get might look like, and some of the pros/cons. On the Chrome side, we are definitely still unsure about what the right path is forward here - we have found basing this on PaymentRequest to be quite awkward and a source of implementor bugs, but also it is not clear that navigator.credentials.get() would be better-enough to be worth the switch!

Background

Secure Payment Confirmation currently uses PaymentRequest as its API entry point:

// On, e.g., merchant.com
const request = new PaymentRequest([{
  supportedMethods: 'secure-payment-confirmation',
  data: {
    credentialIds: [ … ],
    rpId: 'bank.com',
    challenge: ...,
    instrument: {
      displayName: 'Fancy Card ****1234',
      icon: 'https://fancybank.com/card-art.png',
    },

    payeeName: 'Merchant Shop',
    payeeOrigin: 'https://merchant.com',

    timeout: 360000,
  }],
  {
    total: {
      label: 'Total',
      amount: { currency: 'USD', value: '5.00' }
    }
  });

try {
  const response = await request.show();
  await response.complete('success');

  // response.data is a PublicKeyCredential, with a clientDataJSON
  // that contains the transaction data for verification by the
  // issuing bank.
} catch (e) {
  // Handle SPC cancellation/failure, e.g. by presenting an
  // alternative authentication method.
}

This was done for a few reasons that I am aware of:

1. The Web Payments Working Group (WPWG) was used to working with PaymentRequest as an API surface, and so naturally biased itself that way.
2. Originally it was not clear that SPC would be closely tied with WebAuthn - currently this is no longer true and SPC directly uses WebAuthn.

However, using PaymentRequest for SPC also comes with downsides:

1. Mismatch in purpose - PaymentRequest is meant to handle payment experiences (e.g., processing a full payment via a payment app), whilst SPC is (arguably) more of an authentication experience tailored towards payments.
2. PaymentRequest has a number of sub-APIs that make little sense for SPC:
   • canMakePayment() - for SPC, this is just a feature-detection method.
   • hasEnrolledInstrument() - has no use for SPC.
   • PaymentResponse.retry() - can only be called on a successful SPC invocation (failure rejects the promise instead), and so has little/no use for SPC.
   • PaymentResponse.complete() - unnecessary for SPC, but developers have to call it anyway or Bad Things Happen.
   • Asking for shipping addresses or contact info - Prohibited with SPC.
   • Specifying multiple payment methods in one request - Prohibited with SPC.
3. A PaymentHandler hosted payment app (e.g., Google Pay) cannot invoke SPC, as PaymentRequest doesn't allow nested calls.
   • For Chrome, this is more of a technical constraint currently, and would not be automatically fixed by changing API surface.
4. PaymentRequest.show() requires a user gesture, whilst WebAuthn’s credentials.get() does not. We are currently considering which is correct in Proposal: Remove User Activation requirement for authentication #216

The Proposal

Move SPC to be called by web developers via navigator.credentials.get(). This is largely straight-forward as SPC already defines an internal WebAuthn extension. We would expose that extension and let developers use it directly instead of via PaymentRequest:

// On, e.g., merchant.com
navigator.credentials.get({
  publicKey: {
    allowCredentials: [...],
    rpId: 'bank.com',
    challenge: ...,
    timeout: 360000,
    extensions: {
      payment: {
        payeeName: 'Merchant Shop',
        payeeOrigin: 'https://merchant.com',
        total: {
          currency: 'USD',
          amount: '5.00',
        },
        instrument: {
          displayName: 'Fancy Card ****1234',
          icon: 'https://fancybank.com/card-art.png',
        },
      },
    },
  }
});

There are two changes from the AuthenticationExtensionsPaymentInputs as currently specified in SPC: the rpId field is removed as it is represented elsewhere in the get() call, and the topOrigin field is removed as we have to calculate that in the browser and not allow the website to specify it.

Pros / Cons

(A possibly incomplete list!)

Pros:

• Move SPC away from being a 'payment' thing and towards it being an 'authentication' thing.
• Simplify the SPC API for developers:
  • Remove methods that are functionally unnecessary (e.g., complete()), or pointless (e.g., retry()).
  • Requires us to make feature detection much simpler (see below), though we can do that anyway without changing the API surface (see Make it easy to determine whether a user agent supports SPC #81).
• Make it easier for SPC to support future changes to WebAuthn, e.g. the newly added get()-time parameters for attestation.
  • Currently we have to add these new parameters to SPC as pass-throughs to the underlying WebAuthn call.
• Very hand-wavy and hypothetical - but if we were to support SPC for native Android Apps, we think we would make it use the same API surface as WebAuthn for native Android Apps, rather than invent PaymentRequest at the Android layer.

Cons:

• Move SPC away from being a 'payment' thing and towards it being an 'authentication' thing.
  • (Yes, deliberately included in both lists!)
• Some folks have suggested having a non-WebAuthn backed version of SPC for cases where authentication should be 'lighter', e.g. using WebCrypto instead, and this API change would impede that.
• Awkward fallback behavior in non-supporting web browsers (see below).
• SPC would be a fairly complex WebAuthn extension, if we spec'd all the behavior in the extension.
  • However note that devicePubKey already exists as an extension and is likely more complicated that what we would define.
• Churn of an already-shipped API, will require a deprecation effort from Chrome.

Fallback Behavior // Feature Detection

A strange consequence of moving SPC into a 'public' WebAuthn extension is that - unlike other WebAuthn extensions - the fallback behavior in a non-supporting browser can be actively undesirable for the calling website. Instead of rejecting the get() call, a non-supporting browser will ignore the payment extension entirely and show a normal WebAuthn experience to the user, producing a WebAuthn cryptogram. However if the caller requires payment details in the cryptogram, this cryptogram is useless to them and the user's time has been wasted!

Note: this only happens in the '1p' SPC case, where the current origin is also the Relying Party. In the '3p' SPC case, the get() call immediately rejects in a non-supporting browser as the rpId will mismatch. However the '1p' SPC case is still of significant importance!

To address this, we propose introducing a static method on PublicKeyCredential to indicate support (or lack thereof) for SPC:

partial interface PublicKeyCredential {
    static Promise<boolean> isSecurePaymentConfirmationAvailable();
};

This is very similar to the proposal in #81 already for PaymentRequest. It is also similar to the existing methods for detecting support for a user-verifying platform authenticator or for conditional mediation.

Summary

In summary, we think it would be feasible to move to navigator.credentials.get. It would solve some of the awkwardness of the current API surface, but would also present its own challenges.

We would be interested in discussing this at the Working Group, but most interested in hearing from developers who have already or are currently experimenting with SPC to see how much the API shape impacts them!

[ianbjacobs]

cc @dcrousso

[ianbjacobs]

Thanks, @stephenmcgruer. I would add as a "pro" that not having to also implement Payment Request API could make SPC much easier for browser makers to implement.