Skip to content

Commit bea5b28

Browse files
asurkovasurkov
committed
session-flow: add session initation/termination sections
1 parent 9b804da commit bea5b28

File tree

5 files changed

+296
-45
lines changed

5 files changed

+296
-45
lines changed

‎index.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@
103103
<div data-include="section/storage.html" data-include-replace="true"></div>
104104
<div data-include="section/authentication.html" data-include-replace="true"></div>
105105
<div data-include="section/wallet-setup.html" data-include-replace="true"></div>
106+
<div data-include="section/status.html" data-include-replace="true"></div>
106107
<div data-include="section/session-flow.html" data-include-replace="true"></div>
107108
<div data-include="section/algorithms.html" data-include-replace="true"></div>
108109
<div data-include="section/dictionaries.html" data-include-replace="true"></div>

‎section/dictionaries.html‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,4 +292,34 @@ <h4>Enums</h4>
292292
};
293293
</pre>
294294
</section>
295+
296+
<section>
297+
<h3>Session Dictionaries</h3>
298+
<p>These dictionaries define internal session records used by the user agent to track active monetization sessions.</p>
299+
300+
<section data-dfn-for="Session">
301+
<h4>The `Session` dictionary</h4>
302+
<p>
303+
The {{Session}} dictionary represents an active monetization session. This is an internal user agent
304+
structure maintained in the [=active sessions list=] and is not exposed to JavaScript.
305+
</p>
306+
<pre class="idl">
307+
dictionary Session {
308+
required HTMLLinkElement linkElement;
309+
required WalletAddressDetails walletDetails;
310+
required DOMString incomingPaymentId;
311+
};
312+
</pre>
313+
<dl>
314+
<dt><dfn>`linkElement`</dfn></dt>
315+
<dd>The {{HTMLLinkElement}} with <code>rel="monetization"</code> that initiated this session.</dd>
316+
317+
<dt><dfn>`walletDetails`</dfn></dt>
318+
<dd>The {{WalletAddressDetails}} obtained from the wallet address discovery request.</dd>
319+
320+
<dt><dfn>`incomingPaymentId`</dfn></dt>
321+
<dd>The incoming payment identifier (payment bucket URI) created for receiving funds during this session.</dd>
322+
</dl>
323+
</section>
324+
</section>
295325
</section>

‎section/session-flow.html‎

Lines changed: 204 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,214 @@
11
<section id="session-flow">
2-
<h2>Session Flow</h2>
2+
<h2>Session flow</h2>
3+
34
<p>
45
This section describes the payment session flow that occurs when a user visits a [=web monetized website=].
56
The session flow involves establishing a payment session, managing ongoing payments, and handling session lifecycle events.
67
</p>
78

8-
<h3>Session Flow Overview</h3>
9-
<p>
10-
When a user navigates to a web monetized website, the browser initiates a payment session flow that includes:
11-
</p>
12-
<ul>
13-
<li>Discovery of payment endpoints.</li>
14-
<li>Session establishment.</li>
15-
<li>Payment streaming.</li>
16-
<li>Session management and cleanup.</li>
17-
</ul>
18-
19-
<h3>Session Initiation</h3>
20-
<p>
21-
The payment session begins when the browser detects a monetization link element on a webpage.
22-
The browser must validate the [=wallet address=] and establish a connection with the configured wallet.
23-
</p>
9+
<section>
10+
<h3>Session lifecycle</h3>
11+
<p>
12+
This section defines when sessions are created and ended. It specifies the triggers that invoke the
13+
[[[#session-initiation]]] and [[[#session-termination]]] algorithms defined later in this section.
14+
</p>
2415

25-
<p>To initiate a payment session, given a <var>walletAddress</var>:</p>
26-
<ol>
27-
<li>Validate the [=wallet address=] format.</li>
28-
<li>Check if a wallet is configured and available.</li>
29-
<li>Establish a payment session with the wallet.</li>
30-
<li>Begin payment streaming to the [=wallet address=].</li>
31-
</ol>
16+
<p>
17+
When a {{Document}} becomes [=Document/fully active=], the user agent MUST
18+
[=initiate document-wide sessions=].
19+
If a {{Document}} becomes not [=Document/fully active=], the user agent MUST
20+
[=end sessions for document=] for it and all of its [=child navigables=].
21+
</p>
3222

33-
<h3>Payment Streaming</h3>
34-
<p>
35-
Once a session is established, the browser manages the ongoing payment stream according to the configured budget and rate limits.
36-
</p>
23+
<p>
24+
When the user starts interacting with a [=media element=], the user agent SHOULD
25+
[=initiate media-scoped sessions=] given that element; when the user stops interacting, the user agent
26+
SHOULD [=end sessions scoped to=] that element.
27+
</p>
3728

38-
<h3>Session Lifecycle Management</h3>
39-
<p>
40-
The browser must handle various session lifecycle events including:
41-
</p>
42-
<ul>
43-
<li>Session pause and resume.</li>
44-
<li>Tab focus changes.</li>
45-
<li>Page navigation.</li>
46-
<li>Wallet disconnection.</li>
47-
<li>Budget exhaustion.</li>
48-
</ul>
49-
50-
<h3>Error Handling</h3>
51-
<p>
52-
The session flow must gracefully handle various error conditions and provide appropriate feedback to both the website and the user.
53-
</p>
29+
<p>
30+
If any of the conditions defined in the
31+
<a href="https://webmonetization.org/specification/#link-type-monetization">link fetch and processing timing</a>
32+
cause a monetization link element to be reprocessed, the user agent MUST [=end session=] for the session
33+
associated with that element (if any) and then [=initiate a session=] for that element.
34+
</p>
35+
36+
<p>
37+
The user agent maintains an [=active sessions list=] to track all currently running monetization sessions.
38+
Each session in this list corresponds to a monetization link element and contains the information needed
39+
to distribute payments to the website's wallet.
40+
</p>
41+
42+
<dl>
43+
<dt><dfn>active sessions list</dfn></dt>
44+
<dd>
45+
A user agent maintained ordered list of {{Session}} records created by [=initiate a session=].
46+
</dd>
47+
</dl>
48+
</section>
49+
50+
<section>
51+
<h3>Session initiation</h3>
52+
<p>
53+
This section defines the algorithms for initiating payment sessions at various scopes—document-wide,
54+
media-scoped, or for individual monetization link elements. Session initiation discovers website wallet details,
55+
negotiates authorization, creates an incoming payment, and registers a session record in the [=active sessions list=].
56+
</p>
57+
58+
<div class="algorithm">
59+
<p>To <dfn>initiate document-wide sessions</dfn> given a |document:Document|, run these steps:</p>
60+
<ol>
61+
<li>If the result of [=get user wallet=] is null, then return.</li>
62+
<li>[=initiate sessions scoped to=] the [^head^] element of |document|.</li>
63+
<li>For each [=child navigable=] of |document|, recursively [=initiate document-wide sessions=].</li>
64+
</ol>
65+
</div>
66+
67+
<div class="algorithm">
68+
<p>To <dfn>initiate media-scoped sessions</dfn> given a |media:HTMLElement|, run these steps:</p>
69+
<ol>
70+
<li>If the result of [=get user wallet=] is null, then return.</li>
71+
<li>[=initiate sessions scoped to=] |media|.</li>
72+
</ol>
73+
</div>
74+
75+
<div class="algorithm">
76+
<p>To <dfn>initiate sessions scoped to</dfn> the |root:HTMLElement|, run these steps:</p>
77+
<ol>
78+
<li>Let |document:Document| be the {{Node/ownerDocument}} of |root|.</li>
79+
<li>If [=document monetization disabled=] given |document|, then return.</li>
80+
<li>Let |linkElements:NodeList| be all [^link^] elements with `rel="monetization"` that are descendants of |root|.</li>
81+
<li>For each |linkElement:HTMLLinkElement| in |linkElements|, [=initiate a session=] given |linkElement|.</li>
82+
</ol>
83+
</div>
84+
85+
<div class="algorithm">
86+
<p>To <dfn>initiate a session</dfn>, given |linkElement:HTMLLinkElement|, perform the following steps:</p>
87+
<ol>
88+
<li>If |linkElement| has [^link/disabled^] attribute, then return.</li>
89+
<li>
90+
Let |websiteWalletAddress:DOMString| be the value of the {{HTMLLinkElement/href}} of |linkElement|.
91+
</li>
92+
<li>
93+
If [=wallet monetization restricted=] given |document| and |websiteWalletAddress|, then return.
94+
</li>
95+
<li>
96+
Let |websiteWalletDetails:WalletAddressDetails?| be the result of [=send a wallet address request=] with |websiteWalletAddress|.
97+
</li>
98+
<li>
99+
If |websiteWalletDetails| is null, fire an `error` event on |linkElement| and return.
100+
</li>
101+
<li>
102+
Fire a `load` event on |linkElement|.
103+
</li>
104+
<li>
105+
Let |incomingPaymentGrant:Grant?| be the result of [=send an incoming payment grant request=] with |websiteWalletDetails|.
106+
</li>
107+
<li>
108+
If |incomingPaymentGrant| is null, return.
109+
</li>
110+
<li>
111+
Let |incomingPaymentId:DOMString?| be the result of [=send a create incoming payment request=] with |websiteWalletDetails|, and |incomingPaymentGrant|.
112+
</li>
113+
<li>
114+
If |incomingPaymentId| is null, return.
115+
</li>
116+
<li>
117+
Let |continueUri:DOMString| be |incomingPaymentGrant|.{{Grant/continue}}.{{Continue/uri}}.
118+
</li>
119+
<li>
120+
Let |accessToken:DOMString| be |incomingPaymentGrant|.{{Grant/continue}}.{{Continue/access_token}}.{{ContinueAccessToken/value}}.
121+
</li>
122+
<li>
123+
[=Send a cancel grant request=] with |continueUri| and |accessToken|.
124+
<p class="note">The incoming payment grant is no longer needed after the payment bucket has been created. Canceling it ensures proper cleanup and revokes the authorization. Implementations should handle cancellation failures gracefully but can proceed with the session even if cancellation fails, as the grant will expire naturally.</p>
125+
</li>
126+
<li>
127+
Let |session:Session| be a new {{Session}} with:
128+
<ul>
129+
<li>{{Session/linkElement}} set to |linkElement|</li>
130+
<li>{{Session/walletDetails}} set to |websiteWalletDetails|</li>
131+
<li>{{Session/incomingPaymentId}} set to |incomingPaymentId|</li>
132+
</ul>
133+
</li>
134+
<li>
135+
Append |session| to the [=active sessions list=].
136+
</li>
137+
<li>
138+
If this is the first active session, [=start payment streaming loop=].
139+
</li>
140+
</ol>
141+
</div>
142+
143+
<aside class="note" title="Session initiation summary">
144+
<p>The main [=initiate a session=] algorithm performs these key steps:</p>
145+
<ol>
146+
<li><strong>Preconditions:</strong> Verify user wallet exists and monetization is permitted</li>
147+
<li><strong>Discovery:</strong> Request website wallet address details,
148+
firing `load` event on success or `error` event on failure</li>
149+
<li><strong>Authorization:</strong> Obtain an incoming payment grant to create payments on the website's wallet</li>
150+
<li><strong>Payment setup:</strong> Create an incoming payment (payment bucket) on the website's wallet resource server</li>
151+
<li><strong>Cleanup:</strong> Cancel the temporary incoming payment grant (no longer needed)</li>
152+
<li><strong>Registration:</strong> Add the session to the active sessions list and
153+
start the payment streaming loop if this is not yet started</li>
154+
</ol>
155+
</aside>
156+
</section>
157+
158+
<section>
159+
<h3>Session termination</h3>
160+
<p>
161+
This section defines the algorithms for ending payment sessions at various scopes—document-wide,
162+
media-scoped, or for individual monetization link elements. Session termination removes session records
163+
from the [=active sessions list=] and cancels scheduled payment work.
164+
</p>
165+
166+
<div class="algorithm">
167+
<p>To <dfn>end sessions for document</dfn>, given a |document:Document|, run these steps:</p>
168+
<ol>
169+
<li>[=End sessions scoped to=] the [^head^] element of |document|.</li>
170+
<li>For each [=child navigable=] of |document|, recursively [=end sessions for document=].</li>
171+
</ol>
172+
</div>
173+
174+
<div class="algorithm">
175+
<p>To <dfn>end sessions scoped to</dfn> the |root:HTMLElement|, run these steps:</p>
176+
<ol>
177+
<li>Let |linkElements:NodeList| be all [^link^] elements with `rel="monetization"` that are descendants of |root|.</li>
178+
<li>For each |linkElement:HTMLLinkElement| in |linkElements|:
179+
<ol>
180+
<li>Let |session:Session| be the session record in the [=active sessions list=] whose {{HTMLLinkElement}} is |linkElement|, or null if none exists.</li>
181+
<li>If |session| is not null, [=end session=] given |session|.</li>
182+
</ol>
183+
</li>
184+
</ol>
185+
</div>
186+
187+
<div class="algorithm">
188+
<p>To <dfn>end session</dfn>, given a session record |session:Session|, run these steps:</p>
189+
<ol>
190+
<li>Remove |session| from the [=active sessions list=].</li>
191+
<li>The user agent MUST cancel any scheduled payment work for |session|.</li>
192+
</ol>
193+
</div>
194+
</section>
195+
196+
<section>
197+
<h3>Payment streaming</h3>
198+
<p>
199+
Once a session is established, the browser manages the ongoing payment stream according to the configured budget and rate limits.
200+
</p>
201+
202+
<div class="algorithm">
203+
<p>To <dfn>start payment streaming loop</dfn>, run these steps:</p>
204+
<ol>
205+
<li>
206+
</li>
207+
</ol>
208+
</div>
209+
210+
<p>
211+
The session flow must gracefully handle various error conditions and provide appropriate feedback to both the website and the user.
212+
</p>
213+
</section>
54214
</section>

‎section/status.html‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<section id="monetization-status">
2+
<h2>Monetization status</h2>
3+
4+
<p>
5+
User agents SHOULD provide controls to disable Web Monetization completely and on a per-[=origin=]
6+
basis via a wallet management interface. User agents SHOULD provide a user interface that allows
7+
users to view and adjust these preferences.
8+
</p>
9+
10+
<p>
11+
A website can disable Web Monetization for itself and/or its subdocuments by setting
12+
the <a href="https://webmonetization.org/developers/permissions-policy-monetization/">`monetization`</a>
13+
[=policy-controlled feature=].
14+
</p>
15+
16+
<p>
17+
A website can also restrict Web Monetization to <a>wallet addresses</a> of certain [=origin=]s
18+
by using the <a href="https://webmonetization.org/developers/csp-monetization-src/">`monetization-src`</a>
19+
directive in the [=content security policy=].
20+
</p>
21+
22+
<section id="monetization-is-disabled">
23+
<h3>Document monetization restrictions</h3>
24+
25+
<p>
26+
<dfn data-lt="document monetization disabled">Document monetization disabled</dfn>
27+
given a |document:Document| if either of the following conditions apply:
28+
</p>
29+
30+
<ul>
31+
<li>
32+
The user preferences specify that Web Monetization is either completely disabled or disabled specifically
33+
for the [=Document/origin=] of the |document|.
34+
</li>
35+
<li>
36+
The |document| is not [=allowed to use=]
37+
the <a href="https://webmonetization.org/developers/permissions-policy-monetization/">`monetization`</a>
38+
[=policy-controlled feature=].
39+
</li>
40+
</ul>
41+
</section>
42+
43+
<section id="monetization-is-disabled-for-wallet">
44+
<h3>Wallet address restrictions</h3>
45+
46+
<p>
47+
<dfn data-lt="wallet monetization restricted">Wallet monetization restricted</dfn>
48+
given a |document:Document| and a [=wallet address=] |walletAddress:DOMString|
49+
if the <a href="https://webmonetization.org/developers/csp-monetization-src/">`monetization-src`</a> directive
50+
in the [=content security policy=] of the |document| restricts the |walletAddress|'s [=origin=].
51+
</p>
52+
</section>
53+
54+
<p class="note">
55+
These mechanisms provide multiple layers of control over Web Monetization: the user controls whether
56+
monetization is enabled in their browser, the website can control whether monetization is allowed
57+
via permissions policy, and the website can restrict which wallet addresses are allowed
58+
via content security policy. All three mechanisms work together to ensure monetization only occurs when all parties consent.
59+
</p>
60+
</section>

‎section/storage.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ <h3>Storage</h3>
6161
</section>
6262

6363
<section>
64-
<h3>Storage Operations</h3>
64+
<h3>Storage operations</h3>
6565

6666
<div class="algorithm">
6767
<p>To <dfn>get storage</dfn>:</p>

0 commit comments

Comments
 (0)