@feralfile/cli 3.0.0 → 4.0.0

package/dist/src/utilities/control/strict-json.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * Strict JSON and base64url decoding for the FF1 control protocol v1
+ * (ffos-user docs/ff1-control-v1.md §1).
+ *
+ * Why this exists instead of `JSON.parse`: two implementations that disagree
+ * about what a byte string means (which of two duplicate `kid` members wins,
+ * whether `1.0` is the integer 1) are a signature-confusion bug. `JSON.parse`
+ * silently keeps the LAST duplicate and erases the difference between `1`,
+ * `1.0` and `1e0`, so every header, claims object and JWK that crosses the
+ * trust boundary is parsed here instead. The Go reference (control/json.go)
+ * applies the same rules; keep the two in step.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlFormatError = void 0;
+exports.b64uDecode = b64uDecode;
+exports.b64uEncode = b64uEncode;
+exports.isB64uOfLength = isB64uOfLength;
+exports.utf8Decode = utf8Decode;
+exports.parseStrictJson = parseStrictJson;
+exports.isPlainObject = isPlainObject;
+exports.strictObject = strictObject;
+exports.stringMember = stringMember;
+exports.uintMember = uintMember;
+exports.boolMember = boolMember;
+exports.toPlainJson = toPlainJson;
+/** ControlFormatError is thrown for every malformed protocol object. */
+class ControlFormatError extends Error {
+    constructor(message) {
+        super(`ff1-control: ${message}`);
+        this.name = 'ControlFormatError';
+    }
+}
+exports.ControlFormatError = ControlFormatError;
+/** MAX_SAFE_CLAIM_INT is 2^53-1, the integer ceiling of §1. */
+const MAX_SAFE_CLAIM_INT = Number.MAX_SAFE_INTEGER;
+/** MAX_JSON_DEPTH bounds nesting, matching the Go reference's maxJSONDepth. */
+const MAX_JSON_DEPTH = 128;
+/**
+ * rawNumbers remembers the exact source text of every number member of every
+ * parsed object, so integer claims can be checked for canonical form after
+ * parsing (JSON.parse-style values cannot tell `1` from `1.0`).
+ */
+const rawNumbers = new WeakMap();
+const B64U_ALPHABET = /^[A-Za-z0-9_-]*$/;
+/**
+ * b64uDecode decodes unpadded base64url strictly: `=` padding, whitespace,
+ * any non-alphabet byte and non-zero trailing bits are all rejected (§1). The
+ * round-trip comparison is what catches non-canonical trailing bits, which
+ * Node's lenient decoder would otherwise accept.
+ *
+ * @param value - Candidate base64url text
+ * @returns The decoded bytes
+ * @throws {ControlFormatError} When the text is not canonical base64url
+ */
+function b64uDecode(value) {
+    if (typeof value !== 'string' || !B64U_ALPHABET.test(value) || value.length % 4 === 1) {
+        throw new ControlFormatError('invalid base64url');
+    }
+    const bytes = Buffer.from(value, 'base64url');
+    if (bytes.toString('base64url') !== value) {
+        throw new ControlFormatError('non-canonical base64url');
+    }
+    return new Uint8Array(bytes);
+}
+/**
+ * b64uEncode encodes bytes as unpadded base64url.
+ *
+ * @param bytes - Bytes or UTF-8 text to encode
+ * @returns Unpadded base64url text
+ */
+function b64uEncode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+/**
+ * isB64uOfLength reports whether value is canonical base64url of exactly n bytes.
+ *
+ * @param value - Candidate value
+ * @param n - Required decoded length
+ * @returns True when the value decodes to exactly n bytes
+ */
+function isB64uOfLength(value, n) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    try {
+        return b64uDecode(value).length === n;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * utf8Decode decodes bytes as UTF-8, rejecting invalid sequences (§1). A
+ * lenient decoder would map them to U+FFFD and let two different byte strings
+ * read as the same JSON.
+ *
+ * @param bytes - Raw bytes
+ * @returns The decoded string
+ * @throws {ControlFormatError} On invalid UTF-8
+ */
+function utf8Decode(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new ControlFormatError('invalid UTF-8');
+    }
+}
+/** StrictParser is a small recursive-descent JSON parser with duplicate-key detection. */
+class StrictParser {
+    text;
+    pos = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    parseDocument() {
+        const value = this.parseValue(0);
+        this.skipWhitespace();
+        if (this.pos !== this.text.length) {
+            throw new ControlFormatError('trailing data after JSON value');
+        }
+        return value;
+    }
+    fail(message) {
+        throw new ControlFormatError(`invalid JSON at ${this.pos}: ${message}`);
+    }
+    skipWhitespace() {
+        while (this.pos < this.text.length && ' \t\r\n'.includes(this.text[this.pos])) {
+            this.pos += 1;
+        }
+    }
+    parseValue(depth) {
+        if (depth > MAX_JSON_DEPTH) {
+            this.fail('nested too deeply');
+        }
+        this.skipWhitespace();
+        const ch = this.text[this.pos];
+        if (ch === '{') {
+            return this.parseObject(depth);
+        }
+        if (ch === '[') {
+            return this.parseArray(depth);
+        }
+        if (ch === '"') {
+            return this.parseString();
+        }
+        if (ch === '-' || (ch >= '0' && ch <= '9')) {
+            return Number(this.parseNumberText());
+        }
+        for (const [literal, value] of [
+            ['true', true],
+            ['false', false],
+            ['null', null],
+        ]) {
+            if (this.text.startsWith(literal, this.pos)) {
+                this.pos += literal.length;
+                return value;
+            }
+        }
+        return this.fail('unexpected token');
+    }
+    parseObject(depth) {
+        this.pos += 1;
+        // A null-prototype object keeps a member named "__proto__" an ordinary
+        // member instead of a prototype assignment.
+        const out = Object.create(null);
+        const numbers = new Map();
+        this.skipWhitespace();
+        if (this.text[this.pos] === '}') {
+            this.pos += 1;
+            rawNumbers.set(out, numbers);
+            return out;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.pos] !== '"') {
+                this.fail('object key is not a string');
+            }
+            // Keys are compared after unescaping, so "typ" and "typ" collide.
+            const key = this.parseString();
+            if (Object.prototype.hasOwnProperty.call(out, key)) {
+                this.fail(`duplicate member ${JSON.stringify(key)}`);
+            }
+            this.skipWhitespace();
+            if (this.text[this.pos] !== ':') {
+                this.fail('expected ":"');
+            }
+            this.pos += 1;
+            this.skipWhitespace();
+            const start = this.pos;
+            out[key] = this.parseValue(depth + 1);
+            if (typeof out[key] === 'number') {
+                numbers.set(key, this.text.slice(start, this.pos));
+            }
+            this.skipWhitespace();
+            const sep = this.text[this.pos];
+            this.pos += 1;
+            if (sep === '}') {
+                rawNumbers.set(out, numbers);
+                return out;
+            }
+            if (sep !== ',') {
+                this.fail('expected "," or "}"');
+            }
+        }
+    }
+    parseArray(depth) {
+        this.pos += 1;
+        const out = [];
+        this.skipWhitespace();
+        if (this.text[this.pos] === ']') {
+            this.pos += 1;
+            return out;
+        }
+        for (;;) {
+            out.push(this.parseValue(depth + 1));
+            this.skipWhitespace();
+            const sep = this.text[this.pos];
+            this.pos += 1;
+            if (sep === ']') {
+                return out;
+            }
+            if (sep !== ',') {
+                this.fail('expected "," or "]"');
+            }
+        }
+    }
+    parseString() {
+        const start = this.pos;
+        this.pos += 1;
+        for (;;) {
+            const ch = this.text[this.pos];
+            if (ch === undefined) {
+                this.fail('unterminated string');
+            }
+            if (ch === '"') {
+                this.pos += 1;
+                break;
+            }
+            if (ch === '\\') {
+                this.pos += 2;
+                continue;
+            }
+            if (ch < ' ') {
+                this.fail('control character in string');
+            }
+            this.pos += 1;
+        }
+        // The span is grammar-checked by JSON.parse, which also unescapes it.
+        try {
+            return JSON.parse(this.text.slice(start, this.pos));
+        }
+        catch {
+            return this.fail('invalid string escape');
+        }
+    }
+    parseNumberText() {
+        const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(this.text.slice(this.pos));
+        if (!match) {
+            this.fail('invalid number');
+        }
+        this.pos += match[0].length;
+        return match[0];
+    }
+}
+/**
+ * parseStrictJson parses UTF-8 JSON text with the §1 rules: one value, no
+ * trailing data, no duplicate member names at any depth.
+ *
+ * @param input - JSON text or raw UTF-8 bytes
+ * @returns The parsed value; objects have a null prototype
+ * @throws {ControlFormatError} On any violation
+ */
+function parseStrictJson(input) {
+    const text = typeof input === 'string' ? input : utf8Decode(input);
+    return new StrictParser(text).parseDocument();
+}
+/**
+ * isPlainObject reports whether value is a parsed JSON object (not an array or null).
+ *
+ * @param value - Candidate value
+ * @returns True for JSON objects
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * strictObject requires value to be an object whose member names are all in
+ * required ∪ optional, with every required member present (§1 closed sets).
+ *
+ * @param value - Parsed JSON value
+ * @param required - Members that must be present
+ * @param optional - Members that may be present
+ * @param what - Name used in error messages
+ * @returns The object, typed as a record
+ * @throws {ControlFormatError} On any extra or missing member
+ */
+function strictObject(value, required, optional, what) {
+    if (!isPlainObject(value)) {
+        throw new ControlFormatError(`${what} is not a JSON object`);
+    }
+    for (const key of Object.keys(value)) {
+        if (!required.includes(key) && !optional.includes(key)) {
+            throw new ControlFormatError(`${what} has unexpected member ${JSON.stringify(key)}`);
+        }
+    }
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            throw new ControlFormatError(`${what} is missing member ${JSON.stringify(key)}`);
+        }
+    }
+    return value;
+}
+/**
+ * stringMember returns a required string member.
+ *
+ * @param obj - Parsed object
+ * @param key - Member name
+ * @returns The string value
+ * @throws {ControlFormatError} When the member is absent or not a string
+ */
+function stringMember(obj, key) {
+    const value = obj[key];
+    if (typeof value !== 'string') {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a string`);
+    }
+    return value;
+}
+/**
+ * uintMember returns a canonical non-negative integer member in [0, 2^53-1].
+ * `1.0`, `1e3`, `-0`, `01` and quoted numbers are rejected (§1): the Dart,
+ * JS and Go encoders never produce them, so seeing one means a hand-built or
+ * hostile object. Only objects produced by parseStrictJson can be checked.
+ *
+ * @param obj - Object returned by parseStrictJson
+ * @param key - Member name
+ * @returns The integer value
+ * @throws {ControlFormatError} When absent, non-canonical or out of range
+ */
+function uintMember(obj, key) {
+    const raw = rawNumbers.get(obj)?.get(key);
+    if (raw === undefined || !/^(?:0|[1-9]\d*)$/.test(raw)) {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a canonical integer`);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value > MAX_SAFE_CLAIM_INT) {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is out of range`);
+    }
+    return value;
+}
+/**
+ * boolMember returns a required boolean member.
+ *
+ * @param obj - Parsed object
+ * @param key - Member name
+ * @returns The boolean value
+ * @throws {ControlFormatError} When absent or not a boolean
+ */
+function boolMember(obj, key) {
+    const value = obj[key];
+    if (typeof value !== 'boolean') {
+        throw new ControlFormatError(`member ${JSON.stringify(key)} is not a boolean`);
+    }
+    return value;
+}
+/**
+ * toPlainJson deep-copies a parsed value onto ordinary prototypes so callers
+ * outside the codec (printing, deepEqual in tests) see normal objects.
+ *
+ * @param value - Value from parseStrictJson
+ * @returns Equivalent value with ordinary object prototypes
+ */
+function toPlainJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}

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

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Network classification shared by the FF1 LAN delivery paths (legacy
+ * plaintext casts in ff1-device.ts and the secure envelope transport in
+ * control/secure-transport.ts), so both apply the same retry and relayer
+ * fallback rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
+exports.isConnectPhaseNetworkError = isConnectPhaseNetworkError;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+/**
+ * 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));
+}
+// Codes that can only come from opening the connection (resolving the name,
+// routing, or a refused/timed-out TCP connect): the request bytes were never
+// written, so the FF1 cannot have run it.
+const CONNECT_PHASE_CODES = new Set([
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+// Codes that prove the same only when the failing call was the TCP connect.
+// macOS answers a connect to an absent LAN host with EHOSTDOWN (no ARP reply),
+// where Linux says EHOSTUNREACH.
+const CONNECT_SYSCALL_CODES = new Set(['ETIMEDOUT', 'EHOSTDOWN', 'ENETDOWN', 'EADDRNOTAVAIL']);
+/**
+ * isConnectPhaseNetworkError reports a send failure that proves the request
+ * never reached the FF1, so sending it again (even on another route, with a new
+ * counter) cannot run it twice. `fetch failed` on its own, ECONNRESET, a closed
+ * socket or a response timeout may follow a delivered request, and are not
+ * connect-phase (feral-file#3551 spec §14.4).
+ *
+ * @param {unknown} error - Error thrown by fetch
+ * @returns {boolean} True when the failure happened before any request byte was sent
+ */
+function isConnectPhaseNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const causes = [error, error.cause];
+    const cause = error.cause;
+    if (cause && Array.isArray(cause.errors)) {
+        // Happy-eyeballs connects report one error per address.
+        causes.push(...cause.errors);
+    }
+    return causes.some((candidate) => {
+        if (!candidate || typeof candidate !== 'object') {
+            return false;
+        }
+        const { code, syscall } = candidate;
+        if (typeof code !== 'string') {
+            return false;
+        }
+        return (CONNECT_PHASE_CODES.has(code) || (syscall === 'connect' && CONNECT_SYSCALL_CODES.has(code)));
+    });
+}
+/**
+ * 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;
+}

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

@@ -58,7 +58,7 @@ function applyPatch(existing, patch) {
  * 1. Same mDNS device ID → update in-place (preserves position, handles host change).
  * 2. Same host → update in-place (preserves position and metadata).
  * 3. Same name, different host → replace in-place (preserves position so that
- *    devices[0] — the implicit default for play/send/ssh — does not silently change).
+ *    devices[0] — the implicit default for display/send/ssh — does not silently change).
  * 4. Neither match → append.
  */
 function upsertDevice(existingDevices, newDevice, 

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.
  *