@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/utilities/ff1-compatibility.js

@@ -42,6 +42,8 @@ const http_1 = require("./http");
 const config_1 = require("../config");
 const device_lookup_1 = require("./device-lookup");
 const logger = __importStar(require("../logger"));
+const secure_transport_1 = require("./control/secure-transport");
+const control_errors_1 = require("./control/control-errors");
 const FF1_COMMAND_POLICIES = {
     displayPlaylist: {
         minimumVersion: '1.0.0',
@@ -118,7 +120,12 @@ async function assertFF1CommandCompatibility(device, command, options = {}) {
     // the TCP connection but never answers must not hang `ff-cli ssh`.
     const fetchFn = options.fetchFn || ((input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}));
     const policy = getCommandPolicy(command);
-    const versionResult = await detectFF1VersionSafely(device.host, buildVersionHeaders(device), fetchFn);
+    const versionResult = options.controller && device.id
+        ? await detectFF1VersionSecurely(device, options.controller)
+        : await detectFF1VersionSafely(device, buildVersionHeaders(device), fetchFn);
+    if (versionResult?.refusal) {
+        return { compatible: false, ...versionResult.refusal };
+    }
     return resolveCompatibility(device, command, policy, versionResult);
 }
 /**
@@ -135,14 +142,14 @@ function getCommandPolicy(command) {
 /**
  * Detect FF1 version and recover compatibility when detection fails.
  *
- * @param {string} host - Device host URL
+ * @param {FF1Device} device - Target device
  * @param {Object} headers - Request headers
  * @param {Function} fetchFn - Fetch implementation
  * @returns {Promise<FF1VersionProbe | null>} Detected version metadata
  */
-async function detectFF1VersionSafely(host, headers, fetchFn) {
+async function detectFF1VersionSafely(device, headers, fetchFn) {
     try {
-        return await detectFF1Version(host, headers, fetchFn);
+        return await detectFF1Version(device, headers, fetchFn);
     }
     catch (error) {
         logger.debug('FF1 version detection failed; continuing with command', error.message);
@@ -159,7 +166,7 @@ async function detectFF1VersionSafely(host, headers, fetchFn) {
  * @returns {FF1CompatibilityResult} Compatibility decision
  */
 function resolveCompatibility(device, command, policy, versionResult) {
-    if (!versionResult) {
+    if (!versionResult?.version) {
         logger.warn(`Could not verify FF1 OS version for ${device.name || device.host}`);
         return { compatible: true };
     }
@@ -187,22 +194,22 @@ function resolveCompatibility(device, command, policy, versionResult) {
  *
  * Reads `message.installedVersion` from the device status response.
  *
- * @param {string} host - Device host URL
+ * @param {FF1Device} device - Target device
  * @param {Record<string, string>} headers - Request headers (e.g. API-KEY)
  * @param {FetchFunction} fetchFn - Fetch implementation
- * @returns {Promise<FF1VersionProbe | null>} Version probe or null if unavailable
+ * @returns {Promise<FF1VersionProbe | null>} Version probe, a refusal, or null if unavailable
  * @example
- * const probe = await detectFF1Version('http://ff1.local', {}, fetch);
+ * const probe = await detectFF1Version(device, {}, fetch);
  */
-async function detectFF1Version(host, headers, fetchFn) {
+async function detectFF1Version(device, headers, fetchFn) {
     try {
-        const response = await fetchFn(`${host}/api/cast`, {
+        const response = await fetchFn(`${device.host}/api/cast`, {
             method: 'POST',
             headers: { ...headers, 'Content-Type': 'application/json' },
             body: JSON.stringify({ command: 'getDeviceStatus', request: {} }),
         });
         if (!response.ok) {
-            return null;
+            return refusalFromPublicError(response.status, await response.text(), device.name || device.id || device.host);
         }
         const data = (await response.json());
         const version = data?.message?.installedVersion;
@@ -215,6 +222,75 @@ async function detectFF1Version(host, headers, fetchFn) {
         return null;
     }
 }
+/**
+ * refusalFromPublicError recognizes a secured FF1 refusing a plaintext LAN
+ * cast (ff1-control-v1 §4.4, HTTP 403 `enrollment_required`). That answer
+ * means every plaintext command will be refused, so the preflight stops with
+ * the pairing guidance instead of sending the real command into the same 403.
+ * Any other failure keeps the historical "could not verify" behavior.
+ *
+ * @param status - HTTP status
+ * @param body - Response body text
+ * @param label - Device name for the pair command
+ * @returns A refusal probe, or null
+ */
+function refusalFromPublicError(status, body, label) {
+    if (status !== 401 && status !== 403) {
+        return null;
+    }
+    try {
+        const code = JSON.parse(body)?.error?.code;
+        if (code === 'enrollment_required' || code === 'locked') {
+            return { refusal: (0, control_errors_1.describeControlCode)(code, label) };
+        }
+    }
+    catch {
+        // Not a control-protocol answer.
+    }
+    return null;
+}
+/**
+ * TRANSIENT_PROBE_CODES are secure-probe answers that do not mean "this
+ * controller may not proceed": the FF1 shed load (busy, rate_limited, or the
+ * router's storm protection surfacing as command_failed) or could not record
+ * the replay window (internal_error, §4.3: not executed, retry with a new ctr).
+ * The plaintext probe sees the same conditions as HTTP 429 and carries on, so
+ * the secure probe does too; the real command then applies its own retries.
+ */
+const TRANSIENT_PROBE_CODES = new Set(['busy', 'rate_limited', 'internal_error', 'command_failed']);
+/**
+ * detectFF1VersionSecurely runs the getDeviceStatus probe as a secure
+ * envelope over the LAN only (no retry, no relayer: the probe never had
+ * either). A protocol refusal (revoked, unknown controller, …) stops the
+ * command with actionable guidance; an unreachable device degrades to
+ * "could not verify", exactly like the plaintext probe.
+ *
+ * @param device - Device with a stable ID
+ * @param controller - Enrolled controller record and transport seams
+ * @returns Version probe, refusal, or null
+ */
+async function detectFF1VersionSecurely(device, controller) {
+    const result = await (0, secure_transport_1.runSecureCommand)({
+        device,
+        record: controller.record,
+        cmd: 'getDeviceStatus',
+        req: {},
+        relayerFallback: false,
+        retry: false,
+    }, controller.deps);
+    if (!result.success) {
+        if (result.code && !TRANSIENT_PROBE_CODES.has(result.code)) {
+            return { refusal: { error: result.error, details: result.details } };
+        }
+        logger.debug('Secure FF1 version probe failed; continuing with command', result.error);
+        return null;
+    }
+    // res is the handler's existing body; accept both the bare status object
+    // and the `{message:{…}}` wrapper the plaintext LAN reply uses.
+    const res = result.response;
+    const version = res?.installedVersion ?? res?.message?.installedVersion;
+    return typeof version === 'string' && version ? { version } : null;
+}
 /**
  * Build headers shared by cast requests.
  *

package/dist/src/utilities/ff1-device.js

@@ -37,21 +37,36 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
-exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.parseRetryAfterMs = exports.isTransientDeviceNetworkError = void 0;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
+exports.publicControlCode = publicControlCode;
 const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const config_1 = require("../config");
 const ff1_compatibility_1 = require("./ff1-compatibility");
 const ff1_relayer_1 = require("./ff1-relayer");
 const topic_store_1 = require("./topic-store");
+const secure_transport_1 = require("./control/secure-transport");
+const control_errors_1 = require("./control/control-errors");
+const device_network_1 = require("./device-network");
+Object.defineProperty(exports, "isTransientDeviceNetworkError", { enumerable: true, get: function () { return device_network_1.isTransientDeviceNetworkError; } });
+Object.defineProperty(exports, "parseRetryAfterMs", { enumerable: true, get: function () { return device_network_1.parseRetryAfterMs; } });
 const SEND_RETRY_ATTEMPTS = 3;
 const SEND_RETRY_BASE_DELAY_MS = 750;
 const RATE_LIMIT_STATUS = 429;
 // Cap how long a device-supplied Retry-After can stall the CLI, so a buggy or
 // hostile device cannot pin a command for minutes/hours.
 const MAX_RETRY_DELAY_MS = 30_000;
+// PUBLIC_CONTROL_CODES are the ff1-control-v1 §4.4 public errors a secured
+// FF1 can answer a plaintext cast with (LAN 401/403, relayer RPC message).
+const PUBLIC_CONTROL_CODES = new Set([
+    'bad_envelope',
+    'unknown_controller',
+    'bad_signature',
+    'enrollment_required',
+    'envelope_required',
+    'locked',
+]);
 /** Find an FF1 `ok` flag through the nested cast response envelopes. */
 function nestedCastOk(value) {
     if (!value || typeof value !== 'object') {
@@ -74,78 +89,6 @@ function waitForRetry(delayMs) {
         setTimeout(resolve, delayMs);
     });
 }
-/**
- * isTransientDeviceNetworkError returns true when a send failure is likely temporary.
- *
- * This classifier intentionally targets resolver and route-level failures that are
- * common on local mDNS/Wi-Fi environments. Permanent command errors should surface
- * immediately without retry loops.
- *
- * @param {unknown} error - Error thrown by fetch
- * @returns {boolean} True when retrying is likely to recover
- */
-function isTransientDeviceNetworkError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    const networkCodes = new Set([
-        'EHOSTUNREACH',
-        'ENETUNREACH',
-        'ENOTFOUND',
-        'EAI_AGAIN',
-        'ETIMEDOUT',
-        'ECONNREFUSED',
-        'ECONNRESET',
-    ]);
-    const message = error.message || '';
-    const messageLooksTransient = message.includes('fetch failed') ||
-        message.includes('getaddrinfo') ||
-        message.includes('EHOSTUNREACH') ||
-        message.includes('ENOTFOUND') ||
-        message.includes('ETIMEDOUT') ||
-        message.includes('network timeout') ||
-        message.includes('No route to host');
-    if (messageLooksTransient) {
-        return true;
-    }
-    const causeCode = error.cause &&
-        typeof error.cause === 'object' &&
-        'code' in error.cause &&
-        typeof error.cause.code === 'string'
-        ? error.cause.code
-        : undefined;
-    return Boolean(causeCode && networkCodes.has(causeCode));
-}
-/**
- * parseRetryAfterMs converts an HTTP `Retry-After` header into milliseconds.
- *
- * Supports both forms from RFC 7231: a delta-seconds integer (e.g. "5") and an
- * HTTP-date (e.g. "Wed, 21 Oct 2025 07:28:00 GMT"). Returns undefined when the
- * header is absent or unparseable, so callers can fall back to their own
- * backoff. A past date clamps to 0 (retry immediately).
- *
- * @param {string | null | undefined} headerValue - Raw Retry-After header value
- * @returns {number | undefined} Delay in milliseconds, or undefined if unknown
- */
-function parseRetryAfterMs(headerValue) {
-    if (!headerValue) {
-        return undefined;
-    }
-    const trimmed = headerValue.trim();
-    if (/^\d+$/.test(trimmed)) {
-        return Number(trimmed) * 1000;
-    }
-    // A valid HTTP-date always contains letters (month/day names, or the ISO
-    // 'T'/'Z'). Requiring one rejects bare numeric junk (e.g. "-5", "5.5") that
-    // Date.parse would otherwise misinterpret as a date.
-    if (/[a-zA-Z]/.test(trimmed)) {
-        const dateMs = Date.parse(trimmed);
-        if (!Number.isNaN(dateMs)) {
-            return Math.max(0, dateMs - Date.now());
-        }
-    }
-    return undefined;
-}
 /**
  * Send a DP1 playlist to an FF1 device using the cast API
  *
@@ -186,6 +129,8 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
         getRelayerConfigFn: overrides.getRelayerConfigFn ?? config_1.getFF1RelayerConfig,
         waitFn: overrides.waitFn ?? waitForRetry,
         noticeFn: overrides.noticeFn ?? logger.always,
+        controllerStore: overrides.controllerStore,
+        nowFn: overrides.nowFn,
     };
     let device;
     try {
@@ -204,16 +149,30 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
             };
         }
         device = resolved.device;
+        // A stored controller file means this FF1 was paired under the control
+        // protocol (ff1-control-v1): every command goes as a secure envelope and
+        // the legacy plaintext path below is never used for it.
+        const secure = (0, secure_transport_1.findSecureController)(device, dependencies.controllerStore);
+        if (secure.failure) {
+            return { success: false, error: secure.failure.error, details: secure.failure.details };
+        }
         const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist', {
             fetchFn: dependencies.fetchFn,
+            controller: secure.record
+                ? { record: secure.record, deps: secureDeps(dependencies) }
+                : undefined,
         });
         if (!compatibility.compatible) {
             return {
                 success: false,
                 error: compatibility.error || 'FF1 OS does not support playlist casting',
-                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
+                details: compatibility.details ??
+                    (compatibility.version ? `Detected version ${compatibility.version}` : undefined),
             };
         }
+        if (secure.record) {
+            return sendPlaylistSecurely(playlist, device, secure.record, dependencies);
+        }
         logger.info(`Sending playlist to FF1 device: ${device.host}`);
         const apiUrl = `${device.host}/api/cast`;
         // Wrap playlist in required structure
@@ -251,7 +210,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
                 // Treat it as transient: honor Retry-After when present, otherwise back
                 // off, and retry within the bounded attempt budget.
                 if (response.status === RATE_LIMIT_STATUS && attempt < SEND_RETRY_ATTEMPTS) {
-                    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+                    const retryAfterMs = (0, device_network_1.parseRetryAfterMs)(response.headers.get('retry-after'));
                     const retryDelay = Math.min(retryAfterMs ?? SEND_RETRY_BASE_DELAY_MS * attempt, MAX_RETRY_DELAY_MS);
                     logger.warn(`Device rate-limited the command (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
                     response = null;
@@ -291,7 +250,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
                 break;
             }
             catch (error) {
-                const shouldRetry = attempt < SEND_RETRY_ATTEMPTS && isTransientDeviceNetworkError(error);
+                const shouldRetry = attempt < SEND_RETRY_ATTEMPTS && (0, device_network_1.isTransientDeviceNetworkError)(error);
                 if (!shouldRetry) {
                     throw error;
                 }
@@ -320,6 +279,11 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
             const errorText = await response.text();
             logger.error(`Failed to cast to device: ${response.status} ${response.statusText}`);
             logger.debug(`Error details: ${errorText}`);
+            const publicCode = publicControlCode(response.status, errorText);
+            if (publicCode) {
+                const failure = (0, control_errors_1.describeControlCode)(publicCode, device.name || device.id || device.host);
+                return { success: false, error: failure.error, details: failure.details };
+            }
             if (response.status === RATE_LIMIT_STATUS) {
                 const deviceLabel = device.name || device.host;
                 return {
@@ -368,7 +332,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
     catch (error) {
         const errorMessage = error.message;
         logger.error(`Error sending playlist to device: ${errorMessage}`);
-        if (device && isTransientDeviceNetworkError(error)) {
+        if (device && (0, device_network_1.isTransientDeviceNetworkError)(error)) {
             const deviceLabel = device.name || device.host;
             return fallbackToRelayer({
                 playlist,
@@ -388,6 +352,117 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
         };
     }
 }
+/**
+ * secureDeps forwards the delivery seams to the secure transport.
+ *
+ * @param dependencies - Resolved delivery dependencies
+ * @returns Secure transport dependencies
+ */
+function secureDeps(dependencies) {
+    return {
+        fetchFn: dependencies.fetchFn,
+        getTopicIdFn: dependencies.getTopicIdFn,
+        getRelayerConfigFn: dependencies.getRelayerConfigFn,
+        waitFn: dependencies.waitFn,
+        noticeFn: dependencies.noticeFn,
+        controllerStore: dependencies.controllerStore,
+        nowFn: dependencies.nowFn,
+    };
+}
+/**
+ * sendPlaylistSecurely delivers displayPlaylist as a secure envelope with the
+ * same retry budget and LAN-then-relayer fallback as the plaintext path. The
+ * `req` is the unchanged plaintext request object (§3.3).
+ *
+ * @param playlist - DP-1 playlist
+ * @param device - Device with a stored controller record
+ * @param record - Enrolled controller record
+ * @param dependencies - Delivery seams
+ * @returns Send result
+ */
+async function sendPlaylistSecurely(playlist, device, record, dependencies) {
+    logger.info(`Sending playlist to FF1 device (secure): ${device.host}`);
+    const result = await (0, secure_transport_1.runSecureCommand)({
+        device: device,
+        record,
+        cmd: 'displayPlaylist',
+        req: { dp1_call: playlist, intent: { action: 'now_display' } },
+        relayerFallback: true,
+        retry: true,
+    }, secureDeps(dependencies));
+    const deviceName = device.name || device.host;
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error,
+            details: result.details,
+            transport: result.transport,
+        };
+    }
+    if (nestedCastOk(result.response) === false) {
+        return {
+            success: false,
+            error: `Device "${deviceName}" rejected the display command`,
+            details: JSON.stringify(result.response),
+            transport: result.transport,
+        };
+    }
+    const viaRelayer = result.transport === 'relayer';
+    return {
+        success: true,
+        device: device.host,
+        deviceName,
+        response: result.response,
+        message: viaRelayer
+            ? 'Playlist successfully sent through the FF1 relayer'
+            : 'Playlist successfully sent to FF1 device',
+        transport: result.transport,
+    };
+}
+/**
+ * publicControlCode extracts a control-protocol public error (§4.4) from a
+ * LAN 401/403, e.g. a secured FF1 refusing plaintext with
+ * `enrollment_required`. Other bodies return undefined.
+ *
+ * @param status - HTTP status
+ * @param body - Response text
+ * @returns The code, or undefined
+ */
+function publicControlCode(status, body) {
+    if (status !== 401 && status !== 403) {
+        return undefined;
+    }
+    try {
+        const code = JSON.parse(body)?.error?.code;
+        return typeof code === 'string' && PUBLIC_CONTROL_CODES.has(code) ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * plaintextRefusalCode finds a control-protocol refusal in a relayer reply:
+ * the flat plaintext denial `{ok:false,error:"<code>",command,message}` or the
+ * public-error shape `{error:{code}}`, at any of the relayer's nesting levels.
+ *
+ * @param response - Parsed relayer response
+ * @returns A §4.4 code, or undefined
+ */
+function plaintextRefusalCode(response) {
+    let current = response;
+    for (let depth = 0; depth < 3 && current && typeof current === 'object'; depth += 1) {
+        const record = current;
+        const error = record.error;
+        const code = record.ok === false && typeof error === 'string'
+            ? error
+            : error?.code;
+        if (typeof code === 'string' && PUBLIC_CONTROL_CODES.has(code)) {
+            return code;
+        }
+        current = record.message;
+    }
+    return undefined;
+}
 /**
  * Fall back to the relayer only after LAN reachability is exhausted.
  *
@@ -437,6 +512,14 @@ async function fallbackToRelayer(input) {
         playlist: input.playlist,
         fetchFn: input.dependencies.fetchFn,
     });
+    // A secured FF1 refuses a plaintext relayer cast it will not run
+    // (ff1-control-v1 §4.4/§7.2) with a flat `{ok:false,error:"<code>"}` RPC
+    // message; map it to pairing guidance instead of a bare rejection.
+    const refusal = plaintextRefusalCode(result.response);
+    if (refusal) {
+        const failure = (0, control_errors_1.describeControlCode)(refusal, input.device.name ?? input.device.id);
+        return { success: false, error: failure.error, details: failure.details, transport: 'relayer' };
+    }
     if (!result.success) {
         return {
             success: false,

package/dist/src/utilities/ff1-relayer.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendPlaylistViaRelayer = sendPlaylistViaRelayer;
+exports.sendCastViaRelayer = sendCastViaRelayer;
 const http_1 = require("./http");
 function nestedOk(value) {
     if (!value || typeof value !== 'object') {
@@ -27,6 +28,37 @@ function nestedOk(value) {
  * and JSON parsing errors.
  */
 async function sendPlaylistViaRelayer(input) {
+    const result = await sendCastViaRelayer({
+        ...input,
+        body: {
+            command: 'displayPlaylist',
+            request: {
+                dp1_call: input.playlist,
+                intent: { action: 'now_display' },
+            },
+        },
+    });
+    if (result.success && nestedOk(result.response) === false) {
+        return {
+            success: false,
+            error: 'FF1 rejected the relayer display command',
+            details: JSON.stringify(result.response),
+            response: result.response,
+        };
+    }
+    return result;
+}
+/**
+ * sendCastViaRelayer posts one cast body to the relayer topic endpoint and
+ * returns the parsed JSON response without interpreting the device's answer.
+ * It is shared by the legacy plaintext Play path and the secure `ff1Envelope`
+ * path (ff1-control-v1 §10: the envelope rides the same topic cast).
+ *
+ * @param input - Relayer endpoint, optional compatibility key, paired topic,
+ * cast body, and optional fetch implementation.
+ * @returns The parsed relayer response, or a structured failure.
+ */
+async function sendCastViaRelayer(input) {
     // Production default rides the shared deadline (#101 review).
     const fetchFn = input.fetchFn ?? http_1.defaultDeadlineFetch;
     let url;
@@ -53,13 +85,7 @@ async function sendPlaylistViaRelayer(input) {
             // the mobile request shape and topic query parameter.
             method: 'POST',
             headers,
-            body: JSON.stringify({
-                command: 'displayPlaylist',
-                request: {
-                    dp1_call: input.playlist,
-                    intent: { action: 'now_display' },
-                },
-            }),
+            body: JSON.stringify(input.body),
         });
     }
     catch (error) {
@@ -78,6 +104,7 @@ async function sendPlaylistViaRelayer(input) {
         return {
             success: false,
             error: `FF1 relayer returned HTTP ${response.status}`,
+            status: response.status,
             details: needsCompatibilityKey
                 ? 'This relayer deployment still requires its optional FF1_RELAYER_API_KEY compatibility gate.'
                 : bodyText || response.statusText,
@@ -96,12 +123,5 @@ async function sendPlaylistViaRelayer(input) {
             };
         }
     }
-    if (nestedOk(data) === false) {
-        return {
-            success: false,
-            error: 'FF1 rejected the relayer display command',
-            details: bodyText,
-        };
-    }
     return { success: true, response: data };
 }

package/dist/src/utilities/handoff-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TopicHandoffReceiver = void 0;
+exports.HandoffReceiver = void 0;
+exports.parseHandoffPayload = parseHandoffPayload;
 const http_1 = require("./http");
 const handoff_crypto_1 = require("./handoff-crypto");
 const DEFAULT_HANDOFF_URL = 'https://handoff.feralfile.com';
@@ -33,6 +34,19 @@ function parsePoll(value, channelId) {
     }
     return record;
 }
+/**
+ * parseHandoffPayload accepts a v1 topic handoff for the selected device and
+ * rejects everything else, including a retired v2 controller handoff.
+ *
+ * @param value - Decrypted handoff plaintext
+ * @param channelId - This receiver's channel
+ * @param expectedDeviceId - The configured device's stable ID
+ * @returns The validated payload
+ * @throws {Error} When the payload is for another channel or device, or malformed
+ */
+function parseHandoffPayload(value, channelId, expectedDeviceId) {
+    return parseTopicPayload(value, channelId, expectedDeviceId);
+}
 function parseTopicPayload(value, channelId, expectedDeviceId) {
     const payload = value;
     if (payload?.v !== 1 ||
@@ -48,8 +62,8 @@ function parseTopicPayload(value, channelId, expectedDeviceId) {
     }
     return payload;
 }
-/** One short-lived CLI-side channel waiting for a mobile topic transfer. */
-class TopicHandoffReceiver {
+/** One short-lived CLI-side channel waiting for a mobile topic handoff. */
+class HandoffReceiver {
     baseUrl;
     channelId;
     shortCode;
@@ -90,10 +104,10 @@ class TopicHandoffReceiver {
             channelId: created.channelId,
             minterPublicKeyJwk: publicKey,
         });
-        return new TopicHandoffReceiver(baseUrl, created.channelId, created.shortCode, verificationCode, created.expiresAt, created.minterToken, keyPair.privateKey, fetchFn);
+        return new HandoffReceiver(baseUrl, created.channelId, created.shortCode, verificationCode, created.expiresAt, created.minterToken, keyPair.privateKey, fetchFn);
     }
-    /** Poll until mobile sends a valid encrypted topic for the selected device. */
-    async receiveTopic(options) {
+    /** Poll until mobile sends a valid encrypted topic handoff for the selected device. */
+    async receiveHandoff(options) {
         const deadline = Date.now() + (options.maxWaitMs ?? 300_000);
         let afterSeq = 0;
         while (Date.now() <= deadline) {
@@ -117,11 +131,11 @@ class TopicHandoffReceiver {
                     seq: message.seq,
                     message,
                 });
-                return parseTopicPayload(plaintext, this.channelId, options.expectedDeviceId);
+                return parseHandoffPayload(plaintext, this.channelId, options.expectedDeviceId);
             }
             await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1000));
         }
-        throw new Error('Timed out waiting for the mobile app topic transfer');
+        throw new Error('Timed out waiting for the mobile app handoff');
     }
     /** Close the broker channel and invalidate its participant credentials. */
     async close() {
@@ -134,4 +148,4 @@ class TopicHandoffReceiver {
         }
     }
 }
-exports.TopicHandoffReceiver = TopicHandoffReceiver;
+exports.HandoffReceiver = HandoffReceiver;