@feralfile/cli 2.0.3 → 2.2.0

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

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopicHandoffReceiver = void 0;
+const handoff_crypto_1 = require("./handoff-crypto");
+const DEFAULT_HANDOFF_URL = 'https://handoff.feralfile.com';
+function brokerBaseUrl(value) {
+    return (value || process.env.FF1_HANDOFF_URL || DEFAULT_HANDOFF_URL).replace(/\/$/, '');
+}
+async function responseJson(response, operation) {
+    if (!response.ok) {
+        throw new Error(`${operation} failed with HTTP ${response.status}`);
+    }
+    return response.json();
+}
+function parseCreated(value) {
+    const record = value;
+    if (!record ||
+        typeof record.channelId !== 'string' ||
+        !record.channelId.startsWith('ch_') ||
+        typeof record.minterToken !== 'string' ||
+        typeof record.shortCode !== 'string' ||
+        !/^\d{6}$/.test(record.shortCode) ||
+        typeof record.expiresAt !== 'string') {
+        throw new Error('handoff channel response is invalid');
+    }
+    return record;
+}
+function parsePoll(value, channelId) {
+    const record = value;
+    if (record?.channelId !== channelId || !Array.isArray(record.messages)) {
+        throw new Error('handoff poll response is invalid');
+    }
+    return record;
+}
+function parseTopicPayload(value, channelId, expectedDeviceId) {
+    const payload = value;
+    if (payload?.v !== 1 ||
+        payload.type !== 'ff1_topic_handoff' ||
+        payload.channelId !== channelId ||
+        typeof payload.deviceId !== 'string' ||
+        payload.deviceId.trim().toUpperCase() !== expectedDeviceId.trim().toUpperCase() ||
+        typeof payload.topicId !== 'string' ||
+        payload.topicId.trim().length === 0 ||
+        typeof payload.sentAt !== 'string' ||
+        Number.isNaN(Date.parse(payload.sentAt))) {
+        throw new Error('received topic handoff does not match the selected FF1 device');
+    }
+    return payload;
+}
+/** One short-lived CLI-side channel waiting for a mobile topic transfer. */
+class TopicHandoffReceiver {
+    baseUrl;
+    channelId;
+    shortCode;
+    verificationCode;
+    expiresAt;
+    minterToken;
+    privateKey;
+    fetchFn;
+    constructor(baseUrl, channelId, shortCode, verificationCode, expiresAt, minterToken, privateKey, fetchFn) {
+        this.baseUrl = baseUrl;
+        this.channelId = channelId;
+        this.shortCode = shortCode;
+        this.verificationCode = verificationCode;
+        this.expiresAt = expiresAt;
+        this.minterToken = minterToken;
+        this.privateKey = privateKey;
+        this.fetchFn = fetchFn;
+    }
+    /** Ask the handoff broker for a one-time six-digit pairing channel. */
+    static async create(options = {}) {
+        const fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+        const baseUrl = brokerBaseUrl(options.baseUrl);
+        const keyPair = await (0, handoff_crypto_1.generateHandoffKeyPair)();
+        const publicKey = await (0, handoff_crypto_1.exportHandoffPublicJwk)(keyPair.publicKey);
+        const response = await fetchFn(new URL('/v1/channels', baseUrl), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                algorithm: handoff_crypto_1.HANDOFF_ALGORITHM,
+                minterPublicKeyJwk: publicKey,
+                idleTtlSeconds: 300,
+                shortCodeRequested: true,
+            }),
+        });
+        const created = parseCreated(await responseJson(response, 'handoff channel creation'));
+        const verificationCode = (0, handoff_crypto_1.handoffVerificationCode)({
+            channelId: created.channelId,
+            minterPublicKeyJwk: publicKey,
+        });
+        return new TopicHandoffReceiver(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) {
+        const deadline = Date.now() + (options.maxWaitMs ?? 300_000);
+        let afterSeq = 0;
+        while (Date.now() <= deadline) {
+            const url = new URL(`/v1/channels/${encodeURIComponent(this.channelId)}/messages`, this.baseUrl);
+            url.searchParams.set('afterSeq', String(afterSeq));
+            const response = await this.fetchFn(url, {
+                headers: { Authorization: `Bearer ${this.minterToken}` },
+            });
+            const poll = parsePoll(await responseJson(response, 'handoff poll'), this.channelId);
+            for (const message of poll.messages) {
+                afterSeq = Math.max(afterSeq, message.seq);
+                if (message.sender !== 'browser' ||
+                    message.recipient !== 'minter' ||
+                    !message.senderPublicKeyJwk) {
+                    continue;
+                }
+                const plaintext = await (0, handoff_crypto_1.decryptHandoffMessage)({
+                    privateKey: this.privateKey,
+                    peerPublicKeyJwk: message.senderPublicKeyJwk,
+                    channelId: this.channelId,
+                    seq: message.seq,
+                    message,
+                });
+                return parseTopicPayload(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');
+    }
+    /** Close the broker channel and invalidate its participant credentials. */
+    async close() {
+        const response = await this.fetchFn(new URL(`/v1/channels/${encodeURIComponent(this.channelId)}`, this.baseUrl), {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${this.minterToken}` },
+        });
+        if (!response.ok && response.status !== 404 && response.status !== 410) {
+            throw new Error(`handoff channel close failed with HTTP ${response.status}`);
+        }
+    }
+}
+exports.TopicHandoffReceiver = TopicHandoffReceiver;

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

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFF_ALGORITHM = void 0;
+exports.canonicalJson = canonicalJson;
+exports.handoffVerificationCode = handoffVerificationCode;
+exports.generateHandoffKeyPair = generateHandoffKeyPair;
+exports.exportHandoffPublicJwk = exportHandoffPublicJwk;
+exports.encryptHandoffMessage = encryptHandoffMessage;
+exports.decryptHandoffMessage = decryptHandoffMessage;
+exports.randomHandoffMessageId = randomHandoffMessageId;
+const node_crypto_1 = require("node:crypto");
+/** Wire algorithm required by the handoff broker protocol. */
+exports.HANDOFF_ALGORITHM = 'P256-HKDF-SHA256-AES-256-GCM';
+/** canonicalJson serializes JSON with recursively sorted object keys. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+        .join(',')}}`;
+}
+/** Create the out-of-band key commitment shown by both CLI and mobile. */
+function handoffVerificationCode(input) {
+    const commitment = (0, node_crypto_1.createHash)('sha256')
+        .update(canonicalJson({
+        v: 1,
+        algorithm: exports.HANDOFF_ALGORITHM,
+        channelId: input.channelId,
+        minterPublicKeyJwk: input.minterPublicKeyJwk,
+    }))
+        .digest('hex')
+        .slice(0, 12)
+        .toUpperCase();
+    return `${commitment.slice(0, 4)}-${commitment.slice(4, 8)}-${commitment.slice(8, 12)}`;
+}
+/** Generate an ephemeral P-256 ECDH key pair for one broker channel. */
+async function generateHandoffKeyPair() {
+    return (await node_crypto_1.webcrypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, [
+        'deriveBits',
+    ]));
+}
+/** Export the public half of an ephemeral handoff key as JWK. */
+async function exportHandoffPublicJwk(publicKey) {
+    return node_crypto_1.webcrypto.subtle.exportKey('jwk', publicKey);
+}
+function base64UrlEncode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+function base64UrlDecode(value) {
+    return new Uint8Array(Buffer.from(value, 'base64url'));
+}
+function handoffAAD(input) {
+    return {
+        v: 1,
+        channelId: input.channelId,
+        messageId: input.messageId,
+        seq: input.seq,
+        sender: input.sender,
+        recipient: input.recipient,
+        algorithm: exports.HANDOFF_ALGORITHM,
+    };
+}
+async function deriveAesKey(input) {
+    const peer = await node_crypto_1.webcrypto.subtle.importKey('jwk', input.peerPublicKeyJwk, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+    const sharedBits = await node_crypto_1.webcrypto.subtle.deriveBits({ name: 'ECDH', public: peer }, input.privateKey, 256);
+    const hkdfKey = await node_crypto_1.webcrypto.subtle.importKey('raw', sharedBits, 'HKDF', false, ['deriveKey']);
+    const saltInput = canonicalJson({
+        algorithm: exports.HANDOFF_ALGORITHM,
+        channelId: input.channelId,
+        v: 1,
+    });
+    const salt = await node_crypto_1.webcrypto.subtle.digest('SHA-256', Buffer.from(saltInput));
+    return node_crypto_1.webcrypto.subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt,
+        info: Buffer.from('ff-mint-pairing/v1/aes-gcm'),
+    }, hkdfKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+/** Encrypt a JSON payload into the broker's authenticated envelope format. */
+async function encryptHandoffMessage(input) {
+    const aad = handoffAAD({ ...input, seq: 0 });
+    const aadBytes = Buffer.from(canonicalJson(aad));
+    const nonce = (0, node_crypto_1.randomBytes)(12);
+    const key = await deriveAesKey(input);
+    const ciphertext = await node_crypto_1.webcrypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce, additionalData: aadBytes, tagLength: 128 }, key, Buffer.from(canonicalJson(input.plaintext)));
+    return {
+        messageId: input.messageId,
+        sender: input.sender,
+        recipient: input.recipient,
+        algorithm: exports.HANDOFF_ALGORITHM,
+        aad: base64UrlEncode(aadBytes),
+        nonce: base64UrlEncode(nonce),
+        ciphertext: base64UrlEncode(new Uint8Array(ciphertext)),
+        ...(input.senderPublicKeyJwk ? { senderPublicKeyJwk: input.senderPublicKeyJwk } : {}),
+    };
+}
+/** Decrypt and validate one channel-bound broker message. */
+async function decryptHandoffMessage(input) {
+    const { message } = input;
+    if (message.algorithm !== exports.HANDOFF_ALGORITHM) {
+        throw new Error('encrypted message algorithm mismatch');
+    }
+    const aadBytes = base64UrlDecode(message.aad);
+    const aad = JSON.parse(Buffer.from(aadBytes).toString('utf8'));
+    const valid = aad.v === 1 &&
+        aad.channelId === input.channelId &&
+        aad.messageId === message.messageId &&
+        aad.sender === message.sender &&
+        aad.recipient === message.recipient &&
+        aad.algorithm === exports.HANDOFF_ALGORITHM &&
+        (aad.seq === 0 || aad.seq === input.seq);
+    if (!valid) {
+        throw new Error('encrypted message channel binding mismatch');
+    }
+    const nonce = base64UrlDecode(message.nonce);
+    if (nonce.length !== 12) {
+        throw new Error('AES-GCM nonce must be 12 bytes');
+    }
+    const key = await deriveAesKey(input);
+    const plaintext = await node_crypto_1.webcrypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce, additionalData: aadBytes, tagLength: 128 }, key, base64UrlDecode(message.ciphertext));
+    return JSON.parse(Buffer.from(plaintext).toString('utf8'));
+}
+/** Create a collision-resistant broker message identifier. */
+function randomHandoffMessageId() {
+    return `msg_${(0, node_crypto_1.randomBytes)(16).toString('base64url')}`;
+}

package/dist/src/utilities/index.js

@@ -487,7 +487,7 @@ async function buildPlaylistDirect(params, options = {}) {
         console.log(chalk.cyan('Shuffling items...'));
         finalItems = shuffleArray([...allItems]);
     }
-    console.log(chalk.cyan(`Creating playlist with ${finalItems.length} items...`));
+    console.log(chalk.cyan(`Creating playlist with ${finalItems.length} ${finalItems.length === 1 ? 'item' : 'items'}...`));
     // Build DP1 playlist
     const playlist = await buildDP1Playlist(finalItems, playlistSettings.title, playlistSettings.slug);
     // Save playlist to file

package/dist/src/utilities/playlist-builder.js

@@ -317,7 +317,7 @@ function convertTokensToDP1Items(tokensInfo, duration) {
  */
 function generatePlaylistTitle(items) {
     if (!items || items.length === 0) {
-        return 'DP1 Playlist';
+        return 'DP-1 Playlist';
     }
     // Check if all items have provenance (likely NFT playlist)
     const hasProvenance = items.some((item) => item.provenance?.type === 'onChain');
@@ -337,7 +337,7 @@ function generatePlaylistTitle(items) {
         }
     }
     // Fallback: use item count
-    return `DP1 Playlist (${items.length} ${items.length === 1 ? 'item' : 'items'})`;
+    return `DP-1 Playlist (${items.length} ${items.length === 1 ? 'item' : 'items'})`;
 }
 /**
  * Build complete DP1 v1.0.0 compliant playlist

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

@@ -86,11 +86,7 @@ async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds
                 details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
             };
         }
-        let apiUrl = `${device.host}/api/cast`;
-        if (device.topicID && device.topicID.trim() !== '') {
-            apiUrl += `?topicID=${encodeURIComponent(device.topicID)}`;
-            logger.debug(`Using topicID: ${device.topicID}`);
-        }
+        const apiUrl = `${device.host}/api/cast`;
         const request = {
             enabled,
         };

package/dist/src/utilities/topic-store.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topicStoreAccount = topicStoreAccount;
+exports.storeTopicId = storeTopicId;
+exports.getTopicId = getTopicId;
+exports.deleteTopicId = deleteTopicId;
+const keyring_1 = require("@napi-rs/keyring");
+const TOPIC_STORE_SERVICE = 'com.feralfile.ff-cli.topic';
+const defaultEntryFactory = (service, account) => new keyring_1.Entry(service, account);
+/** Normalize a physical FF1 identifier into its one keyring account name. */
+function topicStoreAccount(deviceId) {
+    const normalized = deviceId.trim().toUpperCase();
+    if (!normalized) {
+        throw new Error('FF1 device ID is required for secure topic storage');
+    }
+    return normalized;
+}
+/** Store a device topic in the operating system credential vault. */
+function storeTopicId(deviceId, topicId, entryFactory = defaultEntryFactory) {
+    const normalizedTopic = topicId.trim();
+    if (!normalizedTopic) {
+        throw new Error('FF1 topic ID is required for secure topic storage');
+    }
+    entryFactory(TOPIC_STORE_SERVICE, topicStoreAccount(deviceId)).setPassword(normalizedTopic);
+}
+/** Read a device topic from the operating system credential vault. */
+function getTopicId(deviceId, entryFactory = defaultEntryFactory) {
+    return entryFactory(TOPIC_STORE_SERVICE, topicStoreAccount(deviceId)).getPassword();
+}
+/** Delete a device topic from the operating system credential vault. */
+function deleteTopicId(deviceId, entryFactory = defaultEntryFactory) {
+    return entryFactory(TOPIC_STORE_SERVICE, topicStoreAccount(deviceId)).deletePassword();
+}

package/docs/CONFIGURATION.md

@@ -120,6 +120,9 @@ Configure devices you want to play content on.
 
 - `ff1Devices.devices` (array of objects):
   - `name` (string): Friendly device label. Free‑form; pick anything memorable.
+  - `id` (string): Stable physical ID discovered from FF1 (for example
+    `FF1-SKYZ2E3A`). Relayer pairing stores the topic under this ID in the OS
+    credential vault.
   - `host` (string): Device base URL. For LAN devices, use `http://<ip>:1111`. The device typically listens on port `1111`.
 
 During `ff-cli setup`, the CLI will attempt local discovery via mDNS (`_ff1._tcp`). If devices are found, you can pick one and the host will be filled in automatically. If discovery returns nothing, setup falls back to manual entry.
@@ -127,15 +130,21 @@ During `ff-cli setup`, the CLI will attempt local discovery via mDNS (`_ff1._tcp
 > **mDNS is best-effort.** It frequently does not cross subnets — a common case with mesh routers (e.g. eero) that put wired and Wi-Fi clients on different `/24`s. If discovery comes up empty even though the device is reachable by IP, skip it entirely and add the device directly:
 >
 > ```bash
-> ff-cli device add --host http://<device-ip>:1111 --name <name>
+> ff-cli device add --host http://<device-ip>:1111 --name <name> --id FF1-XXXXXXXX
 > ```
 
 You can also manage devices independently with:
 
-- `ff-cli device add` – Add a device interactively (with mDNS discovery), or non-interactively with `--host` and `--name`.
+- `ff-cli device add` – Add a device interactively (with mDNS discovery), or
+  non-interactively with `--host`, `--name`, and the physical `--id` shown in
+  Feral File mobile. Manual devices need the ID before relayer pairing.
 - `ff-cli device list` – Show all configured devices.
+- `ff-cli device rename <name> <new-name>` – Rename a device without touching its host, API key, or default status. Works offline; also accepts the host URL as the identifier, so unnamed legacy entries can be given a name.
 - `ff-cli device remove <name>` – Remove a device by name.
 - `ff-cli device default <name>` – Promote a device to the top of the list so it is used when `-d` is omitted.
+- `ff-cli device pair [name]` – Display a one-time handoff code and key-bound
+  security check, then securely receive that device's relayer topic from Feral
+  File mobile. Confirm both values match before approving in mobile.
 
 Setup and `device add` both preserve existing devices. Adding a device with the same host as an existing one updates it in place.
 
@@ -164,6 +173,26 @@ Content-Type: application/json
 
 The `intent` field is **required** — without it the device returns `{"message":{"ok":false}}` with no further explanation. `dp1_call` may be the playlist inline (as above) or a hosted playlist URL string; ff-cli sends the resolved playlist object.
 
+When LAN delivery is unreachable, `play` prints an explicit notice and retries
+the same command through `ff1Relayer.baseUrl`. The per-device topic is read from
+the operating system credential vault, never `config.json`. Pair it from the
+mobile app first:
+
+```bash
+ff-cli device pair office
+```
+
+The CLI and mobile confirmation both show the same 12-hex-digit security check.
+Comparing it authenticates the CLI public key out of band, so an active broker
+cannot silently substitute its own encryption key.
+
+The default relayer is
+`https://tv-cast-coordination.autonomy-system.workers.dev`. Override it with
+`ff1Relayer.baseUrl` or `FF1_RELAYER_URL`. Signed topic-only relayer deployments
+need no additional key. Deployments that retain the cloud-edge compatibility
+gate may receive `ff1Relayer.apiKey` or `FF1_RELAYER_API_KEY`; ff-cli never
+bundles that shared key.
+
 On the first cast after boot the device may return an empty body. ff-cli retries this automatically and, if it persists, reports a clear "accepted the request but returned no usable response" error rather than crashing on a JSON parse.
 
 Compatibility checks:
@@ -207,6 +236,7 @@ Minimal `config.json` example (selected fields):
     "devices": [
       {
         "name": "Living Room Display",
+        "id": "FF1-ABCD1234",
         "host": "http://192.168.1.100:1111"
       }
     ]

package/docs/EXAMPLES.md

@@ -385,6 +385,9 @@ npm run dev -- device add
 # Add a device non-interactively
 npm run dev -- device add --host 192.168.1.100 --name kitchen
 
+# Rename a device (host, API key, and default status are untouched)
+npm run dev -- device rename kitchen gallery
+
 # Remove a device by name
 npm run dev -- device remove kitchen
 

package/docs/PROJECT_SPEC.md

@@ -110,6 +110,12 @@ Based on the code today, the CLI is responsible for:
 - signing playlists when a private key is configured
 - publishing validated playlists to configured feed servers
 - discovering configured FF1 devices and sending playlists or direct media playback requests
+- pairing a device's signed relayer topic through a short-lived end-to-end
+  encrypted mobile handoff, authenticating the CLI key with a user-compared
+  security check, and storing it in the operating system credential vault
+- falling back from unreachable LAN delivery to the shared FF1 relayer with an
+  explicit terminal notice, so sandboxed and cross-subnet control remains
+  observable to the mobile app
 - performing FF1 OS compatibility preflight checks before display and SSH flows
 
 ## Architecture boundaries

package/docs/README.md

@@ -117,8 +117,10 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
   - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
 - `device list` – List all configured FF1 devices
-- `device add` – Add a new FF1 device (with mDNS discovery)
-  - Options: `--host <host>`, `--name <name>`
+- `device add` – Add a device with mDNS or manual `--host`, `--name`, and `--id`
+  - Options: `--host <host>`, `--name <name>`, `--id <id>`
+- `device pair [name]` – Securely receive relayer access from Feral File mobile
+- `device rename <name> <new-name>` – Rename a configured FF1 device (host, API key, and default status are untouched)
 - `device remove <name>` – Remove a configured FF1 device
 - `device default <name>` – Set the default FF1 device (used when `-d` is omitted)
 - `config <init|show|validate>` – Manage configuration
@@ -271,7 +273,10 @@ ff-cli device list
 ff-cli device add
 
 # Add a device non-interactively
-ff-cli device add --host 192.168.1.100 --name kitchen
+ff-cli device add --host 192.168.1.100 --name kitchen --id FF1-XXXXXXXX
+
+# Rename a device (host, API key, and default status are untouched)
+ff-cli device rename kitchen gallery
 
 # Remove a device by name
 ff-cli device remove kitchen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
@@ -32,7 +32,8 @@
     "start": "node dist/index.js",
     "dev": "tsx index.ts",
     "smoke": "npm run build && node dist/index.js validate examples/sample-playlist-v11.json && node dist/index.js config validate",
-    "check": "npm run format:check && npm run lint && npm run test",
+    "check": "npm run format:check && npm run lint && npm run check:copy && npm run test",
+    "check:copy": "node scripts/check-copy.js",
     "verify": "npm run check && npm run smoke",
     "prepublishOnly": "npm run verify",
     "test": "node scripts/run-tests.js",
@@ -57,6 +58,8 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@napi-rs/keyring": "1.3.0",
+    "@feralfile/source-resolver": "git+https://github.com/feral-file/ff-source-resolver.git#54be943014c8cf7860114510257cdd713bbf4e79",
     "axios": "^1.6.2",
     "bonjour-service": "^1.3.0",
     "chalk": "^4.1.2",