@feralfile/cli 2.7.0 → 2.9.0

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` 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.
 
   **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) accept the private key in any of these encodings:
 
@@ -133,7 +133,27 @@ DP‑1 Feed API configuration.
 Endpoints used by the CLI:
 
 - `GET /api/v1/playlists` (supports `limit`, `offset`, and sorting)
-- `GET /api/v1/playlists/{id}`
+- `GET /api/v1/playlists/{id}` (`fetch`)
+- `POST /api/v1/playlists` (`publish`)
+- `PUT /api/v1/playlists/{id}` (`publish --replace`)
+- `DELETE /api/v1/playlists/{id}` (`unpublish`)
+
+No credential is configured for any of these. The feed has no API key: every write is authorized by
+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. 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
+`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).
+
+**Choosing between several configured servers.** Commands that address a feed (`publish`, `unpublish`,
+`fetch`, `find --publish`) take `-s, --server <index>`, a 0-based index into the list above. With one server
+configured it is optional. With more than one and no `-s`, an interactive session asks; a session with no
+terminal — a pipe, a cron job, a CI step — exits non-zero and prints the list rather than guessing, since
+defaulting to index 0 would silently write to whichever feed happens to be first.
 
 Environment variable alternative:
 

package/docs/EXAMPLES.md

@@ -347,10 +347,34 @@ npm run dev -- publish playlist.json
 # Direct: publish to specific server (server index 0)
 npm run dev -- publish playlist.json -s 0
 
+# Replace a playlist already stored under this document id
+npm run dev -- publish playlist.json --replace -s 0
+
 # Show help
 npm run dev -- publish --help
 ```
 
+A bare Enter at the interactive prompt selects nothing either, and fails with the list. The prompt has no
+default by design: it is being asked precisely because the CLI cannot tell which feed was meant, and
+`Number('')` is `0` — the first server, usually production.
+
+**With more than one server configured and no `-s`, a non-interactive session fails rather than
+choosing.** Under a pipe, a cron job, or a CI step there is no terminal to answer the prompt, and
+defaulting to the first server would write to production for a script that meant the other one:
+
+```
+$ ff-cli publish playlist.json < /dev/null; echo "exit=$?"
+
+Publish playlist
+
+Multiple feed servers configured (2); pass --server <index>
+  0: https://feed.feralfile.com/api/v1
+  1: http://localhost:8787
+exit=1
+```
+
+The same rule applies to `unpublish`. With a single server configured, `-s` stays optional everywhere.
+
 ### Flow
 
 1. **Verify** - Playlist structure and signatures checked; unsigned or broken playlists are rejected
@@ -519,6 +543,352 @@ only way to add one is to replace the document. Publishing is what makes that pe
 `find` and `build` sign as `curator` automatically, since they declare the key themselves. This applies to
 documents you sign by hand, where `playlist.role` (default `agent`) decides the role.
 
+## 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 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.
+
+### Replace
+
+```bash
+# 1. Start from the PUBLISHED document, not a rebuilt one.
+ff-cli fetch <id> -o playlist.json -s 0
+
+# 2. Edit it. `id`, `slug`, `created` and the curators[] owner set must all stay as published.
+
+# 3. Re-sign FRESH. This flag is required here — see below.
+ff-cli sign playlist.json -r curator --replace-signatures
+
+# 4. Replace.
+ff-cli publish playlist.json --replace -s 0
+```
+
+**Step 3 needs `--replace-signatures`.** The document you fetched carries the curator's signature and
+the feed's own, both taken over the content as published. Editing it moves bytes those signatures cover,
+and `sign` **appends** rather than replaces — so a plain re-sign produces an envelope holding two stale
+entries and one good one, which `sign` then refuses to write:
+
+```
+$ ff-cli sign playlist.json -r curator
+
+Sign playlist
+
+Sign failed: Signed playlist verification failed: signed playlist is not verifiable
+
+If you edited this playlist after it was signed, the existing signatures no longer
+  cover it, and signing again cannot repair them — signing appends. Sign fresh instead:
+    ff-cli sign playlist.json -r curator --replace-signatures
+  That discards every existing entry, including any feed signature, and signs the
+  document as it stands now. It is the path a feed replace expects.
+```
+
+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
+
+Sign playlist
+
+✓ Playlist signed and saved to: /path/to/playlist.json
+
+Playlist signed
+  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.
+
+```
+$ ff-cli publish playlist.json --replace -s 0
+
+Replace playlist
+
+Replaced
+  Playlist ID: 97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+  Server: https://feed.feralfile.com/api/v1
+  Status: Replaced on feed server
+```
+
+`--replace` is never applied on your behalf. A plain `publish` of an id the feed already holds still
+fails with a conflict, because creating and overwriting are different intentions and only one of them is
+recoverable.
+
+Re-running `find` or `build` does **not** produce a replacement: each run mints a new `id`, `slug`, and
+`created`, and the feed compares all three against the stored row. `ff-cli` checks them locally and names
+the fields that moved, because the feed's own answer is a bare `400`:
+
+```
+Replace failed
+  The document changes fields a replace may not change.
+
+A replace keeps identity and ownership fixed: id, slug, and created must equal the stored
+  document's, and the curators[] owner set is immutable.
+    slug: stored "snowfro-send-receive", document "a-completely-new-slug"
+    created: stored "2026-09-07T23:32:39.660Z", document "2026-09-08T01:02:03.000Z"
+```
+
+### Delete
+
+```bash
+# id, slug, or a feed URL — all resolve to the same playlist.
+ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+ff-cli unpublish https://feed.feralfile.com/api/v1/playlists/97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+```
+
+```
+$ ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0 -y
+
+Unpublish playlist
+
+Unpublished
+  Playlist ID: 97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+  Slug: snowfro-send-receive
+  Server: https://feed.feralfile.com/api/v1
+  Status: Deleted from feed server (the id is now tombstoned and cannot be reused)
+```
+
+Without `-y`, `unpublish` shows the title and the server and asks, defaulting to **no**. The delete
+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
+valid `curator`-role signature. Being named is a claim; signing in the owner role is the proof, and the
+CLI checks both against the stored document before it signs an intent.
+
+That distinction has one large real population: playlists published while the default signing role was
+`agent`. They declare a curator and carry only that key's `agent` signature, so nothing can ever
+authorize a write to them — not even the holder of the declared key, because adding the missing proof
+would itself be a replace:
+
+```
+Unpublish failed
+  No key has proved ownership of this playlist, so none can delete it.
+
+A key counts as an owner only when it is named in curators[] AND signed the document as
+  "curator". This playlist names a curator and carries no valid curator signature
+  from that key — the shape of a playlist published while the default signing role was
+  "agent".
+  Declared:
+    did:key:z6Mkv7qJ...
+  Nothing can repair it, including holding one of those keys: adding the missing signature
+  would be a replace, and a replace needs the very proof that is missing. Publish a corrected
+  playlist under a new id instead.
+```
+
+This is why `publish` refuses to create such a document in the first place: the refusal at publish time
+is recoverable, and this one is not.
+
+### When the key is not an owner
+
+`ff-cli` reads the stored playlist before it signs anything, so this is refused locally and nothing is
+sent. The feed's own answer would be a bare `403`, naming neither the identity you offered nor the ones
+that would have worked:
+
+```
+$ ff-cli unpublish 885b2ea6-74e2-44fe-96d0-e8728f6bba9c -s 0 -y
+
+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[] 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
+  Keys that have proved ownership:
+    did:key:z6MkoDkq5YXsFGXPiD6HDUVfze5mvhU5QF4hTy59pVVPYg82
+  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`
+says so rather than sending you after a key that does not exist. That is the state every playlist
+published without an owner-role signature is frozen in, and it is what the `publish` owner-role gate
+above exists to prevent.
+
 ## Complete Flow (build → validate → sign → play → publish)
 
 ```bash

package/docs/PROJECT_SPEC.md

@@ -178,7 +178,69 @@ substituted for a chain the row already named.
 ### Delivery
 
 - `play` (handles playlist files, playlist URLs, and media URLs)
-- `publish`
+- `fetch`
+- `publish` (`--replace` sends an owner-bound replacement instead of a create)
+- `unpublish`
+
+### Owner-bound feed mutations
+
+Creating on a feed is open; changing or removing something is not. A feed accepts a `POST` from any
+document that is self-signed by a curator it declares, and the signer becomes that resource's owner. A
+`PUT` and a `DELETE` are authorized instead against the **stored** document's `curators[]`, and neither
+accepts an API key. Both therefore carry a signed intent — `{ action, target: { type, id, slug },
+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 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
+declared curators, declared but never proved (terminal, and the shape of anything published while the
+default role was `agent`), and proved by a key other than this one. A `403` that survives all three is
+reported as the feed's own judgement, not as a missing declaration. This is also why `publish` refuses to
+create a document whose declared curator did not sign in the `curator` role: that refusal is
+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
+reports on a document rather than saving one. Signing appends by default, which is
+correct only while the signed content is unchanged; an edit invalidates every entry the document
+carries, including the feed's own co-signature, and the envelope check refuses to persist a mix of stale
+and fresh. The fresh mode drops them all — the feed re-appends its signature after it verifies the
+replacement.
 
 ### Device operations
 

package/docs/README.md

@@ -97,7 +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>`
+  - 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
@@ -109,7 +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)
+  - 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>`. 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
@@ -323,6 +332,58 @@ 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 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.
+
+```bash
+# Edit a published playlist: fetch it, change the file, re-sign fresh, then replace.
+ff-cli fetch <id> -o playlist.json -s 0
+#   ...edit the title, items, or metadata...
+ff-cli sign playlist.json -r curator --replace-signatures
+ff-cli publish playlist.json --replace -s 0
+
+# Delete a published playlist (id, slug, or feed URL all work).
+ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+ff-cli unpublish https://feed.example.com/api/v1/playlists/97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+```
+
+`--replace-signatures` is not optional on that path. The document you fetched carries the curator's
+signature and the feed's, both taken over the pre-edit content; a plain `ff-cli sign` appends to them and
+the envelope check then refuses to write a file with stale entries in it. Signing fresh drops both — the
+feed re-appends its own after it verifies the replacement.
+
+`--replace` keeps identity fixed: `id`, `slug`, and `created` must equal the stored document's, and the
+`curators[]` owner set may not change. Editing a published playlist therefore means editing the document
+you published — re-running `find` or `build` mints a fresh id, slug, and `created`, which is a new
+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
+signed under another role (the shape of anything published while the default role was `agent`) can never
+be replaced or deleted by anyone, and the CLI says so rather than sending a request the feed will refuse.
+
+`unpublish` asks for confirmation first, showing the title and the server. `-y` skips it for scripts.
+Deletion is final in a way worth knowing before you run it: the feed **tombstones** the id, so the
+playlist cannot be restored and a later publish naming that id is refused. Build a new playlist instead.
+
 ### FF1 device management
 
 ```bash

package/package.json

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