session payments: add token rotation flow (#23)

Author: asurkov

section/session-flow.html

@@ -266,18 +266,31 @@ <h3>Payment streaming</h3>
         <li>Let |result:OutgoingPaymentResult| be the result of [=send a create outgoing payment request=]
           with |userWallet|'s {{UserWallet/walletAddressDetails}}, |session|'s {{Session/incomingPaymentId}},
           |amountValue|, and |userWalletGrant|.</li>
+        <li>If |result| is {{OutgoingPaymentResult/"token-invalid"}}:
+          <ol>
+            <li>Let |rotatedAccessToken:AccessToken| be the result of [=send a rotate access token request=]
+              with |userWalletGrant|.</li>
+            <li>If |rotatedAccessToken| is failure:
+              <ol>
+                <li>[=Revoke user wallet credentials=].</li>
+                <li>Return.</li>
+              </ol>
+            </li>
+            <li>Set |userWalletGrant|'s {{Grant/access_token}} to |rotatedAccessToken|.</li>
+            <li>Run [=update grant access token=] with |rotatedAccessToken|.</li>
+            <li>Set |result| to the result of [=send a create outgoing payment request=]
+              with |userWallet|'s {{UserWallet/walletAddressDetails}}, |session|'s {{Session/incomingPaymentId}},
+              |amountValue|, and |userWalletGrant|.</li>
+          </ol>
+        </li>
         <li>If |result| is {{OutgoingPaymentResult/"success"}}:
           <ol>
             <li>[=Fire monetization event=] given |session|, |amount|, and |userWallet|.</li>
             <li>[=Schedule payment streaming tick=].</li>
             <li>Return.</li>
           </ol>
         </li>
-        <li>Otherwise:
-          <ol>
-            <li>TODO: Handle token rotation and other failure cases.</li>
-          </ol>
-        </li>
+        <li>[=Revoke user wallet credentials=].</li>
       </ol>
     </div>
 
@@ -321,5 +334,29 @@ <h3>Payment streaming</h3>
       </ol>
       <p class="note">For example, <code>convert scaled amount to decimal(100, 2)</code> returns <code>"1.00"</code>.</p>
     </div>
+
+    <div class="algorithm">
+      <p>To <dfn>revoke user wallet credentials</dfn>, run these steps:</p>
+      <ol>
+        <li>Run [=update grant access token=] with the empty string.</li>
+        <li>For each |session| in the [=active sessions list=]:
+          <ol>
+            <li>Remove |session| from the [=active sessions list=].</li>
+          </ol>
+        </li>
+        <li>Set the [=current session iterator=] to the [=end iterator=].</li>
+      </ol>
+      <aside class="note">
+        <p>
+          Revoking credentials clears the access token but preserves other user wallet information
+          (wallet address, auth keys). This allows the user interface to display a "Reconnect" prompt
+          rather than requiring the user to set up their wallet again from scratch.
+        </p>
+        <p>
+          All active monetization sessions are terminated since payments can no longer be made.
+        </p>
+      </aside>
+    </div>
+
   </section>
 </section>

section/storage.html

@@ -90,6 +90,20 @@ <h3>Storage operations</h3>
             </ol>
         </div>
 
+        <div class="algorithm">
+            <p>To <dfn>update grant access token</dfn>, given |accessToken:DOMString|:</p>
+            <ol>
+                <li>Let |storage| be the result of [=get storage=].</li>
+                <li>If |storage|'s {{Storage/grant}} is null, return.</li>
+                <li>Set |storage|'s {{Storage/grant}}'s {{Grant/access_token}} to |accessToken|.</li>
+                <li>[=Persist storage=] with |storage|.</li>
+            </ol>
+            <p class="note">This algorithm updates only the access token within an existing grant,
+              preserving other grant properties. Used during token rotation when the authorization
+              server issues a new access token. When |accessToken| is the empty string, the grant is
+              invalidated but wallet information is preserved for reconnection.</p>
+        </div>
+
         <div class="algorithm">
             <p>To <dfn>store auth keys</dfn>, given |authKeys:AuthKeys|:</p>
             <ol>