From e0f36962a90da65edff46032bf590dbd5956627b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= <marcosc@apple.com>
Date: Tue, 16 Jul 2024 17:14:46 +1000
Subject: [PATCH] Introduce DiscoverFromExternalSource activation + visibility
 requirements (#129)

---
 explainer.md | 45 +++++++++++++++++++++++++++------------------
 index.html   | 34 +++++++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/explainer.md b/explainer.md
index c67d247..b2d6a4f 100644
--- a/explainer.md
+++ b/explainer.md
@@ -34,26 +34,35 @@ At its core, the API is designed for a website ("verifier") to [transparently](h
 
 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="requestLicense()">Request Driver's license<button>
+```
+
+
 ```javascript
-    const digitalCredential = await navigator.identity.get({
-      digital: {
-        providers: [{
-          // Protocol extensibility:
-          protocol: "oid4vp",
-          // An example of an OpenID4VP request to wallets.
-          // Based on https://github.com/openid/OpenID4VP/issues/125
-          request: {
-            nonce: "n-0S6_WzA2Mj",
-            presentation_definition: {
-              // Presentation Exchange request, omitted for brevity
-            }
-          }
-        }],
-      },
-    });
-    // To be decrypted on the server...
-    const encryptedData = digitalCredential.data;
+async function requestLicense() {
+  const oid4pv = {
+    // Protocol extensibility:
+    protocol: "oid4vp", // An example of an OpenID4VP request to wallets. // Based on https://github.com/openid/OpenID4VP/issues/125
+    request: {
+      nonce: "n-0S6_WzA2Mj",
+      presentation_definition: {
+        // Presentation Exchange request, omitted for brevity
+      },
+    },
+  };
+  const digitalCredential = await navigator.identity.get({
+    digital: {
+      providers: [oid4pv],
+    },
+  });
+  // To be decrypted on the server...
+  const encryptedData = digitalCredential.data;
+}
 ```
+
 You can read a more detailed and technical description of the API in the [specification draft](https://wicg.github.io/digital-identities/).
 
 ### Using the API from another origin
diff --git a/index.html b/index.html
index a35a62a..97ec158 100644
--- a/index.html
+++ b/index.html
@@ -241,7 +241,7 @@ <h2>
       {{DigitalCredential}} instances are [=Credential/origin bound=].
     </p>
     <h3>
-      Extensions to Credential Management API
+      Integration with Credential Management API
     </h3>
     <aside class="issue" data-number="65"></aside>
     <h3>
@@ -272,6 +272,38 @@ <h3>
       The <dfn data-dfn-for="DigitalCredential">data</dfn> member is the
       credential's response data.
     </p>
+    <h3>
+      [[\DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)
+      internal method
+    </h3>
+    <p>
+      When invoked, the <dfn class="export" data-dfn-for=
+      "DigitalCredential">[[\DiscoverFromExternalSource]](origin, options,
+      sameOriginWithAncestors)</dfn> internal method MUST:
+    </p>
+    <ol class="algorithm">
+      <li>Let |global| be [=this=]'s [=relevant global object=].
+      </li>
+      <li>Let |document| be |global|'s [=associated `Document`=].
+      </li>
+      <li>If |document| is not a [=Document/fully active descendant of a
+      top-level traversable with user attention=], [=exception/throw=]
+      {{"NotAllowedError"}} {{DOMException}}.
+      </li>
+      <li>If |window| does not have [=transient activation=],
+      [=exception/throw=] {{"NotAllowedError"}} {{DOMException}}.
+      </li>
+      <li>[=Consume user activation=] of |window|.
+      </li>
+      <li>
+        <aside class="issue">
+          Details of how to actually get the [=digital credential=] are
+          forthcoming.
+        </aside>
+      </li>
+      <li>Return a {{DigitalCredential}}.
+      </li>
+    </ol>
     <h3>
       [[\Store]](credential, sameOriginWithAncestors) internal method
     </h3>