@feralfile/cli 2.8.0 → 2.10.0

package/dist/package.json

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichCommand = void 0;
+exports.writePlaylistAtomically = writePlaylistAtomically;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
@@ -11,6 +12,12 @@ const crypto_1 = require("crypto");
 const path_1 = require("path");
 const enrich_playlist_1 = require("../utilities/enrich-playlist");
 const playlist_verifier_1 = require("../utilities/playlist-verifier");
+// Rename semantics, not inode identity. This command writes a temp file and renames it over the
+// destination, and rename() replaces a directory ENTRY: onto a hard link it repoints that one name and
+// leaves the input's own name on the untouched original inode. So a hard-link -o is a genuinely
+// distinct output here, and treating it as in-place makes the stale-input guard below refuse a write
+// that was never unsafe. The signer's direct-write path needs the opposite predicate; see same-file.ts.
+const same_file_1 = require("../utilities/same-file");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { resolveTokenBatch } = require('../utilities/nft-indexer');
 /**
@@ -28,32 +35,67 @@ const { resolveTokenBatch } = require('../utilities/nft-indexer');
  * The temporary file is created alongside the destination rather than in the
  * system temp directory: rename is only atomic within a filesystem, and those
  * are not guaranteed to be the same one.
+ *
+ * Exported for tests: whether a destination counts as the input depends on this
+ * 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);
             }
@@ -77,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
@@ -103,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;
     }
 }
@@ -126,28 +200,50 @@ 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';
     }
 }
 /**
- * isSameFile reports whether two paths name the same file on disk.
+ * 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.
  *
- * Compares resolved paths rather than the strings the caller typed, so
- * `-o ./playlist.json` against `playlist.json`, and a symlink against its
- * target, are recognized as the in-place case they are.
+ * 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 isSameFile(a, b) {
-    if (a === b) {
-        return true;
+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');
     }
-    const [left, right] = await Promise.all([
-        fs_1.promises.realpath(a).catch(() => null),
-        fs_1.promises.realpath(b).catch(() => null),
-    ]);
-    return left !== null && left === right;
 }
 /**
  * syncDirectory flushes a directory entry so a rename survives power loss.
@@ -158,9 +254,9 @@ async function isSameFile(a, b) {
  * 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();
         }
@@ -284,7 +380,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
             if (!after.valid) {
                 reportInvalid('Enrichment produced an invalid playlist:', after);
             }
-            const replaced = await writePlaylistAtomically(destination, JSON.stringify(result.playlist, null, 2), (await isSameFile(file, destination)) ? originalDigest : undefined);
+            const replaced = await writePlaylistAtomically(destination, JSON.stringify(result.playlist, null, 2), (await (0, same_file_1.isSameEntryForRename)(destination, file)) ? originalDigest : undefined);
             if (!replaced) {
                 console.error(chalk_1.default.red('\nThat playlist changed while the lookup ran.'));
                 console.error(chalk_1.default.dim('  Enrichment was computed from the earlier version, so writing it\n' +
@@ -319,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,16 +7,69 @@ 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 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.
+        //
+        // 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 ${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'));
         const { getFeedConfig } = await import('../config.js');
         const { publishPlaylist, replacePlaylist } = await import('../utilities/playlist-publisher.js');
+        // Validate the signing credential before the server is chosen, for a replace.
+        //
+        // Selecting between several configured feeds is a question put to the operator; asking it and
+        // only then rejecting their key spends their attention on a run that could never have completed.
+        // The credential is already in hand, so it is checked without asking anybody anything.
+        //
+        // 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 {
+                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'));
+                console.error(chalk_1.default.red(`  ${error.message}`));
+                console.log();
+                process.exit(1);
+            }
+        }
         const feedConfig = getFeedConfig();
         const selection = await (0, feed_server_1.selectFeedServer)(feedConfig.baseURLs, { serverArg: options.server });
         if (!selection.ok) {
@@ -31,7 +84,11 @@ exports.publishCommand = new commander_1.Command('publish')
         // loudly on a duplicate id, a replace overwrites a published document — and an operator who typed
         // neither flag meant the safe one.
         const result = options.replace
-            ? await replacePlaylist(file, selection.url)
+            ? await replacePlaylist(file, selection.url, {
+                // The material resolved above, so the identity validated here is the one that signs.
+                privateKey: replaceKey,
+                keySource,
+            })
             : await publishPlaylist(file, selection.url);
         if (result.success) {
             console.log(chalk_1.default.green(options.replace ? 'Replaced' : 'Published'));

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,23 +14,97 @@ 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,
         });
         if (result.success) {
             console.log(chalk_1.default.green('\nPlaylist signed'));
-            // Report the discard explicitly. Dropping an entry is a real change to the document —
-            // someone else's endorsement may have been in it — and staying silent would make a fresh
-            // sign indistinguishable from an appending one.
-            if (result.droppedSignatures > 0) {
-                const plural = result.droppedSignatures === 1 ? '' : 's';
-                console.log(chalk_1.default.dim(`  Replaced ${result.droppedSignatures} existing signature${plural}`));
+            // Name the casualty. --force overwrote a document this command never read, and the only
+            // record that it existed is now this line.
+            if (result.overwroteAnother) {
+                console.log(chalk_1.default.yellow(`  Overwrote a different document at ${result.outputPath} (--force)`));
+            }
+            // Name every discarded entry, and say only what was actually checked.
+            //
+            // Your own earlier signature is free: this command replaces it. For the rest the only
+            // establishable fact is whether the entry verifies against the document as it stands —
+            // "void" would assert it verified against the PREVIOUS content, which was edited in place
+            // and exists nowhere by the time this runs. A failed verification is equally consistent
+            // with an edit, with a tampered entry, and with one that was never valid, so it is reported
+            // as unverified rather than diagnosed.
+            //
+            // Roles are carried through rather than assumed: a document may hold `agent`,
+            // `institution`, or `licensor` entries, and a `feed` role is not special-cased because any
+            // key can emit one and this CLI has no feed identity to check a kid against.
+            const dropped = result.dropped ?? [];
+            if (dropped.length > 0) {
+                const plural = dropped.length === 1 ? '' : 's';
+                console.log(chalk_1.default.dim(`  Replaced ${dropped.length} existing signature${plural}:`));
+                for (const entry of dropped) {
+                    console.log(chalk_1.default.dim(`    - ${entry.label}`));
+                }
+                // Everything this run did not supersede. A same-key entry in another role belongs here:
+                // the fresh signature asserts a different role, so that entry is gone and not reinstated.
+                const others = dropped.filter((entry) => entry.kind !== 'replaced' && entry.checkable);
+                const stillValid = others.filter((entry) => entry.verified);
+                const unverified = others.filter((entry) => !entry.verified);
+                if (stillValid.length > 0) {
+                    const noun = stillValid.length === 1 ? 'signature' : 'signatures';
+                    const it = stillValid.length === 1 ? 'it' : 'them';
+                    // Say where they still exist. Only two cases reach here: an --output run, where the
+                    // input is untouched and holds them; or an in-place run whose still-valid entries are
+                    // all this key's own in another role, which nobody else has to be asked for. An
+                    // in-place run that would drop another key's still-valid signature never gets this far
+                    // — it is refused, because that file is the only copy and its holder is the only one
+                    // who could make another.
+                    const where = result.inPlace
+                        ? `  ${it.charAt(0).toUpperCase()}${it.slice(1)} ${stillValid.length === 1 ? 'was' : 'were'} made by your own key in another role; sign again to add back any you still want.`
+                        : `  Your input file is untouched, so ${it} ${stillValid.length === 1 ? 'remains' : 'remain'} valid there.`;
+                    console.log(chalk_1.default.yellow(`  ${stillValid.length} other ${noun} still verified over this content and ` +
+                        `${stillValid.length === 1 ? 'was' : 'were'} removed anyway.\n` +
+                        where));
+                }
+                if (unverified.length > 0) {
+                    const noun = unverified.length === 1 ? 'signature' : 'signatures';
+                    // Stated as what was observed, with both explanations, and no instruction that would
+                    // only make sense under one of them.
+                    console.log(chalk_1.default.yellow(`  ${unverified.length} other ${noun} could not be verified against this document:`));
+                    for (const entry of unverified) {
+                        const who = entry.kid ? `...${entry.kid.slice(-8)}` : 'unknown key';
+                        // "claims" is not decoration: an unverified entry carrying this key's kid has not
+                        // established whose it is, and reading it as yours is how a forgery would hide.
+                        const mine = entry.sameKey
+                            ? ' — your own key'
+                            : entry.claimsSigningKey
+                                ? ' — claims your key, unverified'
+                                : '';
+                        console.log(chalk_1.default.yellow(`    ${who}${entry.role ? ` (${entry.role})` : ''}${mine}`));
+                    }
+                    console.log(chalk_1.default.yellow(`  That is consistent with the content having changed since they were made, and\n` +
+                        `  equally with their never having been valid — this command only has the document\n` +
+                        `  as it stands, so it cannot tell which. If you want those signatures on what you\n` +
+                        `  publish, their holders have to sign this document; signing appends, so they can\n` +
+                        `  add to this file without disturbing yours.`));
+                }
+                if (dropped.some((entry) => !entry.checkable)) {
+                    console.log(chalk_1.default.yellow(`  A legacy flat signature carries no kid or role, so nothing here can judge it.`));
+                }
+                // The general fact, never a claim about a specific entry above.
+                console.log(chalk_1.default.dim(`  A feed appends its own signature again after it verifies a replacement.`));
             }
             if (Array.isArray(result.playlist?.signatures)) {
                 console.log(chalk_1.default.dim(`  Signatures: ${result.playlist.signatures.length}`));