@feralfile/cli 2.9.0 → 2.10.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.9.0",
+    "version": "2.10.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",

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/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'));

package/dist/src/utilities/feed-mutation.js

@@ -141,7 +141,11 @@ async function fetchStoredPlaylist(feedServerUrl, identifier) {
     return stored;
 }
 /**
- * Resolve the key that signs an owner-bound intent, honouring an explicit `--key`.
+ * Resolve the key that signs an owner-bound intent, honouring an explicit key from the command line.
+ *
+ * `--key-file` material arrives here already read and trimmed by `signing-key-source`, which rejects an
+ * empty file there rather than here: the message below is about shell expansion, which is the right
+ * diagnosis for a value typed at the prompt and the wrong one for a file that turned out to be empty.
  *
  * **Presence, never truthiness.** `--key ""` — the shape an unset shell variable takes,
  * `--key "$SIGNING_KEY"` with nothing in it — is an override that FAILED, not an absent one. Treating it
@@ -168,7 +172,8 @@ function resolveMutationSigningKey(override, action) {
     const configured = (0, config_1.getPlaylistConfig)().privateKey;
     if (!configured) {
         throw new Error(`No playlist signing key is configured. A ${action} is authorized by a signature, so one is ` +
-            'required: run "ff-cli setup", set playlist.privateKey in config.json, or pass --key.');
+            'required: run "ff-cli setup", set playlist.privateKey in config.json, or pass --key / ' +
+            '--key-file for this run.');
     }
     return configured;
 }
@@ -235,20 +240,26 @@ async function storedOwnership(stored) {
     }
     return { declared, proven };
 }
+/** How a private key is named as the argument to the flag it arrived on. */
+function flagArgument(keySource) {
+    return keySource === '--key-file' ? 'file holding the private key' : 'private key';
+}
 /** How to describe the identity in a refusal, given where it came from. */
 function identityLabel(keySource) {
-    return keySource === 'supplied'
-        ? 'The identity you passed with --key:'
-        : 'Your configured identity:';
+    return keySource === 'configured'
+        ? 'Your configured identity:'
+        : `The identity you passed with ${keySource}:`;
 }
 /** What to do about it, given where it came from. */
 function retryAdvice(keySource, plural) {
     const which = plural ? 'one of the keys listed above' : 'the key listed above';
-    return keySource === 'supplied'
-        ? `  Run it again with an owner key: --key <private key for ${which}>.\n` +
-            `  (Confirm which identity a key carries with "ff-cli status --key <private key>".)`
-        : `  Point playlist.privateKey at ${which}, or pass one for this run with --key (confirm any\n` +
-            `  key's identity with "ff-cli status --key <private key>").`;
+    if (keySource === 'configured') {
+        return (`  Point playlist.privateKey at ${which}, or pass one for this run with --key (confirm any\n` +
+            `  key's identity with "ff-cli status --key <private key>").`);
+    }
+    const argument = flagArgument(keySource);
+    return (`  Run it again with an owner key: ${keySource} <${argument} for ${which}>.\n` +
+        `  (Confirm which identity a key carries with "ff-cli status ${keySource} <${argument}>".)`);
 }
 /**
  * Refuse locally when the signing key cannot authorize a mutation on the stored playlist.
@@ -319,7 +330,9 @@ async function ownershipPreflight(stored, signerDidKey, action, keySource = 'con
                 `  over the document as published.`,
         };
     }
-    const source = keySource === 'supplied' ? 'The key you passed with --key is' : 'The configured signing key is';
+    const source = keySource === 'configured'
+        ? 'The configured signing key is'
+        : `The key you passed with ${keySource} is`;
     return {
         error: `${source} not an owner of this playlist, so it cannot ${verb} it.`,
         message: `Only a key the stored playlist names in curators[] AND that signed it as "${exports.OWNER_ROLE}" can\n` +
@@ -381,8 +394,8 @@ function describeFeedMutationError(error, action, keySource = 'configured') {
         return {
             error: `${verb} refused: the feed saw no signatures on the request.`,
             message: `Every mutating request is authorized by the signatures in its body — there is no API key.\n` +
-                (keySource === 'supplied'
-                    ? `  The key passed with --key produced no signature the feed could read, which should not\n` +
+                (keySource !== 'configured'
+                    ? `  The key passed with ${keySource} produced no signature the feed could read, which should not\n` +
                         `  happen once it has been accepted locally — please report this.\n`
                     : `  This usually means no signing key is configured: run "ff-cli status" to check, and\n` +
                         `  "ff-cli setup" to generate one.\n`) +
@@ -395,9 +408,9 @@ function describeFeedMutationError(error, action, keySource = 'configured') {
     // remaining causes are the feed disagreeing about the stored document, or a replace touching the
     // owner set. Say that the feed refused, and that the local check disagreed.
     if (status === 403) {
-        const which = keySource === 'supplied'
-            ? 'the key you passed with --key is'
-            : 'the configured signing key is';
+        const which = keySource === 'configured'
+            ? 'the configured signing key is'
+            : `the key you passed with ${keySource} is`;
         return {
             error: `${verb} refused by the feed: it did not accept the signing key as an owner.`,
             message: `The local check disagreed — ${which} named in the stored playlist's curators[]\n` +

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

@@ -127,7 +127,7 @@ async function replacePlaylist(filePath, feedServerUrl, options = {}) {
     // Where the identity came from, resolved before the first request so every refusal — local or from
     // the feed — names the key the operator actually used rather than a config file this run may not
     // have read.
-    const keySource = options.keySource ?? (options.privateKey !== undefined ? 'supplied' : 'configured');
+    const keySource = options.keySource ?? (options.privateKey !== undefined ? '--key' : 'configured');
     // Presence, not truthiness: `--key ""` is an override that failed to expand, and falling back to the
     // configured key would sign someone else's replacement into place.
     let privateKey;

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

@@ -56,7 +56,7 @@ async function unpublishPlaylist(idOrUrl, feedServerUrl, options = {}) {
     // Where the identity came from, resolved before the first request so every refusal — local or from
     // the feed — names the key the operator actually used rather than a config file this run may not
     // have read.
-    const keySource = options.keySource ?? (options.privateKey !== undefined ? 'supplied' : 'configured');
+    const keySource = options.keySource ?? (options.privateKey !== undefined ? '--key' : 'configured');
     // Resolve and validate together: `--key ""` is a failed override, not an absent one, and must never
     // fall through to the configured key on an operation that tombstones an id.
     let privateKey;

package/dist/src/utilities/signing-key-source.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Where an explicit signing key came from: `--key` on the command line, or `--key-file` on disk.
+ *
+ * `--key` puts a private key in two places nobody chose to put it: the shell history file, and the
+ * process list, where any local user can read it for as long as the command runs. Neither is something
+ * the operator can take back afterwards, and an Ed25519 signing key that has been disclosed is not
+ * repairable — the identity it asserts is the identity, and a playlist's owner set is immutable. So
+ * every command that accepts `--key` also accepts `--key-file <path>`, which reads the same material
+ * from a file the operator controls.
+ *
+ * The two flags are mutually exclusive rather than ordered. A precedence rule would have to pick a
+ * winner when they disagree, and the loser is silently ignored — which is exactly the class of failure
+ * the empty-`--key` fix removed: a key the operator believes was used and was not.
+ *
+ * Reading the file is deliberately *not* gated on its permissions. A mode check would refuse work on
+ * key files that are perfectly appropriate — a file inside a per-user directory, a path on a tmpfs
+ * mounted for one user, a Windows ACL the mode bits cannot describe — and it would still not prove the
+ * file is private, because the directory above it decides who can reach the name at all. The
+ * documentation says to keep the file private; the CLI does not pretend to be able to check it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explicitSigningKeyFlag = explicitSigningKeyFlag;
+exports.readSigningKeyFile = readSigningKeyFile;
+exports.resolveExplicitSigningKey = resolveExplicitSigningKey;
+const node_fs_1 = require("node:fs");
+/**
+ * Which key flag the command was given, without reading anything.
+ *
+ * Split out from the resolution below so a command that is going to *refuse* an explicit key — a plain
+ * `publish` signs nothing at request time — can name the flag the operator actually typed without
+ * opening their key file to do it.
+ *
+ * Presence, never truthiness: `--key ""` and `--key-file ""` are both what an unset shell variable
+ * expands to, and both are overrides that failed rather than overrides that are absent.
+ *
+ * @param options - The command's parsed options
+ * @returns The flag used, or `undefined` when neither was given
+ * @throws Error when both flags are present
+ */
+function explicitSigningKeyFlag(options) {
+    const hasKey = options.key !== undefined;
+    const hasKeyFile = options.keyFile !== undefined;
+    if (hasKey && hasKeyFile) {
+        throw new Error('--key and --key-file both name a signing key, and nothing here can tell which one you meant. ' +
+            'Pass exactly one: --key for material on the command line, --key-file for a path to read it from.');
+    }
+    if (hasKeyFile) {
+        return '--key-file';
+    }
+    return hasKey ? '--key' : undefined;
+}
+/**
+ * Read key material out of a key file.
+ *
+ * The contents are trimmed, so a file written by `printf`, by an editor that appends a newline, or by a
+ * password manager's export all behave the same. What comes back then goes through the *same*
+ * normalization `--key` does — base64 PKCS#8 DER, a 32-byte seed as hex or base64, or PEM — because a
+ * key file is a delivery mechanism, not a second key format.
+ *
+ * An empty or whitespace-only file is rejected here rather than passed on. Every other outcome would be
+ * a silent fallback to the configured key: `sign` and the feed mutations would refuse an empty `--key`
+ * with a message about shell expansion that is wrong for a file, and `status` would quietly report the
+ * configured identity as though it were the file's. That fallback is the bug the empty-`--key` fix
+ * removed, and it is worse from a file, because a file that reads as empty (truncated, still being
+ * written, the wrong path in a directory of similar names) looks nothing like a typo at the prompt.
+ *
+ * Every argument is opened. Deciding in advance that something "looks like a key" and refusing to try
+ * cost real paths — `/run/BEGIN/secrets/owner.key`, a content-addressed 64-hex filename — and bought
+ * nothing, because opening a wrong path is free. What is not free is *printing* one: a private key
+ * that reaches a terminal is in scrollback and in whatever ships those logs onward, and it cannot be
+ * rotated out of a document that already names it. So the guarantee lives entirely in what may be said
+ * about a failure; see `safePathLabel`. Existence is also the only thing separating a key typed into
+ * the path from a file genuinely named after a hex digest, and that cannot be known without looking.
+ *
+ * @param path - Value of `--key-file` exactly as the command received it
+ * @returns Trimmed key material
+ * @throws Error when the path is empty, cannot be read, or holds no key material
+ */
+function readSigningKeyFile(path) {
+    if (path.trim().length === 0) {
+        throw new Error('The --key-file path is empty. This usually means a shell variable did not expand (for example ' +
+            '--key-file "$KEY_PATH" with KEY_PATH unset). Refusing rather than falling back to the ' +
+            'configured key, which would sign under an identity you did not choose.');
+    }
+    // The path is used exactly as given, NOT trimmed. Trimming was only ever a convenience, and it is
+    // the wrong one here: it silently opens `owner.key` for `--key-file "owner.key "`, so a file that
+    // is not the one named decides what signs. The trim above answers a different question — whether
+    // anything was passed at all.
+    let contents;
+    try {
+        contents = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(describeKeyFileReadFailure(path, error));
+    }
+    const material = contents.trim();
+    if (material.length === 0) {
+        throw new Error(`The key file at ${safePathLabel(path)} holds no key material. Refusing rather than falling ` +
+            'back to the configured key: a signature made under an identity you did not choose is not ' +
+            'something a publish or a delete can be taken back from.');
+    }
+    return material;
+}
+/**
+ * Whether a value is, on its own, a complete Ed25519 key encoding.
+ *
+ * Complete is the whole point. An earlier version treated any `BEGIN` substring and any key-shaped
+ * last segment as reason enough to refuse before opening, which made `/run/BEGIN/secrets/owner.key`
+ * and a content-addressed 64-hex filename unusable — real paths, refused for looking like something
+ * they were not, with no way to say otherwise. The shapes below are the forms a whole key takes and
+ * nothing else: a PEM block carries both its header AND the line breaks a real block has, a hex seed
+ * is 64 characters of nothing but hex, and base64 is judged by what it decodes to.
+ */
+function isWholeKeyEncoding(value) {
+    if (value.includes('BEGIN') && /[\r\n]/.test(value)) {
+        return true;
+    }
+    if (/^(0x)?[0-9a-fA-F]{64,}$/.test(value)) {
+        return true;
+    }
+    // Decided by DECODED LENGTH rather than by charset alone: `/` and `+` are legal base64 and most
+    // real PKCS#8 keys contain a `/`, so a charset test that read that as a directory separator would
+    // let the common case through. 32 bytes is a raw Ed25519 seed; 48 is PKCS#8 for one.
+    if (/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+        const decodedLength = Buffer.from(value, 'base64').length;
+        if (decodedLength === 32 || decodedLength === 48) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Whether the argument is a bare key: a complete encoding with no path structure around it. */
+function isBareKeyMaterial(value) {
+    return !/[/\\]/.test(value) && isWholeKeyEncoding(value);
+}
+/** Whether any path segment is a complete key encoding — a key with a directory prefix on it. */
+function anySegmentIsKeyEncoding(value) {
+    return value.split(/[/\\]/).some((segment) => isWholeKeyEncoding(segment));
+}
+/**
+ * How to refer to a `--key-file` argument in a message, without ever printing key material.
+ *
+ * This is the guarantee, and it is deliberately separate from the decision to open. Opening a wrong
+ * path costs nothing; printing one can disclose a private key that cannot be rotated out of a document
+ * that already names it. So everything is opened, and this decides what may be said afterwards.
+ *
+ * Length carries most of it: no complete key encoding is under 40 characters — a 32-byte seed is 64
+ * hex or 44 base64 characters — so a short argument cannot be a whole key, and a partial one is not a
+ * key. The segment test then covers a key wearing a directory prefix, which length alone would pass
+ * only for something already too long to print.
+ *
+ * @param path - Value of `--key-file` exactly as the command received it
+ * @returns The path itself when it is provably safe to print, or a description of it
+ */
+function safePathLabel(path) {
+    const value = path.trim();
+    if (value.length < 40 && !anySegmentIsKeyEncoding(value)) {
+        return path;
+    }
+    return 'the path given (not repeated here, in case it is key material)';
+}
+/**
+ * Turn a read failure into a sentence that says what to do about it.
+ *
+ * The raw errno text ("EISDIR: illegal operation on a directory, read") reads like a bug in the CLI
+ * rather than a wrong path, and it is the same three mistakes every time: the file is not there, it is
+ * not readable, or the path names a directory.
+ *
+ * The underlying `Error.message` is never interpolated — only its `code`. Node builds that message by
+ * appending the path it was given, so passing it through would echo the argument a second time, in a
+ * form no caller here controls.
+ */
+function describeKeyFileReadFailure(path, error) {
+    const code = error?.code;
+    const value = path.trim();
+    // A bare, complete key with nothing of a path about it, and no file of that name. `--key-file
+    // "$SIGNING_KEY"` is one keystroke from `--key "$SIGNING_KEY"`, and it is the natural typo for
+    // someone moving off `--key`, so say what the mistake was. Existence is what separates this from a
+    // file someone genuinely named after a hex digest — which is why the open is attempted first rather
+    // than guessed at.
+    if (isBareKeyMaterial(value)) {
+        return ('The --key-file argument looks like a key rather than a path, and no file of that name exists. ' +
+            'It is not repeated here. Point --key-file at the file that holds the key, or pass the key ' +
+            'itself with --key.');
+    }
+    const label = safePathLabel(path);
+    // When the argument cannot be printed, the errno is the whole message. Naming which failure it was
+    // is still worth saying — "there is nothing there" and "you may not read it" send an operator to
+    // different places — but nothing about the value itself may appear.
+    if (label !== path) {
+        return (`The --key-file argument could not be read (${code ?? 'read failed'}) and is not repeated ` +
+            'here: it may be key material rather than a path. Check the path you passed.');
+    }
+    if (code === 'ENOENT') {
+        return `No key file at ${label}.`;
+    }
+    if (code === 'EACCES' || code === 'EPERM') {
+        return `Cannot read the key file at ${label}: permission denied (${code}).`;
+    }
+    if (code === 'EISDIR') {
+        return `${label} is a directory, not a key file.`;
+    }
+    return `Cannot read the key file at ${label} (${code ?? 'read failed'}).`;
+}
+/**
+ * Resolve the explicit signing key a command was given, from either flag.
+ *
+ * Commands call this before anything else — before a feed is chosen, before a playlist is looked up,
+ * before a destructive action is confirmed — so an unreadable file fails while the only thing it can
+ * cost is the run itself.
+ *
+ * `--key` material is returned exactly as typed, including when it is empty: the commands already
+ * refuse an empty `--key` with a message about shell expansion, and that message is the right one for
+ * a value that came from the command line.
+ *
+ * @param options - The command's parsed options
+ * @returns The explicit key and its flag, or `undefined` when neither flag was given
+ * @throws Error when both flags are present, or when a key file cannot be read or is empty
+ */
+function resolveExplicitSigningKey(options) {
+    const flag = explicitSigningKeyFlag(options);
+    if (flag === undefined) {
+        return undefined;
+    }
+    if (flag === '--key-file') {
+        return { material: readSigningKeyFile(options.keyFile), flag };
+    }
+    return { material: options.key, flag };
+}

package/docs/CONFIGURATION.md

@@ -39,7 +39,7 @@ Optional settings used where headless/browser‑like behavior is needed.
 
 Used for signing DP‑1 playlists.
 
-- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures, and as the default signing key for the owner-bound feed mutations (`publish --replace`, `unpublish`), which sign an authorization intent at request time. Those commands and `sign` all take `-k, --key` to override it for a single run. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`. `play` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `play` and `publish` verify before delivery or upload and reject unsigned or broken playlists.
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures, and as the default signing key for the owner-bound feed mutations (`publish --replace`, `unpublish`), which sign an authorization intent at request time. Those commands and `sign` all take `-k, --key` or `--key-file <path>` to override it for a single run — see [Where the signing key can come from](#where-the-signing-key-can-come-from). The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`. `play` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `play` and `publish` verify before delivery or upload and reject unsigned or broken playlists.
 
   **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) accept the private key in any of these encodings:
 
@@ -61,10 +61,64 @@ Used for signing DP‑1 playlists.
 
   To read the `did:key` your signatures will carry, run `ff-cli status`. It reports the identity from
   `PLAYLIST_PRIVATE_KEY` even when no config file exists yet, and `ff-cli status --key <privateKey>`
-  reports it for an explicit key — the one `sign --key` would use.
+  (or `--key-file <path>`) reports it for an explicit key — the one `sign` would use with the same flag.
 
 - `playlist.role` (string): DP-1 signing role used by `ff-cli sign`. The shipped `config.json.example` sets `curator`, because a document signed as `agent` is ownerless to a role-aware feed and `ff-cli publish` refuses it. The code default when the key is omitted entirely is still `agent`. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`). It does **not** apply to `find` and `build`, which always sign as `curator` — see [Signing role and ownership](#signing-role-and-ownership).
 
+### Where the signing key can come from
+
+Three sources, in this order of precedence:
+
+1. **`-k, --key <privateKey>` or `--key-file <path>`** on the command line — `sign`, `status`,
+   `unpublish`, and `publish --replace` all take both.
+2. **`playlist.privateKey`** in `config.json`.
+3. **`PLAYLIST_PRIVATE_KEY`** in the environment or in `.env`.
+
+The file beats the environment, matching the repo-wide `config.json` > `.env` > defaults rule — with
+one exception: a `playlist.privateKey` that is empty or still holds a `YOUR_`/`your_` sample
+placeholder is treated as **unset**, so `PLAYLIST_PRIVATE_KEY` is used instead. Without that, an
+untouched `config init` would beat a perfectly good environment key and every signing path would fail
+on a key you never chose.
+
+An explicit key wins for that one run only; nothing is written back. All three accept the same
+encodings listed above, and the CLI normalizes whichever you supply before signing, so a key file is a
+delivery mechanism rather than a fourth key format.
+
+**Prefer `--key-file` to `--key`.** `--key` writes your private key into your shell history file and
+exposes it in the process list, where any local user can read it for as long as the command runs.
+Neither disclosure can be undone: an Ed25519 signing key *is* the identity it asserts, and a playlist's
+`curators[]` owner set is immutable, so a leaked key cannot be rotated out of a document that already
+names it. `--key-file` keeps the material in a file you control:
+
+```bash
+ff-cli status --key-file ~/.config/ff-cli/signing.key      # whose key is this?
+ff-cli sign playlist.json -r curator --key-file ~/.config/ff-cli/signing.key
+```
+
+**Keep the key file private** — `chmod 600` it, in a directory only you can enter. The CLI does not
+check its permissions and will not refuse a world-readable one: a mode check cannot see the directory
+above the file, cannot describe a Windows ACL, and would refuse paths that are perfectly appropriate,
+so it would be ceremony rather than protection.
+
+The rules on both flags:
+
+- **Passing both is an error**, not a precedence rule. A precedence rule has to silently ignore one of
+  the two keys you supplied, and a key you believe was used and was not is the failure this CLI keeps
+  removing.
+- **An empty `--key`** — what `--key "$SIGNING_KEY"` becomes when the variable is unset — is rejected,
+  never treated as absent.
+- **A `--key-file` that is missing, unreadable, or holds no key material** is rejected the same way.
+  Neither ever falls back to the configured key: signing under an identity you did not choose is not
+  something a publish or a delete can be taken back from.
+- **A `--key-file` argument is always opened, whatever it looks like.** A directory really can be
+  called `BEGIN`, and a key file really can be named after a content hash. What is gated is not the
+  open but the *message*: a failure names the path only when it is short and no part of it is a
+  complete key encoding, and otherwise says it could not be read without repeating it. Typing the key
+  where the path goes — one keystroke from `--key` — is reported as that mistake, by name, with the
+  value withheld.
+- **The key is never echoed**, in any error, in any encoding — nor is a `--key-file` argument that may
+  be one.
+
 ### Generate an Ed25519 private key
 
 The simplest path is `ff-cli setup`, which generates a key for you (base64 PKCS#8 DER) and writes it to your config. To generate one yourself:
@@ -143,8 +197,8 @@ signatures in the request body, and an `apiKey` left in an existing config is ig
 
 `playlist.privateKey` is needed only where the CLI itself has to sign at request time — `publish
 --replace` and `unpublish`, which sign the owner-bound intent that authorizes the write. Both accept
-`-k, --key` to use a different key for one run, so a second owner identity does not require editing this
-file. A plain
+`-k, --key` or `--key-file <path>` to use a different key for one run, so a second owner identity does
+not require editing this file. A plain
 `publish` signs nothing: it uploads the `signatures[]` envelope the document already carries, so it
 works with no key configured at all (the document must have been signed at some point, by
 `ff-cli sign` or by whoever produced it, but not by this command).

package/docs/EXAMPLES.md

@@ -789,9 +789,9 @@ a new playlist instead of trying to recreate it.
 ### Signing with a key other than the configured one
 
 The configured `playlist.privateKey` is the default, not the only option. `unpublish` and
-`publish --replace` take `-k, --key`, like `ff-cli sign` and `ff-cli status`, and it overrides that
-default both for the intent signature and for the local ownership check — so holding a second owner key
-no longer means editing `config.json`:
+`publish --replace` take `-k, --key` and `--key-file <path>`, like `ff-cli sign` and `ff-cli status`,
+and either one overrides that default both for the intent signature and for the local ownership check —
+so holding a second owner key no longer means editing `config.json`:
 
 ```bash
 ff-cli unpublish <id> -s 0 --key <private key for a stored owner>
@@ -804,8 +804,36 @@ confirmation and under `-y`, so the identity that performs an irreversible delet
 record. It resolves that key once, before the lookup and before the prompt, and signs with the same
 material — editing `config.json` while a confirmation is open cannot change who the delete runs as.
 
-A refusal names the key you actually used. If it came from `--key`, the retry says `--key`; it will not
-send you to `playlist.privateKey` for a run that never read it.
+#### Keeping the key off the command line
+
+`--key` puts the private key in your shell history file and in the process list, where any local user
+can read it while the command runs. `--key-file <path>` reads the same material from a file instead, on
+all four commands, with the same key encodings:
+
+```bash
+ff-cli status   --key-file ~/.config/ff-cli/owner.key          # whose key is this?
+ff-cli sign     playlist.json -r curator --key-file ~/.config/ff-cli/owner.key
+ff-cli unpublish <id> -s 0 --key-file ~/.config/ff-cli/owner.key
+ff-cli publish  playlist.json --replace -s 0 --key-file ~/.config/ff-cli/owner.key
+```
+
+Keep the file private (`chmod 600`, in a directory only you can enter) — the CLI does not check its
+permissions. Passing `--key` and `--key-file` together is an error rather than a precedence rule, and a
+key file that is missing, unreadable, or empty is refused rather than quietly falling back to the
+configured key:
+
+```
+$ ff-cli unpublish <id> -y --key-file ./owner.key    # file was truncated
+
+Cannot sign the delete
+  The key file at ./owner.key holds no key material. Refusing rather than falling back to
+  the configured key: a signature made under an identity you did not choose is not something
+  a publish or a delete can be taken back from.
+```
+
+A refusal names the key you actually used. If it came from `--key`, the retry says `--key`; if it came
+from `--key-file`, the retry says `--key-file`; it will not send you to `playlist.privateKey` for a run
+that never read it.
 
 An empty `--key` is **rejected**, not ignored:
 
@@ -819,8 +847,9 @@ Cannot sign the delete
   delete can be taken back from.
 ```
 
-A plain `publish` **refuses** `--key` rather than ignoring it: it signs nothing at request time, so the
-flag would do nothing. `ff-cli fetch` has no `--key` for the same reason — it is a read.
+A plain `publish` **refuses** `--key` and `--key-file` rather than ignoring them: it signs nothing at
+request time, so the flag would do nothing. `ff-cli fetch` has neither for the same reason — it is a
+read.
 
 ### When ownership cannot be proved
 

package/docs/PROJECT_SPEC.md

@@ -192,7 +192,9 @@ created, signatures }`, with a `payloadHash` for replace — whose `created` mus
 freshness window; the intent exists because a document's own signatures are public via `GET` and could
 otherwise be replayed to roll a resource back. The CLI proves ownership before it signs anything: it
 `GET`s the stored playlist and requires the signing key — the configured `playlist.privateKey` unless
-`-k, --key` overrides it for that command — to be both named in the stored `curators[]` and the signer of
+`-k, --key` or `--key-file <path>` overrides it for that command, the latter keeping the key out of the
+shell history and the process list (`CONFIGURATION.md`, "Where the signing key can come from") — to be
+both named in the stored `curators[]` and the signer of
 a cryptographically valid `curator`-role signature over that stored document. Being
 named is a claim; the owner-role signature is the proof, and checking only the claim is what would let a
 legacy `agent`-signed document pass preflight and come back as a `403` reported as a missing
@@ -392,10 +394,17 @@ and nothing else. `enrich` is the repair path for those.
   a curator-restricted playlist is never briefly world-readable mid-write. The
   destination's owner and group are carried across too, since a replacement is
   a new inode and would otherwise take this process's ownership — silently
-  reassigning a shared playlist. Where that cannot be done, the in-place
-  replacement is refused and `--output` is offered instead. Extended ACLs are
-  not preserved, because Node exposes no portable way to read them; a playlist
-  carrying them should be enriched through `--output`.
+  reassigning a shared playlist. Two things clear set-user-ID and set-group-ID
+  — the chown, and an unprivileged write to a regular file — so the mode is
+  restored and verified against the inode after each of them, the second time
+  with nothing left before the rename that could change it. Where the ownership
+  or the mode cannot be reproduced, the in-place replacement is refused and
+  `--output` is offered instead. Access-control
+  lists are not preserved: a replacement is a new inode, so its ACL comes from
+  the directory's default rather than from the file being replaced, and mode
+  bits cannot carry named entries across on any platform — a playlist whose
+  access depends on an ACL should be enriched through `--output` to a fresh
+  name in a directory whose access is what the result should have.
 - `--output` names a file the caller expects to exist afterwards, so it is
   written even when nothing was enriched. A no-op without `--output` writes
   nothing rather than rewriting the input for no gain.

package/docs/README.md

@@ -19,6 +19,19 @@ npm i -g @feralfile/cli
 ff-cli setup
 ```
 
+Unattended provisioning takes the same flags without prompting. Pass an existing signing key with
+`--key-file <path>` rather than `--key`, which puts the key in the process list of a machine nobody is
+watching and in whatever shell or CI log recorded the command:
+
+```bash
+ff-cli setup --non-interactive --key-file /run/secrets/ff-signing.key \
+  --role curator --device-host http://192.168.1.50:1111 --device-name studio
+```
+
+`--key` and `--key-file` together is an error, and an empty or unreadable key file is refused rather
+than quietly generating a new identity for the machine. See
+[Where the signing key can come from](./CONFIGURATION.md#where-the-signing-key-can-come-from).
+
 See the full configuration reference here: `./CONFIGURATION.md`.
 
 During setup, you can pick FF1 devices to add. Use `ff-cli device add` to add more devices later, and `ff-cli device list` to see what's configured. The first device is the default for `play` commands (override with `-d`).
@@ -97,7 +110,8 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
 - `validate <file-or-url>` – Validate playlist structure only
 - `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
 - `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
-  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`, `--replace-signatures`, `--force`
+  - Options: `-k, --key <privateKey>`, `--key-file <path>`, `-r, --role <role>`, `-o, --output <file>`, `--replace-signatures`, `--force`
+  - `--key-file <path>` reads the key from a file instead of the command line, which is where `--key` leaves it in your shell history and in the process list. Same key encodings, same normalization; keep the file private, since the CLI does not check its permissions. `--key` and `--key-file` together is an error, and an empty or unreadable key file is refused rather than falling back to the configured key
   - **It overwrites only a document it has read.** Before writing, the destination is read back and compared with the document being signed; if it holds something else, the run is refused rather than destroying a file the command never inspected. `--force` allows that overwrite, and the report names the file it replaced. A destination holding the *same* document — a copy of the input — is treated as an in-place run, so it is refused only when it would discard a still-valid signature from another key, and `--force` does not override that one. The read and the overwrite are not atomic, so an editor writing in the same instant can still lose its change, as with any in-place tool — a fresh `--output` name is the write that cannot collide. A destination that already exists needs read permission
   - Signing **appends** by default, so repeated runs accumulate endorsements. That is only correct while the signed content is unchanged: editing a signed playlist moves bytes the earlier signatures cover, and the envelope check then refuses to write the result. `--replace-signatures` discards every existing entry — including a feed's own co-signature — and signs the document as it stands. It is the required step before `publish --replace`
   - **An in-place run refuses when it would discard a still-valid signature from another key**, since only its holder could make that signature again: write the result elsewhere with `-o, --output`, which leaves the original where it is. The refusal is about what cannot be recovered — an in-place run still proceeds when the only entries dropped are your own, or ones that no longer verify
@@ -113,12 +127,12 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - DP-1 `evm` names a chain family rather than a network, so those items are skipped unless `--assume-ethereum` asserts which one they are. Getting that wrong attaches another artwork's metadata
   - Options: `-o, --output <file>`, `--force` (replace existing manifests), `--assume-ethereum`, `-v, --verbose`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
-  - Options: `-s, --server <index>` (server index if multiple configured), `--replace` (replace the playlist already stored under this document id instead of creating a new one), `-k, --key <privateKey>` (signs the replace authorization; `--replace` only)
-  - `--key` is refused on a plain `publish`, which signs nothing at request time — it uploads the `signatures[]` envelope the document already carries. Sign the file with `ff-cli sign --key` instead
+  - Options: `-s, --server <index>` (server index if multiple configured), `--replace` (replace the playlist already stored under this document id instead of creating a new one), `-k, --key <privateKey>` (signs the replace authorization; `--replace` only), `--key-file <path>` (the same key, read from a file)
+  - `--key` and `--key-file` are both refused on a plain `publish`, which signs nothing at request time — it uploads the `signatures[]` envelope the document already carries. Sign the file with `ff-cli sign --key-file` instead
 - `fetch <id-or-url>` – Save a published playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. The document goes to `-o` when given and to stdout otherwise (status lines always go to stderr, so `ff-cli fetch <id> > playlist.json` works). This is the starting point for `publish --replace`, which requires the stored `id`, `slug`, and `created`
   - Options: `-s, --server <index>`, `-o, --output <file>`. There is no `--key`: a fetch is a plain read and signs nothing
 - `unpublish <id-or-url>` – Delete a playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. Requires the signing key to be an owner of the stored playlist, and confirms before deleting
-  - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation), `-k, --key <privateKey>` (signs the delete authorization)
+  - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation), `-k, --key <privateKey>` (signs the delete authorization), `--key-file <path>` (the same key, read from a file)
 - `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
@@ -319,6 +333,13 @@ If you sign with `sign --key <privateKey>`, read that key's identity with
 and `build` need none of this: they declare the key and sign it as `curator` for you when a signing key
 is configured. An `apiKey` left over in an existing config is ignored.
 
+`--key-file <path>` is the same key from a file, on `sign`, `status`, `unpublish`, and
+`publish --replace` alike — so `ff-cli status --key-file signing.key` reports the identity
+`ff-cli sign --key-file signing.key` will assert. Prefer it: `--key` writes your private key into your
+shell history and exposes it in the process list for the length of the run, and a signing key that has
+been disclosed cannot be rotated out of a playlist that already names it. See
+[Where the signing key can come from](./CONFIGURATION.md#where-the-signing-key-can-come-from).
+
 ```json
 {
   "feedServers": [
@@ -336,7 +357,10 @@ is configured. An `apiKey` left over in an existing config is ignored.
 
 A feed's `PUT` and `DELETE` are owner-bound. Neither takes an API key, and neither is authorized by the
 document alone: both carry a short-lived **intent** that ff-cli signs in the `curator` role — with the
-configured `playlist.privateKey` by default, or with whatever `-k, --key` names for that one command. Only a key the *stored* playlist names in `curators[]` can authorize either one, which is
+configured `playlist.privateKey` by default, or with whatever `-k, --key` or `--key-file <path>` names
+for that one command (see
+[Where the signing key can come from](./CONFIGURATION.md#where-the-signing-key-can-come-from), which
+explains why the file is the safer of the two). Only a key the *stored* playlist names in `curators[]` can authorize either one, which is
 why `publish` refuses to create a playlist that carries no owner-role signature — such a document can be
 neither replaced nor deleted, ever.
 
@@ -363,10 +387,12 @@ you published — re-running `find` or `build` mints a fresh id, slug, and `crea
 playlist rather than a replacement. A `publish` without `--replace` is never silently upgraded to a
 replace; an id the feed already holds fails with a conflict, as before.
 
-The configured `playlist.privateKey` is only the default. `-k, --key` overrides it on both commands —
-for the intent signature and for the local ownership check alike — the way `ff-cli sign --key` and
-`ff-cli status --key` already do. A `--key` that is
-present but empty (what `--key "$SIGNING_KEY"` becomes when the variable is unset) is **rejected**, never
+The configured `playlist.privateKey` is only the default. `-k, --key` and `--key-file <path>` override
+it on both commands — for the intent signature and for the local ownership check alike — the way
+`ff-cli sign` and `ff-cli status` already accept them. Passing both is an error rather than a precedence
+rule, since a precedence rule silently ignores one of the two keys you supplied. A `--key` that is
+present but empty (what `--key "$SIGNING_KEY"` becomes when the variable is unset), and a `--key-file`
+that is missing, unreadable, or holds nothing, are all **rejected**, never
 treated as absent: falling back to the configured key would authorize the write under an identity you did
 not choose, and a delete cannot be taken back. `unpublish` derives the identity before it looks the
 playlist up, so a bad credential fails before you are asked to confirm anything, and it prints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",