@feralfile/cli 2.8.0 → 2.9.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.8.0",
+    "version": "2.9.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/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,6 +35,10 @@ 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) {
     // Follow a symlink to its target before replacing anything. rename() would
@@ -132,23 +143,6 @@ class OwnershipError extends Error {
         this.name = 'OwnershipError';
     }
 }
-/**
- * isSameFile reports whether two paths name the same file on disk.
- *
- * 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.
- */
-async function isSameFile(a, b) {
-    if (a === b) {
-        return true;
-    }
-    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.
  *
@@ -284,7 +278,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' +

package/dist/src/commands/publish.js

@@ -12,11 +12,49 @@ exports.publishCommand = new commander_1.Command('publish')
     .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)')
     .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
+        // 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'));
+            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'));
+            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.
+        let replaceKey;
+        if (options.replace) {
+            const { mutationSignerIdentity } = await import('../utilities/feed-mutation.js');
+            try {
+                replaceKey = mutationSignerIdentity(options.key, '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 +69,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: options.key !== undefined ? 'supplied' : 'configured',
+            })
             : await publishPlaylist(file, selection.url);
         if (result.success) {
             console.log(chalk_1.default.green(options.replace ? 'Replaced' : 'Published'));

package/dist/src/commands/sign.js

@@ -16,20 +16,88 @@ exports.signCommand = new commander_1.Command('sign')
     .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 {
         console.log(chalk_1.default.blue('\nSign playlist\n'));
         const result = await signPlaylistFile(file, options.key, 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}`));

package/dist/src/commands/unpublish.js

@@ -21,11 +21,43 @@ exports.unpublishCommand = new commander_1.Command('unpublish')
     .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)')
     .action(async (idOrUrl, options) => {
     try {
         console.log(chalk_1.default.blue('\nUnpublish playlist\n'));
         const { getFeedConfig } = await import('../config.js');
         const { unpublishPlaylist, fetchPlaylistForUnpublish } = await import('../utilities/playlist-unpublisher.js');
+        // Resolve the signing credential ONCE, before anything else touches the network or the operator,
+        // and carry the material itself forward.
+        //
+        // This runs before the server is chosen, not after. With several feeds configured, selecting one
+        // is a question put to the operator, and asking it only to reject the key afterwards spends their
+        // attention on a run that could never have completed. A credential the command already holds is
+        // checkable without asking anybody anything, so it is checked first.
+        //
+        // Deriving it here means a malformed or empty --key fails before the lookup and before the
+        // confirmation prompt — otherwise someone was shown a playlist, asked to approve destroying it,
+        // and only then told their key was unusable.
+        //
+        // Passing the resolved material on, rather than letting unpublishPlaylist resolve again, closes a
+        // narrower gap: the prompt can stay open indefinitely, and a second resolution would re-read
+        // config.json at send time. A config edited in that window would sign the delete under an
+        // identity other than the one the operator saw and approved — and a delete tombstones the id.
+        // 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.
+        const { mutationSignerIdentity } = await import('../utilities/feed-mutation.js');
+        let signerDidKey;
+        let signingKey;
+        try {
+            ({ privateKey: signingKey, didKey: signerDidKey } = mutationSignerIdentity(options.key, 'delete'));
+        }
+        catch (error) {
+            console.error(chalk_1.default.red('\nCannot sign the delete'));
+            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,
@@ -59,6 +91,7 @@ exports.unpublishCommand = new commander_1.Command('unpublish')
             }
             console.log(chalk_1.default.yellow(`  ${label}`));
             console.log(chalk_1.default.dim(`  Server: ${selection.url}`));
+            console.log(chalk_1.default.dim(`  Signing as: ${signerDidKey}`));
             console.log(chalk_1.default.dim('  This cannot be undone; the id is tombstoned and cannot be reused.'));
             console.log();
             const prompt = (0, prompt_1.createPrompt)();
@@ -70,7 +103,16 @@ exports.unpublishCommand = new commander_1.Command('unpublish')
                 return;
             }
         }
-        const result = await unpublishPlaylist(idOrUrl, selection.url);
+        // `Signing as` is printed on both paths, not only before the prompt: under -y it is the only
+        // record of which identity performed an irreversible delete, and it is what the assertion in the
+        // tests ties to the signature on the wire.
+        if (options.yes) {
+            console.log(chalk_1.default.dim(`  Signing as: ${signerDidKey}`));
+        }
+        const result = await unpublishPlaylist(idOrUrl, selection.url, {
+            privateKey: signingKey,
+            keySource: options.key !== undefined ? 'supplied' : 'configured',
+        });
         if (result.success) {
             console.log(chalk_1.default.green('Unpublished'));
             if (result.playlistId) {

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

@@ -25,12 +25,16 @@ exports.documentPayloadHash = documentPayloadHash;
 exports.signIntent = signIntent;
 exports.resolvePlaylistIdentifier = resolvePlaylistIdentifier;
 exports.fetchStoredPlaylist = fetchStoredPlaylist;
+exports.resolveMutationSigningKey = resolveMutationSigningKey;
+exports.mutationSignerIdentity = mutationSignerIdentity;
 exports.storedOwnerKeys = storedOwnerKeys;
 exports.storedOwnership = storedOwnership;
 exports.ownershipPreflight = ownershipPreflight;
 exports.describeFeedMutationError = describeFeedMutationError;
 exports.asPlaylist = asPlaylist;
 const axios_1 = __importDefault(require("axios"));
+const config_1 = require("../config");
+const signing_identity_1 = require("./signing-identity");
 // playlist-signer is still CommonJS; require keeps the interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { normalizeSigningKeyToBase64Pkcs8 } = require('./playlist-signer');
@@ -136,6 +140,53 @@ async function fetchStoredPlaylist(feedServerUrl, identifier) {
     }
     return stored;
 }
+/**
+ * Resolve the key that signs an owner-bound intent, honouring an explicit `--key`.
+ *
+ * **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
+ * as absent silently fell back to the configured key, so a delete meant to be authorized by one identity
+ * was authorized by another and tombstoned the playlist under it. There is no recovering from that: the
+ * id is retired. So anything the caller actually passed goes through validation and is rejected there;
+ * only `undefined` means "use the configured key".
+ *
+ * @param override - Value of `--key` exactly as the command received it
+ * @param action - Which mutation is being authorized, for the no-key-configured message
+ * @returns Key material for signing
+ * @throws Error when the override is empty, or when nothing is configured and none was given
+ */
+function resolveMutationSigningKey(override, action) {
+    if (override !== undefined) {
+        if (override.trim().length === 0) {
+            throw new Error('The --key value is empty. This usually means a shell variable did not expand ' +
+                '(for example --key "$SIGNING_KEY" with SIGNING_KEY unset). Refusing rather than falling ' +
+                'back to the configured key: a signature made by the wrong identity is not something a ' +
+                `${action} can be taken back from.`);
+        }
+        return override;
+    }
+    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.');
+    }
+    return configured;
+}
+/**
+ * Identity a mutation will sign under, resolved and validated together.
+ *
+ * Commands call this before doing anything else so a bad credential fails before any request — and, for
+ * `unpublish`, before the operator is asked to confirm a delete they could not have completed. The key
+ * material never appears in what comes back: only the `did:key` it derives to.
+ *
+ * @param override - Value of `--key` exactly as the command received it
+ * @param action - Which mutation is being authorized
+ * @returns The key material and the `did:key` it asserts
+ */
+function mutationSignerIdentity(override, action) {
+    const privateKey = resolveMutationSigningKey(override, action);
+    return { privateKey, didKey: (0, signing_identity_1.playlistSigningDidKey)(privateKey) };
+}
 /** Owner `did:key`s the stored playlist declares, in declaration order. */
 function storedOwnerKeys(stored) {
     const curators = Array.isArray(stored.curators) ? stored.curators : [];
@@ -179,13 +230,28 @@ async function storedOwnership(stored) {
         catch {
             // An entry that does not verify is not proof. It is also not this command's business to report:
             // a stale or tampered signature on someone else's key changes nothing about whether the
-            // configured key can act, and the answer below is derived from the set that survived.
+            // signing key can act, and the answer below is derived from the set that survived.
         }
     }
     return { declared, proven };
 }
+/** 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:';
+}
+/** 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>").`;
+}
 /**
- * Refuse locally when the configured key cannot authorize a mutation on the stored playlist.
+ * Refuse locally when the signing key cannot authorize a mutation on the stored playlist.
  *
  * The feed's own answer to every case here is a bare `403 forbidden`, which says nothing about which
  * identity was offered, which ones would have worked, or whether the problem is the declaration or the
@@ -194,11 +260,11 @@ async function storedOwnership(stored) {
  * declaration is right and the signature that would back it was never made.
  *
  * @param stored - The playlist as the feed serves it
- * @param signerDidKey - `did:key` the configured signing key will assert
+ * @param signerDidKey - `did:key` the signing key will assert
  * @param action - Which mutation is being authorized, for the wording
- * @returns A failure to report, or `null` when the configured key is a proven owner.
+ * @returns A failure to report, or `null` when the signing key is a proven owner.
  */
-async function ownershipPreflight(stored, signerDidKey, action) {
+async function ownershipPreflight(stored, signerDidKey, action, keySource = 'configured') {
     const { declared, proven } = await storedOwnership(stored);
     if (proven.includes(signerDidKey)) {
         return null;
@@ -213,7 +279,7 @@ async function ownershipPreflight(stored, signerDidKey, action) {
             error: `This playlist declares no owners, so no key can ${verb} it.`,
             message: `The feed derives ownership from the stored document's curators[], and this one is empty — the\n` +
                 `  shape a playlist published without an owner-role signature is frozen in. No signature can\n` +
-                `  authorize a ${verb}, including yours (${signerDidKey}).\n` +
+                `  authorize a ${verb}, including this one (${signerDidKey}).\n` +
                 `  Nothing can repair it: the owner set is immutable, and only an owner could change it. Publish\n` +
                 `  a corrected playlist under a new id instead.`,
         };
@@ -240,30 +306,31 @@ async function ownershipPreflight(stored, signerDidKey, action) {
     // it is simply not the one configured here.
     if (declared.includes(signerDidKey)) {
         return {
-            error: `Your key is declared on this playlist but never signed it as ${exports.OWNER_ROLE}, so it cannot ${verb} it.`,
+            error: `This key is declared on this playlist but never signed it as ${exports.OWNER_ROLE}, so it cannot ${verb} it.`,
             message: `The feed treats a declared key as an owner only once it has also signed the stored document\n` +
-                `  as "${exports.OWNER_ROLE}". Yours is named in curators[] but carries no such signature, so an intent\n` +
-                `  signed with it would be refused.\n` +
-                `  Your configured identity:\n` +
+                `  as "${exports.OWNER_ROLE}". This one is named in curators[] but carries no such signature, so an\n` +
+                `  intent signed with it would be refused.\n` +
+                `  ${identityLabel(keySource)}\n` +
                 `    ${signerDidKey}\n` +
                 `  Keys that have proved ownership:\n` +
                 `${proven.map((key) => `    ${key}`).join('\n')}\n` +
-                `  Point playlist.privateKey at one of those (confirm any key's identity with\n` +
-                `  "ff-cli status --key <private key>"). Your own declaration cannot be upgraded after the fact:\n` +
-                `  the proof would have to be a signature over the document as published.`,
+                `${retryAdvice(keySource, proven.length > 1)}\n` +
+                `  The declaration cannot be upgraded after the fact: the proof would have to be a signature\n` +
+                `  over the document as published.`,
         };
     }
+    const source = keySource === 'supplied' ? 'The key you passed with --key is' : 'The configured signing key is';
     return {
-        error: `The configured signing key is not an owner of this playlist, so it cannot ${verb} it.`,
+        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` +
             `  authorize a ${verb}; the feed derives ownership from the stored document, not from a local copy.\n` +
-            `  Your configured identity:\n` +
+            `  ${identityLabel(keySource)}\n` +
             `    ${signerDidKey}\n` +
             `  Keys that have proved ownership:\n` +
             `${proven.map((key) => `    ${key}`).join('\n')}\n` +
-            `  Point playlist.privateKey at a key listed above (confirm any key's identity with\n` +
-            `  "ff-cli status --key <private key>"). Ownership cannot be granted after the fact: the owner set\n` +
-            `  is immutable, so a playlist signed by the wrong key stays that way.`,
+            `${retryAdvice(keySource, proven.length > 1)}\n` +
+            `  Ownership cannot be granted after the fact: the owner set is immutable, so a playlist signed\n` +
+            `  by the wrong key stays that way.`,
     };
 }
 /** Feed error code carried in an error response body, when there is one. */
@@ -290,8 +357,17 @@ function feedErrorDetail(error) {
  *
  * The codes handled are exactly those dp1-feed-v2 documents for these routes; anything else falls
  * through with the server's own words rather than being guessed at.
+ *
+ * `keySource` matters here for the same reason it does locally: two of these messages talk about the
+ * signing identity, and calling it "configured" when the operator passed `--key` describes a file this
+ * run never read. Worse, after a 403 it reads as though the override had been dropped — which is
+ * precisely the doubt an operator should not be left with when their key was used and refused.
+ *
+ * @param error - The failure thrown by the request
+ * @param action - Which mutation was attempted
+ * @param keySource - Where the signing identity came from
  */
-function describeFeedMutationError(error, action) {
+function describeFeedMutationError(error, action, keySource = 'configured') {
     const axiosError = error;
     const status = axiosError.response?.status;
     const code = feedErrorCode(axiosError);
@@ -305,19 +381,26 @@ function describeFeedMutationError(error, action) {
         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` +
-                `  This usually means no signing key is configured: run "ff-cli status" to check, and\n` +
-                `  "ff-cli setup" to generate one.${suffix}`,
+                (keySource === 'supplied'
+                    ? `  The key passed with --key 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`) +
+                `  ${suffix.trim() || 'The feed gave no further detail.'}`,
         };
     }
-    // A 403 that reaches here has already passed the local ownership proof: the configured key was found
+    // A 403 that reaches here has already passed the local ownership proof: the key that signed was found
     // in the stored curators[] with a valid curator-role signature over the stored bytes. Repeating "your
     // key is not declared" would therefore be a lie, and it is the wrong place to send someone — the
     // 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';
         return {
             error: `${verb} refused by the feed: it did not accept the signing key as an owner.`,
-            message: `The local check disagreed — the configured key is named in the stored playlist's curators[]\n` +
+            message: `The local check disagreed — ${which} named in the stored playlist's curators[]\n` +
                 `  and carries a valid "${exports.OWNER_ROLE}" signature over the stored document — so this is the feed's\n` +
                 `  own judgement, not a missing declaration.\n` +
                 (action === 'replace'

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

@@ -8,9 +8,7 @@ exports.replacePlaylist = replacePlaylist;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = __importDefault(require("fs"));
 const playlist_verifier_1 = require("./playlist-verifier");
-const config_1 = require("../config");
 const feed_mutation_1 = require("./feed-mutation");
-const signing_identity_1 = require("./signing-identity");
 /**
  * Publish a verified playlist to a DP-1 feed server
  *
@@ -126,11 +124,16 @@ async function replacePlaylist(filePath, feedServerUrl, options = {}) {
             message: 'A replace targets an existing resource by its id. Publish it without --replace to create it.',
         };
     }
+    // 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');
+    // 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;
     let signerDidKey;
     try {
-        privateKey = resolveIntentSigningKey(options.privateKey);
-        signerDidKey = (0, signing_identity_1.playlistSigningDidKey)(privateKey);
+        ({ privateKey, didKey: signerDidKey } = (0, feed_mutation_1.mutationSignerIdentity)(options.privateKey, 'replace'));
     }
     catch (error) {
         return { success: false, error: error.message };
@@ -140,7 +143,7 @@ async function replacePlaylist(filePath, feedServerUrl, options = {}) {
         stored = await (0, feed_mutation_1.fetchStoredPlaylist)(feedServerUrl, documentId);
     }
     catch (error) {
-        const described = (0, feed_mutation_1.describeFeedMutationError)(error, 'replace');
+        const described = (0, feed_mutation_1.describeFeedMutationError)(error, 'replace', keySource);
         const missing = error.response?.status === 404;
         return {
             success: false,
@@ -161,7 +164,7 @@ async function replacePlaylist(filePath, feedServerUrl, options = {}) {
     if (mismatch) {
         return { success: false, ...mismatch, feedServer: feedServerUrl };
     }
-    const ownership = await (0, feed_mutation_1.ownershipPreflight)(stored, signerDidKey, 'replace');
+    const ownership = await (0, feed_mutation_1.ownershipPreflight)(stored, signerDidKey, 'replace', keySource);
     if (ownership) {
         return { success: false, ...ownership, feedServer: feedServerUrl };
     }
@@ -189,7 +192,7 @@ async function replacePlaylist(filePath, feedServerUrl, options = {}) {
     catch (error) {
         return {
             success: false,
-            ...(0, feed_mutation_1.describeFeedMutationError)(error, 'replace'),
+            ...(0, feed_mutation_1.describeFeedMutationError)(error, 'replace', keySource),
             feedServer: feedServerUrl,
         };
     }
@@ -220,7 +223,11 @@ function replaceIdentityMismatch(playlist, stored) {
     }
     const documentOwners = (0, feed_mutation_1.storedOwnerKeys)(playlist);
     const owners = (0, feed_mutation_1.storedOwnerKeys)(stored);
-    if (documentOwners.join('') !== owners.join('')) {
+    // Compared element-wise rather than by joining on a separator: the owner set is an ordered list
+    // of opaque strings, and any separator is a guess about what cannot appear inside one.
+    const sameOwners = documentOwners.length === owners.length &&
+        documentOwners.every((key, index) => key === owners[index]);
+    if (!sameOwners) {
         differences.push(`    curators: stored [${owners.join(', ')}], document [${documentOwners.join(', ')}]`);
     }
     if (differences.length === 0) {
@@ -254,24 +261,6 @@ function sameInstant(left, right) {
     const b = Date.parse(right);
     return Number.isFinite(a) && Number.isFinite(b) && a === b;
 }
-/**
- * resolveIntentSigningKey resolves the key that signs the authorization intent.
- *
- * The intent is signed separately from the document, and by whoever is running the command: the document
- * may legitimately carry several curators' signatures, while the intent proves that *this* operator holds
- * one of those keys right now.
- */
-function resolveIntentSigningKey(override) {
-    if (override && override.trim().length > 0) {
-        return override;
-    }
-    const configured = (0, config_1.getPlaylistConfig)().privateKey;
-    if (!configured) {
-        throw new Error('No playlist signing key is configured. A replace is authorized by a signed intent, so one is ' +
-            'required: run "ff-cli setup" or set playlist.privateKey in config.json.');
-    }
-    return configured;
-}
 /**
  * readPlaylistFile reads and parses a playlist document from disk.
  *