Add the IDP sign-in status API to the spec

spec/index.bs

@@ -301,6 +301,76 @@ value (which is used when a resource loaded as a third-party, not first-party).
 for an [=IDP=] to adopt the FedCM API without introducing security issues on the API, since the
 [=RP=] cannot inspect the results from the fetches in any way.
 
+<!-- ============================================================ -->
+## IDP Sign-in Status ## {#browser-api-idp-sign-in-status}
+<!-- ============================================================ -->
+
+Each [=user agent=] keeps a global, persistent <dfn>IDP Sign-in Status
+map</dfn>, an initially empty [=map=]. The [=map/keys=] in this map are
+[=/origin=] (of IDPs), and the [=map/values=] are enums that can be one of
+"<dfn><code>unknown</code></dfn>", "<dfn><code>signed-in</code></dfn>",
+and "<dfn><code>signed-out</code></dfn>"
+
+The user agent checks all page and subresource loads for an HTTP response
+[[RFC9110#header.fields|header]] named
+<dfn><code>IdP-SignIn-Status</code></dfn>, whose value is parsed at HTTP
+[[RFC9110#parameter|Parameter]]s.
+If that header exists and the first parameter has a name of `action`,
+the user agent must process it as follows:
+
+* If this is a subresource request, and the response does not have the
+    same [=/origin] as the toplevel page, ignore the header.
+* Otherwise:
+    * If the parameter value is `signin`, [=map/set=] an entry in the
+        [=IDP Sign-in Status map=] with the key being the origin of the resource
+        and the value being [=signed-in=]
+    * If the parameter value is `signout-all`, [=map/set=] an entry in the
+        [=IDP Sign-in Status map=] with the key being the origin of the resource
+        and the value being [=signed-out=]
+
+Issue: Should the header checking be integrated into the fetch spec instead,
+    since it affects all resources?
+
+User agents must also clear the [=IDP Sign-in Status map=] data when:
+    :   the user clears all cookies or site settings data
+    ::  The user agent must clear the entire map
+    :   the user clears cookies or site data for a specific origin
+    ::  The user agent must remote all entries that would be affected
+            by the deleted cookies.
+
+            Note: For example, domain cookies may affect subdomains of
+                the deleted origin.
+    :   if the user agent allows deleting individual cookies
+    ::  the behavior is user agent-defined.
+
+            Note: The user agent may want to reset the state to undefined,
+                since is impossible to know whether this cookie affects
+                authorization state.
+
+Note: Website-initiated cookie changes should not affect this map. When
+    IDP sign-in state changes, it should send an explicit
+    [=IDP-SignIn-Status=].
+    RP state should not affect this map since it only reflects IDP state.
+
+IDPs can also use a JavaScript API to update the stored sign-in status:
+
+<pre class="idl">
+  [Exposed=Window, SecureContext]
+  interface IdentityProvider {
+    static undefined recordSignIn();
+    static undefined recordSignOut();
+  };
+</pre>
+
+Issue: Should the functions return Promise<undefined>, so the caller can know
+    when the call is finished?
+
+When {{IdentityProvider/recordSignIn}} or {{IdentityProvider/recordSignOut}} is
+called, the user agent [=map/set|sets=] the entry in the [=IDP Sign-in Status
+Map=] with the [=map/key=] being  [=/this=]'s [=/relevant settings object=]'s
+[=environment settings object/origin=] and the value being [=signed-in=] (for
+`recordSignIn`) or [=signed-out=] (for `recordSignOut`).
+
 <!-- ============================================================ -->
 ## The State Machine ## {#browser-api-state-machine}
 <!-- ============================================================ -->
@@ -490,11 +560,44 @@ To <dfn>create an IdentityCredential</dfn> given an {{IdentityProviderConfig}}
 |provider| and a |globalObject|, run the following steps. This returns an {{IdentityCredential}} or
 failure.
     1. Assert: These steps are running [=in parallel=].
+    1. Let |signinStatus| be the value of the entry in [=IDP Sign-in Status map=]
+        with the key being the origin of |provider|'s configURL. If there is
+        no such entry, set it to a user-agent specific default (either [=unknown=] or
+        [=signed-out=]).
+    1. If |signinStatus| is [=signed-out=], return failure.
+        Issue: Should the user agent instead show UI to let the user sign
+            in to the IDP? This could be especially useful in the multi-IDP
+            case.
     1. Let |config| be the result of running [=fetch the config file=] with |provider| and
         |globalObject|.
     1. If |config| is failure, return failure.
     1. Let |accountsList| be the result of [=fetch the accounts list=] with |config|, |provider|,
         and |globalObject|.
+    1. If the fetch failed, or the size of |accountsList| is 0:
+        1. [=map/set|Set=] an entry in the [=IDP Sign-in Status map=] with the
+            key being the origin of the configURL and the value being [=signed-out=].
+            A user agent may decide to skip this step if no credentials were sent to
+            server.
+
+            Note: For example, if the fetch failed due to a DNS error, no
+                credentials were sent. In this situation, we do not know whether
+                the user is signed in or not and so we may not want to reset
+                the status.
+        1. If |signinStatus| is [=signed-in=], show a dialog to the user and return
+            failure.
+
+            Note: Since this situation happens when the browser expects the user
+                to be signed in, but the accounts fetch indicated that the user
+                is signed out, it is recommended that this dialog provides a
+                "sign in" button allowing the user to sign in to the IDP using
+                {{IdentityProviderAPIConfig/signin_url}}.
+
+            Note: This dialog ensures that silent tracking of the user is
+                impossible by always showing UI of some kind when credentials
+                were sent to the server.
+    1. If |signinStatus| is [=unknown=], [=map/set=] an entry in the [=IDP
+        sign-in status map=] with the key being the origin of the configURL and
+        the value being [=signed-in=].
     1. For each |account| in |accountsList|:
         1. If |account|["{{IdentityProviderAccount/picture}}"] is present,
             [=fetch the account picture=] with |account| and |globalObject|.
@@ -675,6 +778,7 @@ dictionary IdentityProviderAPIConfig {
   required USVString accounts_endpoint;
   required USVString client_metadata_endpoint;
   required USVString id_assertion_endpoint;
+  USVString signin_url;
   IdentityProviderBranding branding;
 };
 </xmp>