Replace in-field string metadata with resource-level default fields #2280

emlun · 2025-04-09T16:03:33Z

This addresses #1643:

We request that you do the following:

Remove the in-field encoding of language metadata using Unicode tag characters

Remove the in-field encoding of string direction using strongly directional marks

Add a document-level field for the document language and a document-level field for default direction; such fields would be optional, since you have an installed base

New language and direction attributes on PublicKeyCredentialUserEntity seems like the most appropriate implementation of a "document-level field", since these are the only natural language string parameters we have. The new attributes won't work with currently existing CTAP authenticators, but their processing is specified as "best-effort" (at least that's the intent) so RPs should be aware that they might not work.

The following tasks have been completed:

Modified Web platform tests (link)

Implementation commitment:

WebKit (link to issue)
Chromium (link to issue)
Gecko (link to issue)

Documentation and checks

N/A ~~Affects privacy~~
N/A ~~Affects security~~
N/A ~~Updated explainer~~

Preview | Diff

aphillips

Looks good. Thank you for this!

I made a few comments.

index.bs

aphillips

Looks good. Thanks!!!

aphillips · 2025-04-10T13:24:36Z

index.bs

+1. If <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code> is present
+    and is not a [=well-formed language tag=], throw a "{{SyntaxError}}" {{DOMException}}.


One final thought: this requirement feels like it might push implementations that don't support the language field to do extra work. The field is optional and supporting the value is optional, but this clearly says that implementations need to check the tag's structure if the field is present.

String-Meta recommends but does not require that you emit an error here. I'd suggest handling language similar to direction and ignoring the field if the tag is not well-formed.

I see what you mean, but I'm still more inclined to keep the error in the interest of "fail faster". Of course no error will be thrown here if the client implementation predates WebAuthn L3, so there will always be that possibility, but I still think that clients that know the field exists should verify its well-formedness when present - even if the client otherwise ignores the value.

I think this position is also supported by the W3C priority of consituencies: "[...] the needs of web page authors [...] come before the needs of user agent implementors, [...]".

emlun · 2025-04-11T18:06:58Z

From 2025-04-11 face-to-face WG meeting:

It's unclear what clients would do differently for different language values, especially considering these values (user.name and user.displayName) are likely chosen by the user in some way. Is the language field needed here?

selfissued · 2025-04-23T18:16:57Z

index.bs

+                <td>|userLanguage|</td>
+                <td>
+                    The [=resource-wide default=] language tag for the {{PublicKeyCredentialUserEntity|user}} entity associated to the credential.
+                    This property may not be defined.


Suggested change

This property may not be defined.

Note that this property might not be present.

Thanks, but I'm going to reject this proposal as "This property may not be defined" is the formulation already used for userHandle and largeBlob:

webauthn/index.bs

Lines 8003 to 8006 in 6507c4c

<td>|userHandle|</td>

<td>

The [=public key credential source/userHandle=] associated to the credential encoded using

[=Base64url Encoding=]. This property may not be defined.

webauthn/index.bs

Lines 8016 to 8019 in 6507c4c

<td>|largeBlob|</td>

<td>

The [=large, per-credential blob=] associated to the [=public key credential source=], encoded using [=Base64url Encoding=].

This property may not be defined.

selfissued · 2025-04-23T18:17:28Z

index.bs

+                <td>|userDirection|</td>
+                <td>
+                    The [=resource-wide default=] [=string direction=] for the {{PublicKeyCredentialUserEntity|user}} entity associated to the credential.
+                    This property may not be defined.


Suggested change

This property may not be defined.

Note that this property might not be present.

See #2280 (comment)

index.bs

…er Add Credential

Co-authored-by: Michael B. Jones <michael_b_jones@hotmail.com>

nadalin · 2025-04-30T19:11:21Z

@selfissued can you review to make sure your issues have been resolved

MasterKale · 2025-04-30T19:16:00Z

index.bs

@@ -1767,6 +1771,9 @@ When this method is invoked, the user agent MUST execute the following algorithm

 1. If the length of <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/id}}</code> is not between 1 and 64 bytes (inclusive) then throw a {{TypeError}}.

+1. If <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code> is present
+    and is not a [=well-formed language tag=], throw a "{{SyntaxError}}" {{DOMException}}.


WebAuthn typically raises TypeError's when there's an issue with a malformed value, as documented in L3:

https://w3c.github.io/webauthn/#sctn-create-request-exceptions

https://w3c.github.io/webauthn/#sctn-get-request-exceptions

We should probably maintain this behavior for this exception too.

Hm. I see what you mean, but TypeError is not semantically correct for this error case. The user.id error ideally should have been a SyntaxError too, but that's probably too late to change now. SyntaxError is also used by the PRF extension when base64 decoding fails. So I'd prefer to keep this as SyntaxError rather than TypeError.

MasterKale · 2025-04-30T19:16:27Z

index.bs

+    :   {{SyntaxError}}
+    ::  <code>{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code>
+        was present and was not a [=well-formed language tag=].
+


If we agree to keep things consistent with TypeError as I call out above, we'll want to take this out.

MasterKale · 2025-04-30T19:16:52Z

index.bs


 Upon invocation of {{PublicKeyCredential/signalCurrentUserDetails(options)}}, the
 [=client=] executes these steps:

 1. If the result of [=base64url encoding | base64url decoding=]
    <code>|options|.{{CurrentUserDetailsOptions/userId}}</code> is an error,
    then return [=a promise rejected with=] a {{TypeError}}.
+1. If <code>|options|.{{CurrentUserDetailsOptions/language}}</code> is present
+    and is not a [=well-formed language tag=],
+    then return [=a promise rejected with=] a "{{SyntaxError}}" {{DOMException}}.


Tagging another SyntaxError pending a decision about sticking with TypeError as called out above.

nsatragno · 2025-04-30T19:41:10Z

index.bs


-So the string “حبیب الرحمان” could have two different DOMString values, depending on whether the language was encoded or not. (Since the direction is unambiguous a directionality marker is not needed in this example.)
+Instead, the Level 3 [=Web Authentication API=] provides [=resource-wide default=] fields for encoding language and direction metadata
+which SHOULD be used when supported by the [=client=] and [=authenticator=].


How does a relying party know if the client/authenticator support the new language tags?

It doesn't... but I think I see what you mean. When I wrote "SHOULD be used" I meant "[the client] should use them [when provided by the RP and supported by the authenticator]", but your reading was "[the RP] should use them [when supported by the client and authenticator]"? That's definitely an ambiguity I need to fix.

Anything else to do here after fixing that ambiguity?

Does 5d2e401 resolve this ambiguity?

nsatragno · 2025-04-30T19:42:46Z

index.bs

@@ -1767,6 +1771,9 @@ When this method is invoked, the user agent MUST execute the following algorithm

 1. If the length of <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/id}}</code> is not between 1 and 64 bytes (inclusive) then throw a {{TypeError}}.

+1. If <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code> is present


Should we require language and direction be present if the other one is? i.e. if language is present, direction cannot be undefined.

I don't think so, String-Meta specifically describes these as separate values. It doesn't look like either should require the other.

nsatragno · 2025-04-30T19:53:57Z

index.bs

@@ -240,6 +240,10 @@ spec: RFC8610; urlPrefix: https://tools.ietf.org/html/rfc8610
    type: dfn
        text: group sockets; url: section-3.9

+spec: String-Meta; urlPrefix: https://www.w3.org/TR/2024/NOTE-string-meta-20241017


General comment:

I understand this is the i18n wg proposal, but this approach feels strictly worse, since authenticators have to support it for browsers to take advantage of it.

nsatragno · 2025-04-30T19:54:50Z

index.bs

@@ -2926,6 +2938,8 @@ value and terminate the operation.
        required Base64URLString        id;
        required DOMString              name;
        required DOMString              displayName;
+        DOMString                       language;


Was it decided whether we needed language or not?

MasterKale

A language map might be a better pattern here:

https://www.w3.org/TR/2024/NOTE-string-meta-20241017/#language-maps

For example, if we added a new "user.localizedName" property, that looked like this...

localizedName: {
  "en-US": {
    value: "...",
    dir: "ltr"
  }
}

...then processing rules could say clients should use a value in user.localizedName when present, otherwise fall back to user.name.

The same could be done with a "user.localizedDisplayName" too.

selfissued

Ready to go, as far as I'm concerned

MasterKale · 2025-05-28T19:13:38Z

From WG meeting @ May 28: We'll wait till next week's meeting when we can have a more direct discussion on the "best" path forward

dwaite · 2025-05-28T19:35:49Z

Question since I don't quite understand from conversation - is there a reason the UserEntity fields (language, direction and value) can't be encoded by the client into a single string behind the API using STRINGPREP, and decoded by the client when read? (theoretically read - I don't believe we expose displayName back into the API today)

This would mean that we are using STRINGPREP internally only, otherwise banning its use on the web-facing API. This allows for improvements on a more arbitrary schedule to the backing CTAP and platform specifications.

Replace in-field string metadata with resource-level default fields

696afca

emlun added type:technical subtype:algorithms/WebIDL labels Apr 9, 2025

emlun requested review from pascoej, nsatragno, MasterKale, timcappalli, selfissued, jschanck and akshayku April 9, 2025 16:03

emlun self-assigned this Apr 9, 2025

This was referenced Apr 9, 2025

Use of in-field metadata not preferred #1643

Open

[Editorial] Truncation description inaccurate #1645

Open

aphillips reviewed Apr 9, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

index.bs Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

emlun added 3 commits April 10, 2025 12:10

Clarify meaning of "entity" in String-Meta attribute descriptions

1bcd085

Remove "now" as suggested in review

8426a00

Add direction attribute to signalCurrentUserDetails example

01aada9

aphillips approved these changes Apr 10, 2025

View reviewed changes

MasterKale mentioned this pull request Apr 11, 2025

[L3 CR] Horizontal Review: Internationalization (i18n) #2245

Open

MasterKale mentioned this pull request Apr 11, 2025

[L3 CR] Internationalization Self-Review #2260

Open

24 tasks

Use "string direction" instead of "block direction"

bc361f8

pascoej approved these changes Apr 23, 2025

View reviewed changes

selfissued reviewed Apr 23, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

selfissued reviewed Apr 23, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

selfissued reviewed Apr 23, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

selfissued reviewed Apr 23, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

Specify behaviour for undefined userLanguage/userDirection in WebDriv…

6507c4c

…er Add Credential

Apply suggestions from code review

d12bd28

Co-authored-by: Michael B. Jones <michael_b_jones@hotmail.com>

timcappalli approved these changes Apr 30, 2025

View reviewed changes

MasterKale reviewed Apr 30, 2025

View reviewed changes

nsatragno requested changes Apr 30, 2025

View reviewed changes

nadalin added this to the L3 Candidate Recommendation milestone May 7, 2025

MasterKale reviewed May 7, 2025

View reviewed changes

selfissued approved these changes May 21, 2025

View reviewed changes

emlun added 2 commits May 28, 2025 16:42

Merge branch 'main' into issue-1643-drop-in-field-meta

5d2e401

Clarify who should use resource-wide default language/direction metadata

9718f03

		1. If <code>\|pkOptions\|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code> is present
		and is not a [=well-formed language tag=], throw a "{{SyntaxError}}" {{DOMException}}.

	This property may not be defined.
	Note that this property might not be present.

	<td>\|userHandle\|</td>
	<td>
	The [=public key credential source/userHandle=] associated to the credential encoded using
	[=Base64url Encoding=]. This property may not be defined.

	<td>\|largeBlob\|</td>
	<td>
	The [=large, per-credential blob=] associated to the [=public key credential source=], encoded using [=Base64url Encoding=].
	This property may not be defined.

		@@ -1767,6 +1771,9 @@ When this method is invoked, the user agent MUST execute the following algorithm

		1. If the length of <code>\|pkOptions\|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/id}}</code> is not between 1 and 64 bytes (inclusive) then throw a {{TypeError}}.

		1. If <code>\|pkOptions\|.{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/language}}</code> is present

Replace in-field string metadata with resource-level default fields #2280

Are you sure you want to change the base?

Replace in-field string metadata with resource-level default fields #2280

Uh oh!

Conversation

emlun commented Apr 9, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aphillips left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aphillips left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emlun commented Apr 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nadalin commented Apr 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MasterKale left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

selfissued left a comment

Choose a reason for hiding this comment

Uh oh!

MasterKale commented May 28, 2025

Uh oh!

dwaite commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

emlun commented Apr 9, 2025 •

edited by pr-preview bot

Loading

MasterKale left a comment •

edited

Loading

dwaite commented May 28, 2025 •

edited

Loading