@feralfile/cli 2.9.0 → 2.10.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.9.0",
+    "version": "2.10.1",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",
@@ -65,7 +65,7 @@
         "chalk": "^4.1.2",
         "commander": "^11.1.0",
         "dotenv": "^16.3.1",
-        "dp1-js": "2.3.1",
+        "dp1-js": "2.4.1",
         "ff1": "^1.0.0",
         "fuzzysort": "^3.1.0",
         "viem": "^2.56.3"

package/dist/src/commands/config.js

@@ -26,11 +26,18 @@ exports.configCommand = new commander_1.Command('config')
             const config = (0, config_1.getConfig)();
             console.log(chalk_1.default.blue('\nCurrent configuration\n'));
             console.log(chalk_1.default.bold('Default duration:'), chalk_1.default.white(config.defaultDuration + 's'));
-            const feedServers = config.feedServers || [];
-            if (feedServers.length > 0) {
-                console.log(chalk_1.default.bold('\nFeed servers:\n'));
-                feedServers.forEach((server) => {
-                    console.log(`  ${chalk_1.default.dim(server.baseUrl)}`);
+            // The effective list, numbered. `-s <index>` on publish, fetch, replace
+            // and unpublish is an index into exactly this list — whichever of
+            // config.feedServers, the legacy feed.baseURLs, FEED_BASE_URLS, or the
+            // built-in default supplied it — so this is the one place an operator
+            // or an agent can read the number off before a write. Printing only
+            // config.feedServers, unnumbered, left the index undiscoverable for
+            // every other source.
+            const { baseURLs } = (0, config_1.getFeedConfig)();
+            if (baseURLs.length > 0) {
+                console.log(chalk_1.default.bold('\nFeed servers (index for -s):\n'));
+                baseURLs.forEach((url, index) => {
+                    console.log(`  ${chalk_1.default.bold(String(index))}: ${chalk_1.default.dim(url)}`);
                 });
             }
             const devices = config.ff1Devices?.devices || [];

package/dist/src/commands/enrich.js

@@ -40,31 +40,62 @@ const { resolveTokenBatch } = require('../utilities/nft-indexer');
  * function's rename semantics, and pairing it with the wrong predicate is a
  * mistake that has already been made once.
  */
-async function writePlaylistAtomically(destination, contents, expectedDigest) {
+async function writePlaylistAtomically(destination, contents, expectedDigest, filesystem = fs_1.promises) {
     // Follow a symlink to its target before replacing anything. rename() would
     // replace the link itself, silently detaching a playlist that other paths
     // reach through that name while reporting success.
     let target = destination;
-    const existing = await fs_1.promises.lstat(destination).catch(() => null);
+    const existing = await filesystem.lstat(destination).catch(() => null);
     if (existing?.isSymbolicLink()) {
-        target = await fs_1.promises.realpath(destination);
+        target = await filesystem.realpath(destination);
     }
     const temporary = (0, path_1.join)((0, path_1.dirname)(target), `.${(0, path_1.basename)(target)}.${process.pid}.${(0, crypto_1.randomBytes)(4).toString('hex')}.tmp`);
+    // What a replacement preserves, and what it cannot.
+    //
+    // Preserved: the permission mode — applied before the file holds anything,
+    // then restored and verified against the inode after each of the two things
+    // that clear set-user-ID and set-group-ID, which are the chown and the write
+    // itself — and the owner and group, where a failed chown refuses the
+    // replacement outright. Those are what decide access for a file whose
+    // permissions are described by mode bits alone, which is the common case.
+    // Where any of it cannot be reproduced the write is refused rather than
+    // completed with different access.
+    //
+    // NOT preserved: access-control lists. A replacement is a new inode, and a
+    // new inode's ACL comes from the directory's default ACL, not from the file
+    // being replaced — so named entries granting or denying specific users and
+    // groups are gone, and whatever the directory hands out is there instead.
+    // Mode bits cannot carry them across, because mode bits cannot describe a
+    // named entry at all: on Linux the group bits are the POSIX mask rather than
+    // the group's own permissions, macOS extended ACLs are evaluated ahead of the
+    // mode and ignore the mask entirely, and Windows ACLs are not mode bits in
+    // any sense. Node exposes no portable way to read an ACL, let alone reapply
+    // one, so this is a limit of the replacement strategy and not an oversight
+    // that a few more syscalls would close. Reading the mode and finding it
+    // unchanged proves nothing about whether access widened or narrowed.
+    //
+    // What to do when it matters: enrich to a fresh name with `--output`, in a
+    // directory whose access is what you want the result to have. That is a
+    // create rather than a replace, so nothing is silently reassigned — the new
+    // file simply has the access its directory gives it, visibly.
+    //
     // The destination's mode has to be known before the file exists, not after
     // it holds the contents. Creating at the default 0o666-minus-umask and
     // chmod'ing afterwards leaves the enriched playlist readable by other local
     // users for the length of the write — short, but a disclosure window on a
     // file the curator deliberately restricted.
-    const current = await fs_1.promises.stat(target).catch(() => null);
+    const current = await filesystem.stat(target).catch(() => null);
     const mode = current ? current.mode & 0o7777 : undefined;
     try {
         // 'wx' fails rather than truncating if the name somehow exists, so a
         // collision can never destroy another process's work in progress.
-        const handle = await fs_1.promises.open(temporary, 'wx', mode);
+        const handle = await filesystem.open(temporary, 'wx', mode);
         try {
             // open() applies the mode through umask, which can strip bits the
             // destination had. chmod is not subject to umask, so this restores the
-            // exact mode — still before any bytes are written.
+            // exact mode — still before any bytes are written. It runs here, before
+            // the chown below, so the disclosure window stays closed even though
+            // chown will undo part of it.
             if (mode !== undefined) {
                 await handle.chmod(mode);
             }
@@ -88,11 +119,43 @@ async function writePlaylistAtomically(destination, contents, expectedDigest) {
                     await handle.chown(current.uid, current.gid);
                 }
                 catch {
-                    await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
-                    throw new OwnershipError(target);
+                    await filesystem.rm(temporary, { force: true }).catch(() => undefined);
+                    throw new OwnershipError(target, 'ownership');
                 }
+                // chown clears set-user-ID and set-group-ID. POSIX requires it of any
+                // chown by a process without appropriate privileges, and Linux does it
+                // for an executable regardless — the whole point is that a setuid file
+                // must not survive changing hands, since it would then run as its new
+                // owner. Correct in general, and wrong for this one case: the file is
+                // not changing hands, it is being restored to the hands it was already
+                // in. The restore happens just below, in the same step that verifies
+                // it.
             }
+            // Verify against the inode rather than trusting the calls above.
+            //
+            // Both chmod calls can report success and still leave a different mode:
+            // restoring set-group-ID needs the caller to be in the file's group, and
+            // a filesystem may decline the bit outright. Every one of those endings
+            // is the same fact — this replacement would not carry the access the
+            // original had — and the whole reason the ownership branch refuses is
+            // that completing such a write silently is worse than not writing.
+            //
+            // Checked here so a refusal costs nothing already on disk, and again
+            // after the write below, which can undo it.
+            await requirePreservedMode(handle, mode, temporary, target, filesystem);
             await handle.writeFile(contents);
+            // Write clears set-user-ID and set-group-ID too, for the same reason
+            // chown does: POSIX permits it on any write to a regular file by a
+            // process without appropriate privileges, and Linux does it. So the
+            // check above was necessary and not sufficient — a mode that passed it
+            // could still be renamed into place as 0o0750 where the original was
+            // 0o6750. Restore and verify once more, with nothing left that can
+            // change it: after this point the file is only synced and renamed.
+            //
+            // The earlier chmod still cannot move here. It is what keeps the
+            // enriched contents from being briefly world-readable, and that window
+            // opens the moment bytes exist.
+            await requirePreservedMode(handle, mode, temporary, target, filesystem);
             // rename() is atomic against concurrent readers but says nothing about
             // power loss: the directory entry can reach disk before the data it
             // points at. Without this a crash mid-write can leave the playlist
@@ -114,19 +177,19 @@ async function writePlaylistAtomically(destination, contents, expectedDigest) {
         // out entirely, which is the safe path when a file is being actively
         // edited.
         if (expectedDigest !== undefined) {
-            const current = await fs_1.promises.readFile(target).catch(() => null);
+            const current = await filesystem.readFile(target).catch(() => null);
             const digest = current && (0, crypto_1.createHash)('sha256').update(current).digest('hex');
             if (digest !== expectedDigest) {
-                await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+                await filesystem.rm(temporary, { force: true }).catch(() => undefined);
                 return false;
             }
         }
-        await fs_1.promises.rename(temporary, target);
-        await syncDirectory((0, path_1.dirname)(target));
+        await filesystem.rename(temporary, target);
+        await syncDirectory((0, path_1.dirname)(target), filesystem);
         return true;
     }
     catch (error) {
-        await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+        await filesystem.rm(temporary, { force: true }).catch(() => undefined);
         throw error;
     }
 }
@@ -137,12 +200,51 @@ async function writePlaylistAtomically(destination, contents, expectedDigest) {
  */
 class OwnershipError extends Error {
     target;
-    constructor(target) {
-        super(`cannot preserve ownership of ${target}`);
+    kind;
+    constructor(target, kind = 'ownership') {
+        super(`cannot preserve ${kind} of ${target}`);
         this.target = target;
+        this.kind = kind;
         this.name = 'OwnershipError';
     }
 }
+/**
+ * requirePreservedMode re-applies the destination's mode to the replacement and
+ * proves it took.
+ *
+ * Called twice, because two different operations clear set-user-ID and
+ * set-group-ID and both sit between the first chmod and the rename: chown does
+ * it, and so does an unprivileged write to a regular file. POSIX permits the
+ * clearing in both cases and Linux performs it, so a mode verified before the
+ * write can still reach the destination as something narrower.
+ *
+ * Verified against the inode rather than inferred from the calls, because a
+ * chmod can report success and still not take: restoring set-group-ID needs the
+ * caller to be in the file's group, and a filesystem may decline the bit
+ * outright. Every one of those endings is the same fact — this replacement
+ * would not carry the access the original had — and completing such a write
+ * silently is precisely what the ownership refusal exists to prevent.
+ *
+ * A destination that did not exist has no mode to preserve, so this is a no-op.
+ *
+ * @param handle - Open temporary file that will be renamed over the destination
+ * @param mode - Permission bits the destination carried, or undefined
+ * @param temporary - Path of the temporary file, removed on refusal
+ * @param target - Destination, named in the refusal
+ * @param filesystem - Filesystem in use
+ * @throws OwnershipError when the mode cannot be reproduced
+ */
+async function requirePreservedMode(handle, mode, temporary, target, filesystem) {
+    if (mode === undefined) {
+        return;
+    }
+    await handle.chmod(mode);
+    const written = await handle.stat();
+    if ((written.mode & 0o7777) !== mode) {
+        await filesystem.rm(temporary, { force: true }).catch(() => undefined);
+        throw new OwnershipError(target, 'permissions');
+    }
+}
 /**
  * syncDirectory flushes a directory entry so a rename survives power loss.
  *
@@ -152,9 +254,9 @@ class OwnershipError extends Error {
  * the rename, so the worst case here is the old name surviving a crash, not a
  * corrupt file.
  */
-async function syncDirectory(directory) {
+async function syncDirectory(directory, filesystem) {
     try {
-        const handle = await fs_1.promises.open(directory, 'r');
+        const handle = await filesystem.open(directory, 'r');
         try {
             await handle.sync();
         }
@@ -313,8 +415,15 @@ exports.enrichCommand = new commander_1.Command('enrich')
     }
     catch (error) {
         if (error instanceof OwnershipError) {
-            console.error(chalk_1.default.red('\nThat playlist belongs to another user or group.'));
-            console.error(chalk_1.default.dim(`  Replacing it in place would hand it to you and could lock others out,\n` +
+            // Two endings, one remedy. Say which one it was: "belongs to another user" sends someone to
+            // check ownership, and that is the wrong place to look when the ownership carried across fine
+            // and a set-group-ID bit is what could not be reproduced.
+            console.error(chalk_1.default.red(error.kind === 'ownership'
+                ? '\nThat playlist belongs to another user or group.'
+                : '\nThat playlist has permissions this replacement cannot reproduce.'));
+            console.error(chalk_1.default.dim((error.kind === 'ownership'
+                ? `  Replacing it in place would hand it to you and could lock others out,\n`
+                : `  Replacing it in place would give it access the original did not have,\n`) +
                 `  so nothing was written. Write elsewhere instead:\n` +
                 `    ff-cli enrich ${error.target} -o enriched.json\n`));
             process.exit(1);

package/dist/src/commands/find.js

@@ -41,10 +41,11 @@ exports.findCommand = new commander_1.Command('find')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
     .option('-p, --play', 'Play the playlist on an FF1 device after building')
+    .option('--no-play', 'Never cast to a device; combine with -y to build and save without playing')
     .option('-d, --device <name>', 'Device to play on (used with --play; default: first configured)')
     .option('--publish', 'Publish the playlist to a configured feed server')
     .option('-s, --server <index>', 'Feed server index (used with --publish)')
-    .option('-y, --yes', 'Skip interactive prompts; defaults to Play unless --output or --publish is set')
+    .option('-y, --yes', 'Skip interactive prompts. Without --output or --publish, -y plays the playlist on a device; add --no-play to skip casting')
     .option('--skip-verify', 'Skip signature verification before --play (mirrors `ff-cli play --skip-verify`)')
     .action(async (input, options) => {
     try {
@@ -478,9 +479,16 @@ async function confirmMakePlaylist(count, hasMore) {
  * Precedence: explicit flags (--play / --publish) win and may combine. If no
  * flag is set, fall back to --yes default (Play) or an interactive 3-way
  * prompt. Save is unconditional and already done before this is called.
+ *
+ * `--no-play` (commander sets `play === false`) is an opt-out that removes
+ * casting from every path, including the `--yes` default and the interactive
+ * prompt. It is additive: `--yes` alone keeps its deliberate "max-satisfaction
+ * default for scripted use" of Play, and this must not change that. Because
+ * `--no-play` already states the user's intent, it never opens the prompt.
  */
 async function decideActions(options) {
     const flagActions = [];
+    const noPlay = options.play === false;
     if (options.play) {
         flagActions.push('play');
     }
@@ -491,7 +499,8 @@ async function decideActions(options) {
         return flagActions;
     }
     // --output alone (with or without --yes) means "save mode" — the save was the action.
-    if (options.output) {
+    // --no-play likewise means the save was the action; never prompt or default to Play.
+    if (options.output || noPlay) {
         return [];
     }
     // --yes without --output defaults to Play (max-satisfaction default for scripted use).

package/dist/src/commands/publish.js

@@ -7,28 +7,35 @@ exports.publishCommand = void 0;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const feed_server_1 = require("./helpers/feed-server");
+const signing_key_source_1 = require("../utilities/signing-key-source");
 exports.publishCommand = new commander_1.Command('publish')
     .description('Publish a playlist to a feed server')
     .argument('<file>', 'Path to the playlist file')
     .option('-s, --server <index>', 'Feed server index (use this if multiple servers configured)')
     .option('--replace', 'Replace the playlist already stored under this document id, instead of creating a new one')
     .option('-k, --key <privateKey>', 'Ed25519 private key that signs the replace authorization (overrides config; --replace only)')
+    .option('--key-file <path>', 'Read the key that signs the replace authorization from this file, not the command line')
     .action(async (file, options) => {
     try {
         // A plain publish signs nothing at request time — it uploads the signatures[] envelope the
-        // document already carries — so --key would do nothing here. Refusing beats accepting it
+        // document already carries — so a key flag would do nothing here. Refusing beats accepting it
         // silently: someone passing a key believes it is being used, and a no-op flag on a command
         // that writes to a feed is the kind of quiet lie this CLI has been removing.
         //
         // Tested for PRESENCE, not truthiness. `--key ""` is what an unset shell variable expands to,
         // and it is still a key the user meant to supply; skipping the refusal for it published the
         // document while leaving them believing a key had been checked.
-        if (options.key !== undefined && !options.replace) {
-            console.error(chalk_1.default.red('\n--key has no effect on a plain publish'));
+        //
+        // The flag is resolved to a NAME here, not to key material: this branch is about to refuse, and
+        // opening someone's key file only to tell them the flag does not apply reads their private key
+        // for no reason at all.
+        const keyFlag = (0, signing_key_source_1.explicitSigningKeyFlag)(options);
+        if (keyFlag !== undefined && !options.replace) {
+            console.error(chalk_1.default.red(`\n${keyFlag} has no effect on a plain publish`));
             console.log(chalk_1.default.yellow('  A publish is authorized by the signatures already inside the document; the command\n' +
                 '  signs nothing. Sign the file first, with the key you meant:\n' +
-                '    ff-cli sign <file> -r curator --key <private key>\n' +
-                '  --key applies to "publish --replace", which signs an authorization intent.\n'));
+                `    ff-cli sign <file> -r curator ${keyFlag} <${keyFlag === '--key-file' ? 'file holding the private key' : 'private key'}>\n` +
+                `  ${keyFlag} applies to "publish --replace", which signs an authorization intent.\n`));
             process.exit(1);
         }
         console.log(chalk_1.default.blue(options.replace ? '\nReplace playlist\n' : '\nPublish playlist\n'));
@@ -42,11 +49,19 @@ exports.publishCommand = new commander_1.Command('publish')
         //
         // Only for --replace: a plain publish signs nothing at request time and must keep working with
         // no key configured at all, so requiring one here would break it.
+        //
+        // A `--key-file` is read as part of the same step: a missing, unreadable, or empty key file is a
+        // credential failure like any other, and it belongs before the server question for the same
+        // reason a malformed key does.
         let replaceKey;
+        let keySource = 'configured';
         if (options.replace) {
             const { mutationSignerIdentity } = await import('../utilities/feed-mutation.js');
+            const { resolveExplicitSigningKey } = await import('../utilities/signing-key-source.js');
             try {
-                replaceKey = mutationSignerIdentity(options.key, 'replace').privateKey;
+                const explicitKey = resolveExplicitSigningKey(options);
+                keySource = explicitKey?.flag ?? 'configured';
+                replaceKey = mutationSignerIdentity(explicitKey?.material, 'replace').privateKey;
             }
             catch (error) {
                 console.error(chalk_1.default.red('\nCannot sign the replacement'));
@@ -72,7 +87,7 @@ exports.publishCommand = new commander_1.Command('publish')
             ? await replacePlaylist(file, selection.url, {
                 // The material resolved above, so the identity validated here is the one that signs.
                 privateKey: replaceKey,
-                keySource: options.key !== undefined ? 'supplied' : 'configured',
+                keySource,
             })
             : await publishPlaylist(file, selection.url);
         if (result.success) {

package/dist/src/commands/setup.js

@@ -16,6 +16,7 @@ const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
 const config_placeholders_1 = require("../utilities/config-placeholders");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
+const signing_key_source_1 = require("../utilities/signing-key-source");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
 /** Generate a fresh Ed25519 signing key as base64 PKCS#8 DER (the recommended form). */
 function generateSigningKeyBase64() {
@@ -26,6 +27,7 @@ exports.setupCommand = new commander_1.Command('setup')
     .description('Guided setup for config, signing key, and device')
     .option('-y, --non-interactive', 'Run without prompts (for agents/CI); uses flags and safe defaults. Auto-enabled when stdin is not a TTY.')
     .option('--key <privateKey>', 'Signing key material (base64 PKCS#8 DER, 32-byte seed as hex/base64, or PEM)')
+    .option('--key-file <path>', 'Read the signing key from this file instead of the command line (preferred for provisioning)')
     .option('--generate-key', 'Generate a new Ed25519 signing key')
     .option('--role <role>', `Signing role (${playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ')})`)
     .option('--device-host <host>', 'FF1 device host, e.g. http://192.168.1.50:1111 (skips mDNS discovery)')
@@ -39,6 +41,39 @@ exports.setupCommand = new commander_1.Command('setup')
     // Lazily open the prompt so non-interactive runs never touch stdin.
     const getAsk = () => (prompt ??= (0, prompt_1.createPrompt)()).ask;
     try {
+        // Resolve and validate an explicit key BEFORE anything touches disk.
+        //
+        // ensureConfigFile() writes a sample config when none exists, so resolving afterwards meant a
+        // run that could never succeed — a missing key file, an unreadable one, both flags at once, a
+        // key that does not parse — still left a config.json behind. On a machine being provisioned
+        // that is the difference between "nothing happened, fix the flag" and a half-configured host
+        // whose state the next run has to reason about.
+        //
+        // Provisioning is exactly where `--key` hurts most: an unattended run puts the key in the
+        // process list of a machine nobody is watching, and in whatever shell or CI log recorded the
+        // command. `--key-file` reads it from a file the provisioner already had to place.
+        //
+        // It is honoured on the interactive path too, not only under --non-interactive. A key on the
+        // command line is an instruction; prompting past it — "Keep existing signing key?" — would ask
+        // a question the operator has already answered, and answering it for them by ignoring the flag
+        // is the quiet lie this CLI keeps removing.
+        const explicitKey = (0, signing_key_source_1.resolveExplicitSigningKey)(options);
+        if (explicitKey !== undefined) {
+            // Validate eagerly so a bad key fails here with a clear message rather
+            // than later inside dp1-js during signing.
+            //
+            // Presence, not truthiness: `--key ""` is what an unset shell variable expands to, and it
+            // used to fall through to "generate a new key" — provisioning a machine with an identity
+            // nobody chose, silently, which is the whole hazard this flag family exists around. It now
+            // fails the same validation any other unusable value does.
+            try {
+                (0, ed25519_key_derive_1.parsePlaylistPrivateKeyToKeyObject)(explicitKey.material);
+            }
+            catch (error) {
+                throw new Error(`Invalid ${explicitKey.flag}: ${error.message}. ` +
+                    'Expected base64 PKCS#8 DER, a 32-byte raw seed as hex/base64, or PEM.');
+            }
+        }
         const { path: configPath, created } = await (0, config_files_1.ensureConfigFile)();
         if (created) {
             console.log(chalk_1.default.green(`Created ${configPath}`));
@@ -49,22 +84,14 @@ exports.setupCommand = new commander_1.Command('setup')
         const currentRole = config.playlist?.role || '';
         let signingKey = currentKey;
         let signingRole = currentRole;
-        if (nonInteractive) {
-            // Key precedence: explicit --key, then --generate-key, then keep an
+        // Already resolved and validated above, before any file was created.
+        if (explicitKey !== undefined) {
+            signingKey = explicitKey.material;
+        }
+        else if (nonInteractive) {
+            // Key precedence with no explicit key: --generate-key, then keep an
             // existing usable key, otherwise generate one so signing works.
-            if (options.key) {
-                // Validate eagerly so a bad key fails here with a clear message rather
-                // than later inside dp1-js during signing.
-                try {
-                    (0, ed25519_key_derive_1.parsePlaylistPrivateKeyToKeyObject)(options.key);
-                }
-                catch (error) {
-                    throw new Error(`Invalid --key: ${error.message}. ` +
-                        'Expected base64 PKCS#8 DER, a 32-byte raw seed as hex/base64, or PEM.');
-                }
-                signingKey = options.key;
-            }
-            else if (options.generateKey || (0, config_files_1.isMissingConfigValue)(currentKey)) {
+            if (options.generateKey || (0, config_files_1.isMissingConfigValue)(currentKey)) {
                 signingKey = generateSigningKeyBase64();
                 console.log(chalk_1.default.dim('Generated a new Ed25519 signing key.'));
             }

package/dist/src/commands/sign.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.signCommand = void 0;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
+const signing_key_source_1 = require("../utilities/signing-key-source");
 // playlist-signer is still CommonJS; require keeps the interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { signPlaylistFile } = require('../utilities/playlist-signer');
@@ -13,14 +14,20 @@ exports.signCommand = new commander_1.Command('sign')
     .description('Sign a DP-1 playlist file with a DP-1 signature envelope')
     .argument('<file>', 'Path to the playlist file to sign')
     .option('-k, --key <privateKey>', 'Ed25519 private key in base64 format (overrides config)')
+    .option('--key-file <path>', 'Read the Ed25519 private key from this file instead of the command line')
     .option('-r, --role <role>', 'DP-1 signing role (overrides config)')
     .option('-o, --output <file>', 'Output file path (defaults to overwriting input file)')
     .option('--replace-signatures', 'Discard the existing signatures and sign fresh (use after editing a signed playlist)')
     .option('--force', 'Overwrite an output file that holds a different document (refused without this)')
     .action(async (file, options) => {
     try {
+        // Resolve the explicit key before the playlist is opened, so an unreadable or empty key file
+        // costs nothing but the run. `--key` material is passed through exactly as typed, including
+        // when it is empty: signPlaylistFile refuses that with the shell-expansion message, which is
+        // the right diagnosis for a value from the command line and the wrong one for a file.
+        const explicitKey = (0, signing_key_source_1.resolveExplicitSigningKey)(options);
         console.log(chalk_1.default.blue('\nSign playlist\n'));
-        const result = await signPlaylistFile(file, options.key, options.output, options.role, {
+        const result = await signPlaylistFile(file, explicitKey?.material, options.output, options.role, {
             replaceSignatures: !!options.replaceSignatures,
             force: !!options.force,
         });

package/dist/src/commands/status.js

@@ -12,6 +12,7 @@ const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
 const signing_identity_1 = require("../utilities/signing-identity");
 const config_placeholders_1 = require("../utilities/config-placeholders");
+const signing_key_source_1 = require("../utilities/signing-key-source");
 exports.statusCommand = new commander_1.Command('status')
     .description('Show configuration status')
     // Identity discovery must cover every key `sign` accepts, not just the configured one. `sign --key`
@@ -19,9 +20,34 @@ exports.statusCommand = new commander_1.Command('status')
     // user the wrong did:key to declare in curators[] — and a wrong declaration fails exactly like a
     // missing one.
     .option('-k, --key <privateKey>', 'Report the signing identity for this key instead of the configured one')
+    .option('--key-file <path>', 'Read the key to report on from this file instead of the command line')
     .action(async (options) => {
     try {
-        const overrideKey = options.key?.trim();
+        // An unusable key file is reported here rather than allowed to fall through. This command's whole
+        // job is to answer "which identity is this?", so silently answering about the configured key
+        // instead — which an empty file would do, since the check below is truthiness — would hand back a
+        // did:key that belongs to something else and looks exactly like the right answer.
+        let explicitKey;
+        try {
+            explicitKey = (0, signing_key_source_1.resolveExplicitSigningKey)(options);
+        }
+        catch (error) {
+            console.log(chalk_1.default.red(error.message));
+            process.exit(1);
+        }
+        const overrideKey = explicitKey?.material.trim();
+        // Presence, not truthiness — the same rule `sign` and the feed mutations enforce, and the reason
+        // it is enforced here too. `--key ""` is what `--key "$SIGNING_KEY"` becomes when the variable is
+        // unset, and falling through to the configured identity answers "whose key is this?" with a
+        // different key's did:key. Nothing about that answer looks wrong, so it would be copied into
+        // curators[], and a wrong declaration fails exactly like a missing one.
+        if (explicitKey !== undefined && !overrideKey) {
+            console.log(chalk_1.default.red(`The ${explicitKey.flag} value is empty. This usually means a shell variable did not ` +
+                `expand (for example ${explicitKey.flag} "$SIGNING_KEY" with SIGNING_KEY unset).`));
+            console.log(chalk_1.default.yellow('  Refusing rather than reporting the configured identity, which belongs to a different\n' +
+                '  key. Run "ff-cli status" with no key flag if that is the identity you wanted.'));
+            process.exit(1);
+        }
         if (overrideKey) {
             try {
                 console.log(chalk_1.default.green(`Signing identity (did:key) ${(0, signing_identity_1.playlistSigningDidKey)(overrideKey)}`));
@@ -29,7 +55,7 @@ exports.statusCommand = new commander_1.Command('status')
                 return;
             }
             catch (error) {
-                console.log(chalk_1.default.red(`--key unusable: ${error.message}`));
+                console.log(chalk_1.default.red(`${explicitKey?.flag ?? '--key'} unusable: ${error.message}`));
                 process.exit(1);
             }
         }

package/dist/src/commands/unpublish.js

@@ -8,20 +8,13 @@ const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const feed_server_1 = require("./helpers/feed-server");
 const prompt_1 = require("./helpers/prompt");
-/**
- * `ff-cli unpublish <id-or-url>` — delete a playlist this key owns from a feed.
- *
- * The delete is irreversible in a way most deletes are not: the feed tombstones the id, so the playlist
- * cannot be restored and the id can never be reused. Hence the confirmation, which shows the title and
- * server first, and defaults to no. `-y` skips it for scripts; without a terminal and without `-y` the
- * command refuses rather than assuming consent.
- */
 exports.unpublishCommand = new commander_1.Command('unpublish')
     .description('Delete a playlist from a feed server (signed delete; owner key required)')
     .argument('<id-or-url>', 'Playlist id, slug, or feed URL')
     .option('-s, --server <index>', 'Feed server index (use this if multiple servers configured)')
     .option('-y, --yes', 'Skip the confirmation prompt')
     .option('-k, --key <privateKey>', 'Ed25519 private key that signs the delete authorization (overrides config)')
+    .option('--key-file <path>', 'Read the key that signs the delete authorization from this file, not the command line')
     .action(async (idOrUrl, options) => {
     try {
         console.log(chalk_1.default.blue('\nUnpublish playlist\n'));
@@ -46,11 +39,19 @@ exports.unpublishCommand = new commander_1.Command('unpublish')
         // The DID displayed below and the key that signs are now the same value.
         //
         // Only the did:key is ever printed; the material never reaches the output from this path.
+        //
+        // `--key-file` is read here too, in the same step and before the same milestones: a key file that
+        // is missing, unreadable, or empty is a credential failure like any other, and it must not be
+        // discovered after the operator has approved a delete.
         const { mutationSignerIdentity } = await import('../utilities/feed-mutation.js');
+        const { resolveExplicitSigningKey } = await import('../utilities/signing-key-source.js');
         let signerDidKey;
         let signingKey;
+        let keySource = 'configured';
         try {
-            ({ privateKey: signingKey, didKey: signerDidKey } = mutationSignerIdentity(options.key, 'delete'));
+            const explicitKey = resolveExplicitSigningKey(options);
+            keySource = explicitKey?.flag ?? 'configured';
+            ({ privateKey: signingKey, didKey: signerDidKey } = mutationSignerIdentity(explicitKey?.material, 'delete'));
         }
         catch (error) {
             console.error(chalk_1.default.red('\nCannot sign the delete'));
@@ -111,7 +112,7 @@ exports.unpublishCommand = new commander_1.Command('unpublish')
         }
         const result = await unpublishPlaylist(idOrUrl, selection.url, {
             privateKey: signingKey,
-            keySource: options.key !== undefined ? 'supplied' : 'configured',
+            keySource,
         });
         if (result.success) {
             console.log(chalk_1.default.green('Unpublished'));