@feralfile/cli 2.9.0 → 2.10.1

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

@@ -64,6 +64,9 @@ npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --publish
 
 # Build, play on a named device, and skip interactive prompts
 npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play -d "Living Room Display" -y
+
+# -y alone also plays (the scripted default); add --no-play to build and save without casting
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 -y --no-play
 ```
 
 OpenSea and Verse accept both item and collection/series URLs:
@@ -789,9 +792,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 +807,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 +850,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.