feat(remote): license with the client's device when the user picked one

A remote client that passes --cdm, has a cdm entry for the service that named the loaded device, or sets server_cdm: false now declines the server CDM at session create, and warns when the server keeps it. A service option listed in SERVER_DEVICE_OPTIONS keeps the server CDM.

docs/dev/rest-api/remote-sessions.md

@@ -246,6 +246,14 @@ There are two ways DRM keys get resolved, chosen by the client's `server_cdm` fl
 
     - Keeps your CDM local. The server only relays the license request.
     - Used when `server_cdm` is `false` (the default).
+    - Also used for a run with `dl --cdm <name>`, and for a service whose own entry in
+      your `cdm` config named the loaded device. In each case the client sends
+      `server_cdm: false` when it creates the remote session, and the server builds the
+      service on your device even when the API key has the server CDM.
+    - A service option that the service lists in `SERVER_DEVICE_OPTIONS` keeps the server
+      CDM. The server reads the option from `service_params`, then from the top level of
+      the request. The create response gives the result in `server_cdm`, and the client
+      shows a warning when the server did not apply its choice.
     - The service on the server sees your device, not the server's: its DRM system,
       security level, system ID and device type. A CDM call that the service makes
       (for example a session-key exchange at login) goes to your client as a `cdm_call`,
@@ -412,7 +420,7 @@ The server mounts all these routes, even in `--remote-only` mode. Paths use the
 `POST /api/session/create` requires `service` and `title_id`. It also accepts
 `credentials`, `cookies` (base64 of zlib-compressed Netscape cookie file), `proxy`,
 `no_proxy`, `profile`, `cache` (a map of `filename → base64(zlib(bytes))`),
-`client_region`, `cdm_type`, `cdm_security_level`, `cdm_relay` (`true` when the client
+`client_region`, `server_cdm` (`false` when the user picked the local CDM), `cdm_type`, `cdm_security_level`, `cdm_relay` (`true` when the client
 answers CDM calls), `cdm_system_id` and `cdm_device_type` (Widevine only), `service_config`
 (the identity config keys the service lists in `client_config`), `client` (a freeform identity
 object the dashboard shows as sent), and the track-selection hints `range_`, `vcodec`,

docs/guide/cli-reference.md

@@ -192,7 +192,7 @@ order the service used, then renumbers the episodes into the order you asked for
 | Flag | Description |
 |---|---|
 | `--cdm-only` / `--vaults-only` | Use only the CDM, or only Key Vaults, for key acquisition. |
-| `--cdm <name>` | Use the named CDM device from the `cdm` config mapping for this run, ignoring the service/default mapping. |
+| `--cdm <name>` | Use the named CDM device from the `cdm` config mapping for this run, ignoring the service/default mapping. Over `--remote`, that device licenses the remote session, not the server CDM. |
 | `--skip-dl` | Skip the download but still retrieve keys. |
 | `--export` | Export track info and keys to a `mediaexport` JSON file in the exports directory. |
 

docs/guide/downloading.md

@@ -777,7 +777,7 @@ By default, unshackle checks your **key vaults** first and only asks a **CDM** t
 a content key when the vault misses. You can force one side or the other:
 
 - `--cdm-only`: only use the CDM (skip vaults). Over a `server_cdm` remote session the flag does not reach the server, whose vault shortcut still runs; it only skips the client's decode check on a server key.
-- `--cdm <name>`: use the named CDM device for this run, ignoring the `cdm` config mapping (including its quality and Widevine/PlayReady sub-entries).
+- `--cdm <name>`: use the named CDM device for this run, ignoring the `cdm` config mapping (including its quality and Widevine/PlayReady sub-entries). Over `--remote`, that device licenses the remote session, not the server CDM.
 - `--vaults-only`: only use key vaults and never license through the CDM. A missing
   content key fails.
 

docs/guide/drm-and-cdm.md

@@ -501,7 +501,7 @@ control this trade-off on the `dl` command:
 |------|--------|
 | `--vaults-only` | Never send a license request; use only cached/vault keys. Fails if a content key is missing. |
 | `--cdm-only` | Ignore vaults for sourcing keys and always perform a fresh license request. Over a `server_cdm` remote session the server still reads its own vaults; the flag only skips the client's decode check on the key it gets back. |
-| `--cdm <name>` | Use the named CDM device for this run instead of the one the `cdm` config maps for the service. |
+| `--cdm <name>` | Use the named CDM device for this run instead of the one the `cdm` config maps for the service. Over `--remote`, that device licenses the remote session, not the server CDM. |
 
 See [key vaults](vaults.md) for how to configure vault backends.
 

docs/reference/configuration/drm.md

@@ -13,6 +13,14 @@ Resolution is case-insensitive: an override (`dl --cdm <name>`, or the `cdm` fie
 job) wins, then the per-service entry, then `default`. An override pins one device for the whole
 run and skips any quality or Widevine/PlayReady sub-entries.
 
+Over `--remote`, an override also makes your device license the remote session, not the server
+CDM. A per-service entry does the same when it names a device without a quality: a device name,
+a `widevine` or `playready` sub-entry, or a profile or `default` sub-entry. A per-service entry
+that selects only by quality, or only for a different profile, loads no device when the run
+starts. unshackle then shows a warning, and the server decides who licenses the remote session.
+With only the top-level `default` entry, the server CDM licenses when the API key has it. See
+[`remote_services`](services.md#remote_services).
+
 ```yaml
 cdm:
   default: chromecdm_l3

docs/reference/configuration/services.md

@@ -89,6 +89,15 @@ overrides such as `title_map`.
 Leave `server_cdm` unset and the client follows the server: it uses the server CDM for each
 service the API key has it on, and the local CDM for the others. `true` asks for the server CDM
 and falls back to the local CDM when the server refuses; `false` always uses the local CDM.
+`dl --cdm <name>` on a remote run has the same effect as `false` for that run: the device you
+name licenses the remote session. A [`cdm`](drm.md#cdm) entry for the service has the same
+effect for that service when it names the device that unshackle loaded. Both take priority over
+`server_cdm: true`. Remove the entry to use the server CDM for that service. The `default`
+entry does not count.
+
+The server has the last word. When it keeps the server CDM for a remote session that your
+device was to license, unshackle shows a warning. This occurs with a server that does not read
+your choice, and with a service option that runs the remote session on the server's device.
 
 `auth_headers` lists extra header names to send the API key in, tried before the defaults
 `X-Secret-Key` and `X-Api-Key`, which unshackle always appends as fallbacks. It sends the
@@ -154,6 +163,12 @@ client that asks anyway gets a `FORBIDDEN` error. Because a download job always
 an API key without `server_cdm` for that service also cannot submit or retry `/api/download`
 jobs. Keys that have no `users` entry, such as `api_secret`, keep server CDM access.
 
+A remote client that picks its own device licenses the remote session with that device. It picks
+with `dl --cdm`, with a `cdm` entry for the service, or with `server_cdm: false` in its
+`remote_services` entry. The server CDM makes no licence for that remote session, with or without
+a limit. A service option that runs the remote session on the server's device, such as a
+server-identity flag, keeps the server CDM.
+
 `server_cdm_max_height` limits the live licences the server's device makes for that API key.
 Set it to a height in pixels for every service, or to a map of service tag to height with an
 optional `default` entry. A service the map does not name or sets to `null` gets the `default`, and