@feralfile/cli 2.0.2 → 2.1.0

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

@@ -48,16 +48,18 @@ function isInteractiveWeb(mimeType, sourceUrl) {
  *   - a time-based source (video/audio) gets NO duration and
  *     `display.loop: false`, so a conformant player MUST advance at
  *     end-of-stream — the media plays its natural length;
- *   - an interactive web page (HTML) gets NO duration either, but for the
- *     opposite reason: it has no end-of-stream event, so a conformant player
- *     parks on it indefinitely (the generative/interactive art keeps running);
+ *   - an interactive web page (HTML) — generative art with no intrinsic
+ *     runtime and no end-of-stream event — gets the configured
+ *     `generativeDuration` (default 60s) so the playlist rotates. Set
+ *     `generativeDuration` to 0 to omit it and have a conformant player park
+ *     on the work open-ended instead;
  *   - static and code-based sources fall back to the configured
  *     `defaultDuration` because they have no intrinsic runtime to play out.
  *
- * Do not re-introduce an unconditional duration here: stamping a default on
- * video items silently truncates or pads them, and stamping one on an HTML
- * page cuts the artwork off and restarts it every `defaultDuration` seconds
- * (the bugs this guards against).
+ * Do not stamp a duration on video/audio: it silently truncates or pads them.
+ * (Earlier this also omitted duration for HTML works, which left them with no
+ * duration field. Players that require the field — notably FF1 — then rejected
+ * the entire playlist, so generative works now carry an explicit duration.)
  *
  * @param {Object} item - DP1 playlist item (mutated in place)
  * @param {Object} mediaHints - Media signals for the time-based check
@@ -76,8 +78,13 @@ function applyItemTiming(item, mediaHints = {}, duration) {
         return item;
     }
     if (isInteractiveWeb(mediaHints.mimeType, mediaHints.sourceUrl)) {
-        // No duration: an open-ended interactive page should play until the
-        // playlist advances for another reason, not on a fixed timer.
+        // Generative/interactive works have no intrinsic runtime, so stamp the
+        // configured generative duration to drive playlist rotation. A configured
+        // value of 0 means "omit" — a conformant player then parks open-ended.
+        const generativeDuration = getGenerativeDuration();
+        if (generativeDuration > 0) {
+            item.duration = generativeDuration;
+        }
         return item;
     }
     item.duration = getDefaultStaticDuration();
@@ -98,6 +105,23 @@ function getDefaultStaticDuration() {
         return 10;
     }
 }
+/**
+ * getGenerativeDuration returns the configured display seconds for
+ * generative/interactive (HTML) works, which have no intrinsic runtime.
+ * Defaults to 60 when config is unavailable. A configured 0 is honored (the
+ * caller omits the duration so the work plays open-ended).
+ *
+ * @returns {number} Display duration in seconds (0 means "omit / open-ended")
+ */
+function getGenerativeDuration() {
+    try {
+        const configured = getConfig().generativeDuration;
+        return typeof configured === 'number' ? configured : 60;
+    }
+    catch (_error) {
+        return 60;
+    }
+}
 /**
  * Convert a string to a URL-friendly slug
  *
@@ -293,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');
@@ -313,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

@@ -22,8 +22,11 @@ npm run dev -- config show
 ## Top‑level fields
 
 - **defaultDuration** (number, seconds)
-  - Default per‑item display duration for media without an intrinsic runtime (images, code-based works). Falls back to 10s when unset.
+  - Default per‑item display duration for static media without an intrinsic runtime (images). Falls back to 10s when unset.
   - Does NOT apply to video/audio items: with no explicit duration those are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) — the media plays its natural length.
+- **generativeDuration** (number, seconds)
+  - Display duration stamped on generative/interactive (HTML) works, which have no intrinsic runtime and no end-of-stream event. Defaults to **60s** (override via `DEFAULT_GENERATIVE_DURATION`).
+  - Set to **0** to omit the duration entirely, so a conformant player parks on the work open-ended instead of rotating. Note: some players (including FF1) require every item to carry a `duration` and will reject a playlist whose items omit it — keep this non-zero unless you know your player tolerates an absent duration.
 
 ## browser
 
@@ -117,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.
@@ -124,15 +130,20 @@ 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 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.
 
@@ -161,6 +172,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:
@@ -204,6 +235,7 @@ Minimal `config.json` example (selected fields):
     "devices": [
       {
         "name": "Living Room Display",
+        "id": "FF1-ABCD1234",
         "host": "http://192.168.1.100:1111"
       }
     ]

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,9 @@ 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 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 +272,7 @@ 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
 
 # Remove a device by name
 ff-cli device remove kitchen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.0.2",
+  "version": "2.1.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",