@feralfile/cli 2.8.0 → 2.10.0

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. 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:
@@ -142,7 +196,9 @@ No credential is configured for any of these. The feed has no API key: every wri
 signatures in the request body, and an `apiKey` left in an existing config is ignored.
 
 `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. A plain
+--replace` and `unpublish`, which sign the owner-bound intent that authorizes the write. Both accept
+`-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

@@ -546,8 +546,9 @@ documents you sign by hand, where `playlist.role` (default `agent`) decides the
 ## Replace or Delete a Published Playlist
 
 A feed's `PUT` and `DELETE` are **owner-bound**, and neither accepts an API key. Both carry a short-lived
-signed **intent** — `ff-cli` builds it, signs it with the configured key in the `curator` role, and sends
-it alongside (replace) or as (delete) the request body. Only a key the **stored** playlist names in
+signed **intent** — `ff-cli` builds it, signs it in the `curator` role with the configured
+`playlist.privateKey` (or with `-k, --key` when you name one for that command), and sends it alongside
+(replace) or as (delete) the request body. Only a key the **stored** playlist names in
 `curators[]` can authorize either. This is the whole reason `publish` refuses a document with no
 owner-role signature: once such a playlist is created it can never be replaced or deleted.
 
@@ -588,6 +589,14 @@ If you edited this playlist after it was signed, the existing signatures no long
 Signing fresh drops the feed's entry along with the curator's, which is correct: it covers the pre-edit
 content too, and the feed appends a new one of its own after it verifies the replacement.
 
+**On a co-curated playlist this drops the other curators' signatures too.** The command verifies every
+discarded entry against the document as it now stands and names each one, so you can see whose
+signatures will not be on what you publish. Entries that still verify — all of them, if you have not
+actually edited anything — are reported as removed; keep the previous file if you want them back.
+Entries that do not verify are reported as exactly that, with no explanation attached: this command sees
+only the document as it stands, so it cannot tell a changed document from a signature that was never
+valid.
+
 ```
 $ ff-cli sign playlist.json -r curator --replace-signatures
 
@@ -596,10 +605,130 @@ Sign playlist
 ✓ Playlist signed and saved to: /path/to/playlist.json
 
 Playlist signed
-  Replaced 2 existing signatures
+  Replaced 3 existing signatures:
+    - a signature claiming your key (curator, ...Dy8sokwC) — removed; could not be verified against this document
+    - another key's signature (curator, ...L5ufrpW3) — removed; could not be verified against this document
+    - another key's signature (feed, ...1Rq7Lzik) — removed; could not be verified against this document
+  3 other signatures could not be verified against this document:
+    ...Dy8sokwC (curator) — claims your key, unverified
+    ...L5ufrpW3 (curator)
+    ...1Rq7Lzik (feed)
+  That is consistent with the content having changed since they were made, and
+  equally with their never having been valid — this command only has the document
+  as it stands, so it cannot tell which. If you want those signatures on what you
+  publish, their holders have to sign this document; signing appends, so they can
+  add to this file without disturbing yours.
+  A feed appends its own signature again after it verifies a replacement.
+  Signatures: 1
+```
+
+**Your own earlier entry is in that list, and named as a claim rather than as yours.** It was made over
+the content before the edit, so it no longer verifies — and an entry that does not verify has not
+established whose it is. Reading a `kid` as proof of authorship is how a forged entry would hide behind
+your identity, so the command says what it checked: this signature claims your key, and could not be
+confirmed. On an unedited document the same entry verifies and is reported plainly as replaced.
+
+Four things that report deliberately does **not** say.
+
+It does not call an entry *void*. That would assert it verified against the previous content and no
+longer does — and the previous content was edited in place, so it exists nowhere by the time `sign`
+runs. A failed verification is equally consistent with an edit, with a tampered entry, and with one
+that was never valid; the command reports what it checked and offers both explanations.
+
+It does not treat `role: "feed"` as the feed's own. Any key can emit that role and the CLI holds no
+feed identity to check a `kid` against. That a feed re-appends its signature after verifying a
+replacement is a general fact, printed as one, not a claim about the entry above it.
+
+It does not rewrite anyone's role. `agent`, `institution` and `licensor` are valid DP-1 roles, so each
+entry is named with the role it actually carries.
+
+It does not credit an unverified entry to the key it names — not even to yours. Attribution follows
+verification, never the other way round.
+
+A flat legacy `signature` gets its own line, because it carries no `kid` and no `role` and the
+multi-signature verifier has nothing to check it with:
+
+```
+    - a legacy flat signature (no kid, no role) — removed; not checkable here
+  A legacy flat signature carries no kid or role, so nothing here can judge it.
+```
+
+Running the flag on a document you have **not** edited is a different situation, because nothing was
+invalidated — the signing payload excludes `signatures`, so the discarded entries still cover the
+content. **If any of them belongs to another key, an in-place run refuses:**
+
+```
+$ ff-cli sign playlist.json -r curator --replace-signatures
+
+Sign playlist
+
+Sign failed: This would discard 1 still-valid signature from other keys. Write the result elsewhere so the original stays:
+    ff-cli sign playlist.json -r curator --replace-signatures --output <new file>
+```
+
+Only its holder could make that signature again, so overwriting the one file that carries it costs
+something this command cannot restore. Writing elsewhere keeps the original exactly where it is:
+
+```
+$ ff-cli sign playlist.json -r curator --replace-signatures -o out.json
+
+Sign playlist
+
+✓ Playlist signed and saved to: /path/to/out.json
+
+Playlist signed
+  Replaced 2 existing signatures:
+    - your own earlier signature (curator, ...XppfYVjB) — replaced by this signing
+    - another key's signature (curator, ...UNFmeU8D) — removed; still valid over this content
+  1 other signature still verified over this content and was removed anyway.
+  Your input file is untouched, so it remains valid there.
+  A feed appends its own signature again after it verifies a replacement.
   Signatures: 1
 ```
 
+The refusal is narrow: it is about what cannot be recovered, not about how many signatures go. An
+in-place run still proceeds when the only entries dropped are **your own** — sign again to add any of
+them back — or ones that **no longer verify**, which the input could not restore either.
+
+**`sign` overwrites only a document it has read.** Before writing, it reads the destination back and
+compares it with the document being signed. Equal means this is that document, wherever the name now
+points, and the rule above applies to it. Different means the destination holds something never
+inspected, and the run is refused:
+
+```
+$ ff-cli sign playlist.json -r curator --replace-signatures -o notes.json
+
+Sign failed: notes.json already exists and is not the playlist being signed; choose a new name, or pass --force to overwrite it.
+```
+
+`--force` allows it, and the report names what it replaced. This is a content rule, not an identity
+one: no comparison of paths or inodes can promise that the file about to be truncated is the file that
+was read, because a name can be re-pointed between any two system calls — but comparing the bytes
+through the descriptor being written can. A destination that already exists needs read permission for
+that reason.
+
+**It narrows the race; it does not close it.** The read and the overwrite are two operations, and an
+editor writing in the same instant can still lose its change — every tool that edits a file in place
+carries this, and nothing in userspace removes it portably. A fresh `--output` name is the write that
+cannot collide, because nothing is there to lose.
+
+If the destination turns out to hold the **same** document as the input — a copy taken with `cp`, say —
+it is treated exactly as an in-place run, because without file identity a copy and a second name for the
+input are the same thing. So the same narrow rule decides it: the run is refused **only when it would
+discard a still-valid signature from another key**. That is the whole of what the refusal protects, and
+a copy carrying only your own signatures, or only ones that no longer verify, is simply written — the
+input is a different file and is not touched either way.
+
+When it does refuse, `--force` deliberately does **not** override it: force is for replacing a different
+document, never for destroying a signature only its holder could make again. Delete the copy and re-run,
+or pick another `--output` name; a name that does not exist is written with no check at all.
+
+The rule holds on every platform and assumes nothing about the filesystem. An earlier version kept a
+copy of the input instead; that requires reproducing the source's access, which is not portable — POSIX
+ACLs grant what mode bits do not describe, macOS extended ACLs are not constrained by the mask, and
+Windows mode bits constrain nothing — so every implementation of it was a way for the copy to disclose
+the document. Refusing needs none of that.
+
 Appending stays the default, because it is right whenever the content has not changed — a second curator
 co-signing an unedited playlist keeps the first endorsement, and the payload hash excludes `signatures`
 so the earlier entry stays valid.
@@ -657,6 +786,71 @@ Without `-y`, `unpublish` shows the title and the server and asks, defaulting to
 tombstones the id: the playlist cannot be restored, and a later publish naming that id is refused. Build
 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` 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>
+ff-cli publish playlist.json --replace -s 0 --key <private key for a stored owner>
+```
+
+`ff-cli status --key <private key>` reports which identity a key carries, which is how you check it
+against the `Keys that have proved ownership:` list in a refusal. `unpublish` also prints `Signing as:`, both in its
+confirmation and under `-y`, so the identity that performs an irreversible delete is always in the
+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.
+
+#### 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:
+
+```
+$ ff-cli unpublish <id> -y --key "$SIGNING_KEY"     # variable unset
+
+Cannot sign the delete
+  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
+  delete can be taken back from.
+```
+
+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
 
 A key counts as an owner only when the **stored** playlist names it in `curators[]` **and** carries its
@@ -700,17 +894,23 @@ Unpublish playlist
 Unpublish failed
   The configured signing key is not an owner of this playlist, so it cannot delete it.
 
-Only a key the stored playlist names in curators[] can authorize a delete; the feed derives
-  ownership from the stored document, not from a local copy.
+Only a key the stored playlist names in curators[] AND that signed it as "curator" can
+  authorize a delete; the feed derives ownership from the stored document, not from a local copy.
   Your configured identity:
     did:key:z6MkoX8i2dynyvLh4hUHZt8b42q9uAwwCWxM4NSX4YDfMtaC
-  Stored owners:
+  Keys that have proved ownership:
     did:key:z6MkoDkq5YXsFGXPiD6HDUVfze5mvhU5QF4hTy59pVVPYg82
-  Point playlist.privateKey at a key listed above (confirm any key's identity with
-  "ff-cli status --key <private key>"). Ownership cannot be granted after the fact: the owner set
-  is immutable, so a playlist signed by the wrong key stays that way.
+  Point playlist.privateKey at the key listed above, or pass one for this run with --key (confirm
+  any key's identity with "ff-cli status --key <private key>").
+  Ownership cannot be granted after the fact: the owner set is immutable, so a playlist signed
+  by the wrong key stays that way.
 ```
 
+That run used the configured key, so the refusal names it as configured. Had it been given
+`--key`, the same refusal would name that key instead and the retry line would read
+`Run it again with an owner key: --key <private key for the key listed above>` — a refusal always
+points at the key the command actually used, never at a config file the run never read.
+
 Ownership cannot be granted after the fact — the owner set is immutable, and only an owner could change
 it — so the only fix is to hold a declared key. A playlist whose stored `curators[]` is **empty** is a
 harder case with the same shape: nobody owns it, no signature can ever authorize a write, and `ff-cli`

package/docs/PROJECT_SPEC.md

@@ -191,8 +191,11 @@ accepts an API key. Both therefore carry a signed intent — `{ action, target:
 created, signatures }`, with a `payloadHash` for replace — whose `created` must fall inside the feed's
 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 configured key to be both named in the stored `curators[]`
-and the signer of a cryptographically valid `curator`-role signature over that stored document. Being
+`GET`s the stored playlist and requires the signing key — the configured `playlist.privateKey` unless
+`-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
 declaration — the one thing not wrong with it. The three local refusals are therefore distinct: no
@@ -203,6 +206,35 @@ create a document whose declared curator did not sign in the `curator` role: tha
 recoverable and the resulting stored playlist would not be. A delete tombstones the id, so the operation
 is final and the id is not reusable.
 
+A `--replace-signatures` run writing over its own input refuses when it would discard a still-valid
+signature from another key. Only that key's holder could produce it again, so overwriting the one file
+that carries it destroys something the command cannot restore; `--output` writes the result elsewhere
+and leaves the original in place. The refusal is scoped to what is unrecoverable — an in-place run still
+proceeds when the entries dropped are the signer's own, or no longer verify.
+
+Refusal rather than a preserved copy is deliberate. A copy has to reproduce the source's access, and no
+portable means of doing so exists: POSIX ACLs grant what the mode bits do not describe, macOS extended
+ACLs are not constrained by the mask, and Windows mode bits constrain nothing at all. Every version of
+that copy was a way to disclose the document. The refusal assumes nothing about the filesystem, so the
+invariant — a still-valid endorsement is never overwritten in place — holds identically everywhere.
+
+Which document a destination holds is decided by content, not by file identity. The destination is read
+back through the descriptor that will write it and compared with the document being signed; a
+destination holding anything else is refused unless `--force` says otherwise. Identity cannot answer
+this — a name can be re-pointed between any two system calls, so no comparison of paths or inodes
+describes what a later write will land on — while the bytes behind a descriptor can. It narrows the
+race and does not close it: the read and the overwrite are two operations, and an editor writing in the
+same instant can still lose its change, as with any tool that edits in place. A `--output` name that
+does not yet exist is the write that cannot collide.
+
+A destination holding the *same* document as the input is treated as an in-place run, since without
+identity a copy and a second name for the input are indistinguishable — and so the same narrow rule
+applies: it is refused only when the run would discard a still-valid signature from another key. A copy
+carrying only the signer's own entries, or only unverifiable ones, is written like any other
+destination; the input is a separate file and is untouched. Where the refusal does fire, `--force` does
+not reach it by design: force authorizes replacing a different document, never destroying a signature
+only its holder could reproduce.
+
 Editing a published playlist therefore has a required shape: `fetch` the stored document, change it,
 re-sign with `sign --replace-signatures`, then `publish --replace`. `fetch` exists because every other
 way of producing that starting file is wrong: `find` and `build` mint a new identity, and `verify` only
@@ -362,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.