Merge branch 'main' into corrdinator

marcoscaceres · web-flow · commit 3ab67752e3c4 · 2025-07-07T14:47:27.000+10:00
diff --git a/README.md b/README.md
@@ -14,11 +14,7 @@ This project covers the requesting mechanisms for digital credentials, including
 
 ## Trying out the API
 
-**🚧 Note: The API is still extremely unstable and undergoing a lot of changes (almost daily!). 🚧**
-
-However, if you want to try it out:
-
-- [Try out the API in Chrome](https://digitalcredentials.dev/docs/requirements/)
+[Try out the API in Chrome](https://digitalcredentials.dev/docs/requirements/)
 
 ## Contributing
 
diff --git a/explainer.md b/explainer.md
@@ -32,64 +32,7 @@ To balance this tension we propose an API with the following key properties:
 
 At its core, the API is designed for a website ("verifier") to [transparently](https://github.com/w3cping/credential-considerations/blob/main/credentials-considerations.md#in-context-explanations) request the [selective disclosure](https://github.com/w3cping/credential-considerations/blob/main/credentials-considerations.md#selective-disclosure) of attributes from (issued) digital credentials that were provisioned - ahead of time - to wallets ("holders"), in a manner that is seamlessly compatible with existing architectural choices (such as [OpenID4VP integration](https://github.com/openid/OpenID4VP/issues/125)).
 
-Here is an example of how the  the API might be used in practice:
-
-The API needs to be initiated through a user gesture, such as a button click:
-
-```html
-<button onclick="requestCredential()">Request Driver's license<button>
-```
-
-
-```javascript
-async function requestCredential() {
-
-  // Check for Digital Credentials API support
-  if (typeof window.DigitalCredential !== 'undefined') {
-    
-    try {
-      
-      // These parameters are typically fetched from the backend.
-      // Statically defined here for protocol extensibility illustration purposes.
-      const oid4vp = {
-        protocol: "oid4vp", // An example of an OpenID4VP request to wallets. // Based on https://github.com/openid/OpenID4VP/issues/125
-        data: {
-          nonce: "n-0S6_WzA2Mj",
-          presentation_definition: {
-          //Presentation Exchange request, omitted for brevity
-          },
-        },
-      };
-
-      // create an Abort Controller
-      const controller = new AbortController();
-
-      // Call the Digital Credentials API using the presentation request from the backend
-      let dcResponse = await navigator.credentials.get({
-        signal: controller.signal,
-        mediation: "required",
-        digital: {
-          requests: [ oid4vp ]
-        }
-      });
-
-      // Send the encrypted response to the backend for decryption and verification
-      // Ommitted for brevity
-
-    } catch (error) {
-      console.error('Error:', error);
-    }
-  } else {
-    
-    // fallback scenario, illustrative only
-    alert("The Digital Credentials API is not supported in this browser.")
-  }
-};
-```
-
-> Example from: https://digitalcredentials.dev/docs/verifier-site/requesting-cred
-
-You can read a more detailed and technical description of the API in the [specification draft](https://w3c-fedid.github.io/digital-credentials/).
+For an [example of how to use the API](https://w3c-fedid.github.io/digital-credentials/#example-requesting-a-digital-credential) and a more detailed technical description, please refer to the [specification draft](https://www.w3.org/TR/digital-credentials/).
 
 ### Using the API from another origin
 
diff --git a/horizontal-reviews/security-privacy.md b/horizontal-reviews/security-privacy.md
@@ -3,16 +3,16 @@
 > 01.  What information does this feature expose,
 >      and for what purposes?
 
-High-value privacy sensitive claims from digital credentials, such as digital driver's licenses for both unique identification (such as for access to government services) and selective disclosure (such as for age verification). It does this through a one-time user-mediated communication channel from websites, to digital wallet applications, and back to websites. It is designed to be a better option than established lower-level communication channels like custom schemes, QR codes, and server-to-server network communication. How exactly this channel is used is up to the wallet applications and host operating system.
+Potentially high-value, privacy-sensitive claims from digital credentials, such as both unique identification (such as for access to government services) and selective disclosures (such as for age verification) from digital driver's licenses. These requests are made from websites, to digital wallet applications, and back to websites, through user-mediated, one-time communication channels. These are designed to be better options than established lower-level communication channels like custom schemes, QR codes, and server-to-server network communications. A website can decide which information to request. A request can be inspected by the user agent, and the specification recommends that the information being requested be disclosed to the user in the permission prompt. The wallet application decides which information is actually shared, based upon the request.
 
 > 02.  Do features in your specification expose the minimum amount of information
 >      necessary to implement the intended functionality?
 
 A primary use case of the digital credentials API is to enable users to selectively disclose only the minimum required information, such as a cryptographic attestation that the user holds a California driver’s license for an adult. The use of selective disclosure, however, is a decision for the verifier website based on the use case. There are legitimate scenarios, such as creating or recovering an account on a government website, where uniquely identifiable and potentially non-resettable personally identifiable information (PII) might be exposed.
 
-The API is designed to expect the use of response encryption so that this PII is exposed only to the requesting server and not any code running in the web page or browser. It is an [open question](https://github.com/WICG/digital-identities/issues/109) whether this response encryption is something we can reasonably enforce at this layer or not.
+The API is designed to expect the use of response encryption so that this PII is exposed only to the requesting server, such that exposure to code running in the web page or browser can be minimized or even avoided. It is an [open question](https://github.com/WICG/digital-identities/issues/109) whether this response encryption is something we can reasonably enforce at this layer.
 
-The API is also designed to require request transparency to enable user agents and operating systems to appropriately inform users about the level of privacy risk involved in the request. A major area of outstanding work is to outline in the specification our privacy and security guidance to implementers, but we already know that the [Chromium implementation](https://docs.google.com/document/d/1L68tmNXCQXucsCV8eS8CBd_F9FZ6TNwKNOaFkA8RfwI/edit) intends to show users stronger warnings in riskier scenarios such as those that lack the use of selective disclosure.
+The API is also designed to require request transparency to enable user agents and operating systems to appropriately inform users about the level of privacy risk involved in the request. The specification has a set of recommendations ([1](https://www.w3.org/TR/digital-credentials/latest/#user-permission-and-transparency), [2](https://www.w3.org/TR/digital-credentials/latest/#mitigating-unnecessary-requests-for-government-credentials), [3](https://www.w3.org/TR/digital-credentials/latest/#mitigating-unnecessary-requests-for-non-government-credentials)) for implementers, describing how to appropriately inform users about the credentials being exchanged. For example, the [Chromium implementation](https://docs.google.com/document/d/1L68tmNXCQXucsCV8eS8CBd_F9FZ6TNwKNOaFkA8RfwI/edit) intends to show users stronger warnings in riskier scenarios such as those that do not support selective disclosure.
 
 > 03.  Do the features in your specification expose personal information,
 >      personally-identifiable information (PII), or information derived from
@@ -40,7 +40,7 @@ Further, this specification aims to be an improvement over the existing communic
 > 05.  Do the features in your specification introduce state
 >      that persists across browsing sessions?
 
-No. In particular, the current scope is just about credential presentation (read-only). We have had requests to expand scope to consider credential issuance APIs but no work has begun on that.
+Yes. The specification includes [a facility](https://w3c-fedid.github.io/digital-credentials/#create-origin-options-sameoriginwithancestors-internal-method) for issuing new credentials into wallets with user permission.
 
 > 06.  Do the features in your specification expose information about the
 >      underlying platform to origins?
@@ -63,7 +63,7 @@ No.
 
 > 10.  Do features in this specification allow an origin to access other devices?
 
-Not yet, but we expect to expand the API to enable cross-device presentation flows using the same mechanism used by passkeys ([FIDO CTAP](https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html)).
+Potentially, yes. While not a property of the DC API itself, the API is designed to support cross-device presentation flows such as by using the [FIDO CTAP](https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html) used by passkeys.
 
 > 11.  Do features in this specification allow an origin some measure of control over
 >      a user agent's native UI?
@@ -78,7 +78,7 @@ None directly. Wallets may expose temporary identifiers, such as in the MSOs use
 > 13.  How does this specification distinguish between behavior in first-party and
 >      third-party contexts?
 
-The API is currently available only in first-party contexts, but there is an [open issue](https://github.com/WICG/digital-identities/issues/78) to explore adding a permission policy to enable requests in third-party contexts.
+The specification uses a Permissions Policy with the "self" default allow list, meaning the API cannot be used in third-party contexts unless allowed by the (recursive) parent context(s).
 
 > 14.  How do the features in this specification work in the context of a browser’s
 >      Private Browsing or Incognito mode?
@@ -88,7 +88,9 @@ Like other browser authentication (e.g., WebAuthn) and identification (e.g., aut
 > 15.  Does this specification have both "Security Considerations" and "Privacy
 >      Considerations" sections?
 
-Not yet, but it will. The specification is still being written as we incubate the API and gain experience with real-world experiments.
+The specification has [extensive Privacy considerations](https://w3c-fedid.github.io/digital-credentials/#privacy-considerations), most of which are still evolving as the group works through the many Privacy-related challenges of the digital credentials space.
+
+There are [some early outlines for the Security Considerations](https://w3c-fedid.github.io/digital-credentials/#security-considerations), and there is active work in progress to write those up in more detail.
 
 > 16.  Do features in your specification enable origins to downgrade default
 >      security protections?
@@ -99,13 +101,13 @@ No
 >      (instead of getting destroyed) after navigation, and potentially gets reused
 >      on future navigations back to the document?
 
-Implementations should fail or postpone any requests which occur while the page is not visible to the user. The spec may introduce a [requirement for user activation](https://github.com/WICG/digital-identities/issues/91) which could help with this.
+Implementations should fail or postpone any requests which are made while the page is not visible to the user. The spec [requires](https://www.w3.org/TR/digital-credentials/latest/#discoverfromexternalsource-origin-options-sameoriginwithancestors-internal-method) both user attention on a fully active document and user activation to use the API.
 
 > 18.  What happens when a document that uses your feature gets disconnected?
 
-Probably just silently ignored, but [we'll discuss](https://github.com/WICG/digital-identities/issues/112).
+See above. The spec has "fully active" checks in its algorithms.
 
 > 19.  What should this questionnaire have asked?
 
-What are the security and privacy implications of not shipping this feature? How does this feature fit into the larger privacy risk landscape. We believe the feature will lead to a reduced risk relative to the status quo, but this is very subjective and hard to demonstrate definitively.
+What are the security and privacy implications of not shipping this feature? How does this feature fit into the larger privacy risk landscape? We believe this feature will offer reduced risks, relative to large-scale adoption of alternative technologies.
 
diff --git a/index.html b/index.html
@@ -552,7 +552,7 @@ <h3>
     </h3>
     <pre class="idl">
     dictionary DigitalCredentialRequestOptions {
-      sequence&lt;DigitalCredentialGetRequest&gt; requests;
+      required sequence&lt;DigitalCredentialGetRequest&gt; requests;
     };
     </pre>
     <h4>
@@ -689,6 +689,7 @@ <h3>
     <pre class="idl">
     [Exposed=Window, SecureContext]
     interface DigitalCredential : Credential {
+      [Default] object toJSON();
       readonly attribute DOMString protocol;
       [SameObject] readonly attribute object data;
       static boolean userAgentAllowsProtocol(DOMString protocol);
@@ -784,6 +785,14 @@ <h3>
       </li>
       <li>If |requests| is empty, [=exception/throw=] a {{TypeError}}.
       </li>
+      <li>[=List/For each=] |request| of |requests|:
+        <ol>
+          <li>[=serialize a JavaScript value to a JSON string|Serialize=]
+          |request| to a JSON string. [=exception/throw|Re-throw=] any
+          [=exception=].
+          </li>
+        </ol>
+      </li>
       <li>
         <aside class="issue">
           Details of how to actually get the [=digital credential=] are
@@ -833,6 +842,14 @@ <h3>
       </li>
       <li>If |requests| is empty, [=exception/throw=] a {{TypeError}}.
       </li>
+      <li>[=List/For each=] |request| of |requests|:
+        <ol>
+          <li>[=serialize a JavaScript value to a JSON string|Serialize=]
+          |request| to a JSON string. [=exception/throw|Re-throw=] any
+          [=exception=].
+          </li>
+        </ol>
+      </li>
       <li>
         <aside class="issue">
           Details of how to actually issue the [=digital credential=] are
