@feralfile/cli 2.6.0 → 2.8.0

package/docs/PROJECT_SPEC.md

@@ -159,6 +159,16 @@ Today the CLI groups into these workflow areas:
 - `find`
 - `build`
 
+An item's `provenance.contract` is read from the indexer row, not inferred. Each
+row carries the token's own `standard` (`erc721`, `erc1155`, `fa2`) and its
+CAIP-2 `chain` (`eip155:1`, `tezos:mainnet`), and both are written through. The
+client's own detection sees a chain name and an address and nothing else, so it
+answers `erc721` for every EVM contract; it applies only to rows that carry no
+standard, and to the CID a lookup by coordinate must build before the indexer
+has been asked anything. A row naming a chain DP-1 has no word for is recorded
+as `other` — the item is still built, and the client's guess is never
+substituted for a chain the row already named.
+
 ### DP-1 output integrity
 
 - `verify`
@@ -168,7 +178,39 @@ Today the CLI groups into these workflow areas:
 ### 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 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
+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.
+
+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,8 @@ 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`
+  - 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`
 - `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 +110,11 @@ 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)
+- `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)
 - `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 +328,47 @@ 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
+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.
+
+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.6.0",
+  "version": "2.8.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",