Rename PublicKeyCredentialSource.uvInitialized

[zll600]

Description

uvInitialized works fine for me. However, I suggest renaming uvInitialized to uvFlag or something similar.

Because as the spec mentioned:

A Boolean value indicating whether any credential from this public key credential source has had the UV flag set.

At the registration ceremony, the uvInitialized should be persisted as a property of a created credential record.

At the authentication ceremony, the RP may do something according to its authentication policy by comparing the uvInitialized kept in the database(or something) and the authData.UV.

So as a library, it's enough for us to return the authData.UV by the API. And let the RP do what it wants to do.

---

This idea may not be perfect. Feel free to close this issue 🫶

[Spomky]

Hi,

According to the specification, uvInitialized is not simply the UV bit from an authenticator, but a persisted indicator in the credential record that tracks whether this credential has ever returned UV = 1. Renaming it to uvFlag could be misleading. Keeping it aligned with the specification helps avoid confusion.

[zll600]

Hi, here are my thoughts. Please correct me if I am wrong.

According to the specification, uvInitialized is not simply the UV bit from an authenticator, but a persisted indicator in the credential record that tracks whether this credential has ever returned UV = 1

I agree with this point. It means the uvInitialized should be a persistent property of the credential record kept by the PR.

Next, let's look at the following part from the spec:

This is because the first time a public key credential source sets the UV flag to 1, there is not yet any trust relationship established between the Relying Party and the authenticator’s user verification. Therefore, updating uvInitialized from false to true SHOULD require authorization by an additional authentication factor equivalent to WebAuthn user verification.

IMO, the spec wants to say the RP can initiate additional authentication when updating the uvInitialized of the credential record, when a user authenticates with a valid passkey.

The reasons why I want to rename the uvInitialized of the PublicKeyCredentialSource are

1. The library/framework can not know the additional authentication that the RP wants to launch.
2. The spec emphasized spec is 'A Boolean value indicating whether any credential from this public key credential source has had the UV flag set', which requires it has been persisted. But the library/framework can only give the RP the UV flag of the current attestation, not the real uvInitialized, which is persistent by the RP

For example

use Webauthn\PublicKeyCredential;
use Webauthn\PublicKeyCredentialCreationOptions;

class Test {

    public validateAttestation(PulibcKeyCredential $publicKeyCredential, PublicKeyCredentialCreationOptions $publicKeyCredentialCreationOptions) {
       // validate attestation
       $credentialRecord = $this->getAuthenticatorAttestationResponseValidator()
            ->check($publicKeyCredential->response, $publicKeyCredentialCreationOptions, 'localhost');
       
      if ($credentialRecord->uvInitialized === true) {
         // 1. RP check uvInitialized persistent in database
         if ((uvInitialized of database) === false) {
            // 2. RP initiates 2FA(e.g., TOTP) to confirm the current user.
            // 3. update the uvInitialized of the database
            (uvInitialized of database) = true;
         }
      }
    }
}