@feralfile/cli 2.8.0 → 2.9.0

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,42 @@ 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`, 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`:
+
+```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.
+
+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.
+
+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` 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.
+
 ### 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 +865,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,9 @@ 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` overrides it for that command — 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 +204,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

package/docs/README.md

@@ -97,8 +97,11 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
 - `validate <file-or-url>` – Validate playlist structure only
 - `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
 - `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
-  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`, `--replace-signatures`
+  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`, `--replace-signatures`, `--force`
+  - **It overwrites only a document it has read.** Before writing, the destination is read back and compared with the document being signed; if it holds something else, the run is refused rather than destroying a file the command never inspected. `--force` allows that overwrite, and the report names the file it replaced. A destination holding the *same* document — a copy of the input — is treated as an in-place run, so it is refused only when it would discard a still-valid signature from another key, and `--force` does not override that one. The read and the overwrite are not atomic, so an editor writing in the same instant can still lose its change, as with any in-place tool — a fresh `--output` name is the write that cannot collide. A destination that already exists needs read permission
   - Signing **appends** by default, so repeated runs accumulate endorsements. That is only correct while the signed content is unchanged: editing a signed playlist moves bytes the earlier signatures cover, and the envelope check then refuses to write the result. `--replace-signatures` discards every existing entry — including a feed's own co-signature — and signs the document as it stands. It is the required step before `publish --replace`
+  - **An in-place run refuses when it would discard a still-valid signature from another key**, since only its holder could make that signature again: write the result elsewhere with `-o, --output`, which leaves the original where it is. The refusal is about what cannot be recovered — an in-place run still proceeds when the only entries dropped are your own, or ones that no longer verify
+  - `--replace-signatures` names each discarded entry by role and the last 8 characters of its `kid`, and verifies it against the document as it now stands. Your own earlier signature is replaced by the same run. Another key's entry that **still verifies** — which is every entry when the content was not edited, since the signing payload excludes `signatures` — is reported as removed; keep the previous file if you want it back. An entry that does **not** verify is reported as exactly that and no more: the command has only the document as it stands, so it cannot tell an edit from an entry that was never valid, and it does not guess. Roles are carried through as found (`agent`, `institution` and `licensor` are as valid as `curator`), and a flat legacy `signature` is reported as not checkable, since it carries no key or role at all
 - `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `verify` before sending; only the CLI-synthesized media URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
   - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
 - `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
@@ -110,11 +113,12 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - DP-1 `evm` names a chain family rather than a network, so those items are skipped unless `--assume-ethereum` asserts which one they are. Getting that wrong attaches another artwork's metadata
   - Options: `-o, --output <file>`, `--force` (replace existing manifests), `--assume-ethereum`, `-v, --verbose`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
-  - Options: `-s, --server <index>` (server index if multiple configured), `--replace` (replace the playlist already stored under this document id instead of creating a new one)
+  - Options: `-s, --server <index>` (server index if multiple configured), `--replace` (replace the playlist already stored under this document id instead of creating a new one), `-k, --key <privateKey>` (signs the replace authorization; `--replace` only)
+  - `--key` is refused on a plain `publish`, which signs nothing at request time — it uploads the `signatures[]` envelope the document already carries. Sign the file with `ff-cli sign --key` instead
 - `fetch <id-or-url>` – Save a published playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. The document goes to `-o` when given and to stdout otherwise (status lines always go to stderr, so `ff-cli fetch <id> > playlist.json` works). This is the starting point for `publish --replace`, which requires the stored `id`, `slug`, and `created`
-  - Options: `-s, --server <index>`, `-o, --output <file>`
-- `unpublish <id-or-url>` – Delete a playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. Requires the configured key to be an owner of the stored playlist, and confirms before deleting
-  - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation)
+  - Options: `-s, --server <index>`, `-o, --output <file>`. There is no `--key`: a fetch is a plain read and signs nothing
+- `unpublish <id-or-url>` – Delete a playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. Requires the signing key to be an owner of the stored playlist, and confirms before deleting
+  - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation), `-k, --key <privateKey>` (signs the delete authorization)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
   - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
 - `device list` – List all configured FF1 devices
@@ -331,8 +335,8 @@ is configured. An `apiKey` left over in an existing config is ignored.
 ### Change or remove a published playlist
 
 A feed's `PUT` and `DELETE` are owner-bound. Neither takes an API key, and neither is authorized by the
-document alone: both carry a short-lived **intent** that ff-cli signs with the configured key in the
-`curator` role. Only a key the *stored* playlist names in `curators[]` can authorize either one, which is
+document alone: both carry a short-lived **intent** that ff-cli signs in the `curator` role — with the
+configured `playlist.privateKey` by default, or with whatever `-k, --key` names for that one command. Only a key the *stored* playlist names in `curators[]` can authorize either one, which is
 why `publish` refuses to create a playlist that carries no owner-role signature — such a document can be
 neither replaced nor deleted, ever.
 
@@ -359,6 +363,17 @@ you published — re-running `find` or `build` mints a fresh id, slug, and `crea
 playlist rather than a replacement. A `publish` without `--replace` is never silently upgraded to a
 replace; an id the feed already holds fails with a conflict, as before.
 
+The configured `playlist.privateKey` is only the default. `-k, --key` overrides it on both commands —
+for the intent signature and for the local ownership check alike — the way `ff-cli sign --key` and
+`ff-cli status --key` already do. A `--key` that is
+present but empty (what `--key "$SIGNING_KEY"` becomes when the variable is unset) is **rejected**, never
+treated as absent: falling back to the configured key would authorize the write under an identity you did
+not choose, and a delete cannot be taken back. `unpublish` derives the identity before it looks the
+playlist up, so a bad credential fails before you are asked to confirm anything, and it prints
+`Signing as:` so the identity is visible in the record either way. The configured key is one identity;
+the key that owns a given playlist may be another, and editing `config.json` to delete something you own
+is not a workflow.
+
 Both verbs prove ownership locally before signing anything. A key counts as an owner only when the
 **stored** playlist names it in `curators[]` **and** carries its valid `curator`-role signature — being
 named is a claim, signing in the owner role is the proof. A playlist that declares a curator but was

package/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",