Deployed ffda836 with MkDocs version: 1.6.1

dev/rest-api/endpoints/index.html

@@ -4556,7 +4556,7 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
 <p class="admonition-title">Developer feature</p>
 <p>The <code>/api/session/*</code> endpoints power unshackle's <strong>remote download</strong> mode. A thin local client authenticates once against a remote server, then fetches titles, tracks, and segments, and proxies DRM licensing back through it. The server mounts these endpoints in <code>--remote-only</code> mode, and they are what the built-in <code>RemoteService</code> client drives. Most end users never call them directly.</p>
 </div>
-<p>The server holds remote sessions in memory. They expire after <code>serve.session_ttl</code> (default 300s), except while awaiting interactive authentication input, which uses a 600s window. A remote session binds to the IP that made it, so the server rejects a request from a different IP with <code>403 FORBIDDEN</code>.</p>
+<p>The server holds remote sessions in memory. They expire after <code>serve.session_ttl</code> (default 300s) without a request, except while awaiting interactive authentication input, which uses a 600s window. A remote session binds to the IP that made it, so the server rejects a request from a different IP with <code>403 FORBIDDEN</code>.</p>
 <h3 id="remote-session-lifecycle-overview">Remote session lifecycle overview<a class="headerlink" href="#remote-session-lifecycle-overview" title="Permanent link">&para;</a></h3>
 <div class="language-text highlight"><pre><span></span><code><span id="__span-28-1"><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a>POST /api/session/create        → returns session_id, status "authenticating"
 </span><span id="__span-28-2"><a id="__codelineno-28-2" name="__codelineno-28-2" href="#__codelineno-28-2"></a>GET  /api/session/{id}/prompt   → poll until authenticated (submit answers via POST)
@@ -4585,7 +4585,7 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
 </div>
 </div>
 </div>
-<p><code>server_account</code> is <code>true</code> when the server authenticated with one of its own accounts (<code>serve.server_accounts</code>). Otherwise the server uses only what the client sent, and never falls back to its own credentials. Only a client that sent its own cookies or credentials gets cookies, auth headers, and the remote session cache back. For any other remote session (a server account, or an anonymous login through the server's proxy) the tracks and segments responses carry no cookies and no auth headers. The server also drops secret-looking keys from track data, and the cache stays on the server. A server-account service also refuses a client proxy URI, because the server's login would pass through it.</p>
+<p><code>server_account</code> is <code>true</code> when the server authenticated with one of its own accounts (<code>serve.server_accounts</code>). Otherwise the server uses only what the client sent, and never falls back to its own credentials. Only a client that sent its own cookies, credentials, or cache files gets cookies, auth headers, and the remote session cache back. A client that answered a login prompt (a device code or an OTP) gets them too. This applies only when the login then succeeds and the remote session does not use a server account. For any other remote session (a server account, or an anonymous login through the server's proxy) the tracks and segments responses carry no cookies and no auth headers. The server also drops secret-looking keys from track data, and the cache stays on the server. A server-account service also refuses a client proxy URI, because the server's login would pass through it.</p>
 <table>
 <thead>
 <tr>
@@ -5043,7 +5043,7 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
 </div>
 </div>
 </div>
-<p>The <code>cache</code> field is present only if the remote session produced cache files. <code>404 SESSION_NOT_FOUND</code> if the remote session does not exist.</p>
+<p>The <code>cache</code> field is present only if the remote session produced cache files and the login belongs to the client. <code>404 SESSION_NOT_FOUND</code> if the remote session does not exist.</p>
 <hr />
 <h2 id="error-responses">Error responses<a class="headerlink" href="#error-responses" title="Permanent link">&para;</a></h2>
 <p>The server serialises every structured error raised inside a handler to the same JSON envelope:</p>

dev/rest-api/remote-sessions/index.html

@@ -2554,10 +2554,16 @@ and return the content keys directly. See
 <a href="#server-side-vs-proxied-cdm">Server-side vs. proxied CDM</a> below.</p>
 </div>
 <div class="tabbed-block">
-<p>The client downloads, decrypts, and muxes locally. On completion it deletes
-the remote session. If the server has updated cache files (for example a refreshed
-token), the delete returns them and the client saves them locally, so the <strong>next</strong>
-remote session can skip interactive auth.</p>
+<p>The client downloads, decrypts, and muxes locally. While it works, it sends a
+keep-alive request to the remote session at an interval of one third of
+<code>session_ttl</code>, so a long download does not let the remote session expire. On
+completion, and also when <code>dl</code> exits early (<code>--list</code>, Ctrl+C, an error), it
+deletes the remote session. If the login belongs to the client, the <code>DELETE</code>
+request returns the updated cache files (for example a refreshed token) and the
+client saves them locally, so the <strong>next</strong> remote session can skip interactive
+authentication. The login belongs to the client when the client sent
+cookies, credentials, or cache files, or answered a login prompt (a device code
+or an OTP) that led to a successful login. A server-account login never does.</p>
 </div>
 </div>
 </div>
@@ -2877,9 +2883,10 @@ returns <code>{ "status": "accepted" }</code>. A post with no pending prompt is
 <div class="language-text highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>_sessions/&lt;pbkdf2_hmac(sha256, X-Secret-Key, "unshackle-session-ns", 100000)[:12]&gt;/&lt;session_id&gt;/&lt;service&gt;
 </span></code></pre></div>
 <p>The handler writes forwarded <code>cache</code> files into that directory before authentication.
-On <code>DELETE</code>, the handler harvests updated cache files (compressing each with zlib
-and base64-encoding, <strong>excluding</strong> <code>titles_*</code> files) and returns them under a
-<code>cache</code> field, so the client can keep refreshed tokens:</p>
+On <code>DELETE</code>, when the login belongs to the client (<code>client_auth</code>), the handler
+harvests updated cache files (compressing each with zlib and base64-encoding,
+<strong>excluding</strong> <code>titles_*</code> files) and returns them under a <code>cache</code> field, so the
+client can keep refreshed tokens:</p>
 <div class="language-json highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"cache"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"tokens"</span><span class="p">:</span><span class="w"> </span><span class="s2">"...base64(zlib(bytes))..."</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
 </span></code></pre></div>
 <h3 id="remote-session-info-response">Remote session info response<a class="headerlink" href="#remote-session-info-response" title="Permanent link">&para;</a></h3>