@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/utilities/ssh-access.js

@@ -1,6 +1,24 @@
 "use strict";
 /**
  * SSH access control for FF1 devices.
+ *
+ * The sshAccess command is LAN-only: it is POSTed straight to the device's
+ * `/api/cast` endpoint and never falls back to the relayer.
+ *
+ * Topic proof (feral-file#3551 phase 0): on a claimed FF1, newer FF OS rejects
+ * a LAN `sshAccess` (and `connect`) cast unless it carries the relayer topic in
+ * the `X-FF1-Topic` header, answering HTTP 401 `{"error":{"code":"topic_required"}}`.
+ * The topic is the secret that `ff-cli device pair` stores in the OS keyring;
+ * holding it proves the CLI was paired by the owner through the mobile app.
+ * Older firmware and unclaimed devices ignore the header, so the request is
+ * still sent without it when no topic is stored. The topic value must never be
+ * logged or placed in an error message.
+ *
+ * Secure control (feral-file#3551 M6): when ff-cli holds a controller file for
+ * the device, `sshAccess` is sent as an ff1-control-v1 envelope instead, still
+ * LAN-only. `sshAccess` is owner tier, so a controller-role grant gets
+ * `permission_denied`, mapped to "needs an owner grant". No topic header is
+ * sent on that path: the signed envelope is the proof.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -36,25 +54,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FF1_TOPIC_HEADER = void 0;
 exports.sendSshAccessCommand = sendSshAccessCommand;
 const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const ff1_compatibility_1 = require("./ff1-compatibility");
+const topic_store_1 = require("./topic-store");
+const secure_transport_1 = require("./control/secure-transport");
+/** FF1_TOPIC_HEADER is the LAN cast header that carries the relayer topic proof. */
+exports.FF1_TOPIC_HEADER = 'X-FF1-Topic';
+/** TOPIC_REQUIRED_CODE is the device error code for a missing or wrong topic proof. */
+const TOPIC_REQUIRED_CODE = 'topic_required';
 /**
- * Send an SSH access command to an FF1 device.
+ * sendSshAccessCommand sends an SSH access command to an FF1 device over the LAN.
  *
  * @param {Object} params - Function parameters
  * @param {boolean} params.enabled - Whether to enable SSH access
  * @param {string} [params.deviceName] - Device name to target (defaults to first configured)
  * @param {string} [params.publicKey] - SSH public key to authorize (required for enable)
  * @param {number} [params.ttlSeconds] - Time-to-live in seconds for auto-disable
- * @returns {Promise<Object>} Result object
- * @returns {boolean} returns.success - Whether the command succeeded
- * @returns {string} [returns.device] - Device host used
- * @returns {string} [returns.deviceName] - Device name used
- * @returns {Object} [returns.response] - Response from device
- * @returns {string} [returns.error] - Error message if failed
- * @throws {Error} When device configuration is invalid or missing
+ * @param {SshAccessDependencies} [overrides] - Optional fetch, topic-store, and config seams
+ * @returns {Promise<SshAccessResult>} Result object; never throws. A device that
+ *   demands topic proof yields `success: false` with an actionable pairing error.
  * @example
  * // Enable SSH for 30 minutes
  * const result = await sendSshAccessCommand({
@@ -63,15 +84,15 @@ const ff1_compatibility_1 = require("./ff1-compatibility");
  *   ttlSeconds: 1800,
  * });
  */
-async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds, }) {
+async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds }, overrides = {}) {
+    const fetchFn = overrides.fetchFn ?? ((input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}));
     try {
         if (enabled && (!publicKey || !publicKey.trim())) {
-            return {
-                success: false,
-                error: 'Public key is required to enable SSH access',
-            };
+            return { success: false, error: 'Public key is required to enable SSH access' };
         }
-        const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName);
+        const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName, {
+            getFF1DeviceConfigFn: overrides.getFF1DeviceConfigFn,
+        });
         if (!resolved.success || !resolved.device) {
             return {
                 success: false,
@@ -79,64 +100,177 @@ async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds
             };
         }
         const device = resolved.device;
-        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'sshAccess');
+        const secure = (0, secure_transport_1.findSecureController)(device, overrides.controllerStore);
+        if (secure.failure) {
+            return { success: false, error: secure.failure.error, details: secure.failure.details };
+        }
+        const secureDeps = {
+            fetchFn: overrides.fetchFn,
+            getTopicIdFn: overrides.getTopicIdFn,
+            controllerStore: overrides.controllerStore,
+            nowFn: overrides.nowFn,
+        };
+        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'sshAccess', {
+            fetchFn: overrides.fetchFn,
+            controller: secure.record ? { record: secure.record, deps: secureDeps } : undefined,
+        });
         if (!compatibility.compatible) {
             return {
                 success: false,
                 error: compatibility.error || 'FF1 OS does not support SSH access command',
-                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
+                details: compatibility.details ??
+                    (compatibility.version ? `Detected version ${compatibility.version}` : undefined),
             };
         }
-        const apiUrl = `${device.host}/api/cast`;
-        const request = {
-            enabled,
-        };
-        if (publicKey && publicKey.trim()) {
-            request.publicKey = publicKey.trim();
-        }
-        if (typeof ttlSeconds === 'number') {
-            request.ttlSeconds = ttlSeconds;
-        }
-        const requestBody = {
-            command: 'sshAccess',
-            request,
-        };
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        if (device.apiKey) {
-            headers['API-KEY'] = device.apiKey;
+        const body = buildSshAccessBody(enabled, publicKey, ttlSeconds);
+        if (secure.record) {
+            return await sendSshAccessSecurely(device, secure.record, body.request, secureDeps);
         }
-        const response = await (0, http_1.fetchWithTimeout)(apiUrl, {
+        const topicId = lookupTopicId(device, overrides.getTopicIdFn ?? topic_store_1.getTopicId);
+        const response = await fetchFn(`${device.host}/api/cast`, {
             method: 'POST',
-            headers,
-            body: JSON.stringify(requestBody),
+            headers: buildSshAccessHeaders(device, topicId),
+            body: JSON.stringify(body),
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            logger.error(`SSH access request failed: ${response.status} ${response.statusText}`);
-            logger.debug(`Error details: ${errorText}`);
-            return {
-                success: false,
-                error: `Device returned error ${response.status}: ${response.statusText}`,
-                details: errorText,
-            };
-        }
-        const responseData = (await response.json());
-        logger.info('SSH access command succeeded');
-        logger.debug(`Device response: ${JSON.stringify(responseData)}`);
-        return {
-            success: true,
-            device: device.host,
-            deviceName: device.name || device.host,
-            response: responseData,
-        };
+        return await interpretSshAccessResponse(device, response);
     }
     catch (error) {
         logger.error(`Error sending SSH access command: ${error.message}`);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * sendSshAccessSecurely sends `sshAccess` as a secure envelope over the LAN
+ * (no retry and no relayer fallback, matching the plaintext path).
+ *
+ * @param device - Device with a controller record
+ * @param record - Enrolled controller record
+ * @param request - The unchanged sshAccess request object
+ * @param deps - Transport seams
+ * @returns SSH access result
+ */
+async function sendSshAccessSecurely(device, record, request, deps) {
+    const result = await (0, secure_transport_1.runSecureCommand)({
+        device: device,
+        record,
+        cmd: 'sshAccess',
+        req: request,
+        relayerFallback: false,
+        retry: false,
+    }, deps);
+    if (!result.success) {
+        logger.error(`SSH access request failed: ${result.error}`);
+        return { success: false, error: result.error, details: result.details };
+    }
+    logger.info('SSH access command succeeded');
+    return {
+        success: true,
+        device: device.host,
+        deviceName: device.name || device.host,
+        response: result.response,
+    };
+}
+/**
+ * lookupTopicId reads the stored relayer topic for a device, or null.
+ *
+ * A missing device ID, a missing topic, or an unavailable keyring all degrade
+ * to "send without the header": unclaimed devices and older firmware accept
+ * that, and a device that does require proof answers 401 topic_required, which
+ * is mapped to the pairing guidance. Failing hard here would break SSH on every
+ * device the header is irrelevant to.
+ */
+function lookupTopicId(device, getTopicIdFn) {
+    if (!device.id) {
+        return null;
+    }
+    try {
+        return getTopicIdFn(device.id);
+    }
+    catch (error) {
+        logger.debug(`Secure topic storage unavailable: ${error.message}`);
+        return null;
+    }
+}
+/** buildSshAccessHeaders returns the cast headers, adding topic proof only when known. */
+function buildSshAccessHeaders(device, topicId) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (device.apiKey) {
+        headers['API-KEY'] = device.apiKey;
+    }
+    if (topicId) {
+        headers[exports.FF1_TOPIC_HEADER] = topicId;
+    }
+    return headers;
+}
+/** buildSshAccessBody returns the `sshAccess` cast body. */
+function buildSshAccessBody(enabled, publicKey, ttlSeconds) {
+    const request = { enabled };
+    if (publicKey && publicKey.trim()) {
+        request.publicKey = publicKey.trim();
+    }
+    if (typeof ttlSeconds === 'number') {
+        request.ttlSeconds = ttlSeconds;
+    }
+    return { command: 'sshAccess', request };
+}
+/** interpretSshAccessResponse maps the device HTTP response onto an SshAccessResult. */
+async function interpretSshAccessResponse(device, response) {
+    if (!response.ok) {
+        const errorText = await response.text();
+        logger.error(`SSH access request failed: ${response.status} ${response.statusText}`);
+        logger.debug(`Error details: ${errorText}`);
+        if (isTopicRequired(response.status, errorText)) {
+            return { success: false, error: topicRequiredMessage(device), details: errorText };
+        }
         return {
             success: false,
-            error: error.message,
+            error: `Device returned error ${response.status}: ${response.statusText}`,
+            details: errorText,
         };
     }
+    const responseData = (await response.json());
+    logger.info('SSH access command succeeded');
+    logger.debug(`Device response: ${JSON.stringify(responseData)}`);
+    return {
+        success: true,
+        device: device.host,
+        deviceName: device.name || device.host,
+        response: responseData,
+    };
+}
+/** isTopicRequired reports whether a device rejection is the topic-proof 401. */
+function isTopicRequired(status, body) {
+    if (status !== 401) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        return parsed?.error?.code === TOPIC_REQUIRED_CODE;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * topicRequiredMessage tells the user how to pair the CLI for this device.
+ *
+ * The same guidance covers "never paired" and "stored topic is stale" (the
+ * device rotated its topic): pairing again replaces the keyring entry. A device
+ * without a stable ID cannot be paired, so it is told to re-add first.
+ */
+function topicRequiredMessage(device) {
+    const label = device.name || device.host;
+    const pairCommand = `ff-cli device pair ${quoteArg(label)}`;
+    const base = `This FF1 requires ff-cli to be paired before SSH access can be changed.`;
+    // Securing first makes the pairing an owner grant, which keeps working once
+    // the FF1 no longer has a relayer topic (feral-file#3551 relay v2).
+    const secure = `In the Feral File app, choose "Secure this FF1" for this device if it is offered`;
+    if (!device.id) {
+        return `${base} Re-add the device with its ID (ff-cli device add --id <FF1 device ID>). ${secure}, then run \`${pairCommand}\` and choose "Pair with ff-cli".`;
+    }
+    return `${base} ${secure}, then run \`${pairCommand}\` and choose "Pair with ff-cli", then retry.`;
+}
+/** quoteArg double-quotes a shell argument that contains whitespace or quotes. */
+function quoteArg(value) {
+    return /[\s"'$`\\]/.test(value) ? JSON.stringify(value) : value;
 }