@feralfile/cli 2.4.0 → 2.6.0

package/docs/EXAMPLES.md

@@ -239,7 +239,7 @@ title-only on the FF1 tombstone, and shows empty tiles in the app for every
 live HTML work. `enrich` repairs it in place.
 
 ```bash
-ff-cli enrich playlist.json
+ff-cli enrich playlist.json --assume-ethereum
 ```
 
 ```text
@@ -251,25 +251,37 @@ Enrich playlist
   Output: playlist.json
 ```
 
+`--assume-ethereum` is the operator's assertion that the playlist's `evm`
+coordinates are Ethereum. DP-1 records every EVM network as `chain: "evm"`,
+and `find` writes that for Ethereum works too, so an Ethereum playlist needs
+the flag; without it those items are skipped rather than guessed at, because
+the wrong network returns a different artwork's metadata. A Tezos playlist
+needs no flag.
+
 Items the indexer cannot resolve are listed rather than guessed at:
 
 ```text
 Nothing to enrich
 
-  Skipped 2:
+  Skipped 3:
     Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
     Untitled — the indexer returned nothing for it
+    Pre-Process — chain "evm" names a family; pass --assume-ethereum to assert the network
 ```
 
 Enrichment changes the document, so a signed playlist loses its envelope and
 has to be re-signed:
 
 ```bash
-ff-cli enrich playlist.json
+ff-cli enrich playlist.json --assume-ethereum
 ff-cli sign playlist.json
 ff-cli play playlist.json -d "living room"
 ```
 
+Casting does not care about the signing role. Add `-r curator` to that `sign` if the playlist is also
+going to a feed: `ff-cli publish` requires the owner role, for the reasons in
+[Publish to Feed Server](#publish-to-feed-server).
+
 ## Validate / Sign / Play
 
 ```bash
@@ -317,12 +329,10 @@ Add feed servers to `config.json`:
 {
   "feedServers": [
     {
-      "baseUrl": "http://localhost:8787/api/v1",
-      "apiKey": "your-api-key"
+      "baseUrl": "http://localhost:8787/api/v1"
     },
     {
-      "baseUrl": "https://feed.example.com/api/v1",
-      "apiKey": "your-api-key"
+      "baseUrl": "https://feed.example.com/api/v1"
     }
   ]
 }
@@ -383,13 +393,132 @@ Select server (0-based index): 0
    Playlist file not found: /path/to/playlist.json
 ```
 
-**API error:**
+Both of these are caught locally, before anything is uploaded.
+
+**Not signed:**
 
 ```
-❌ Failed to publish playlist
-   Failed to publish: {"error":"unauthorized","message":"Invalid API key"}
+Publish failed
+  Playlist verification failed: Playlist signature verification failed
+```
+
+Declare your key in `curators[]`, then sign it as the owner before publishing:
+
+```bash
+ff-cli status                          # the did:key to declare
+ff-cli sign <file> -r curator
+```
+
+Plain `ff-cli sign` would use `playlist.role` (default `agent`), producing a document the next two checks
+refuse — under role-aware ownership a declared key counts as an owner only when it signed as `curator`, and
+`ff-cli publish` requires that whether or not the target feed enforces it yet. (Posting the unsigned
+document straight to the feed answers
+`{"error":"unauthorized","message":"missing authentication: request body must carry signatures"}`.)
+
+**Signed, but the signer is not declared as a curator:**
+
+```
+Publish failed
+  Playlist is signed, but the signing key is not declared as a curator.
+
+The feed accepts a publish when a signature's kid appears in the playlist's own curators[].
+  Add this to the playlist before signing:
+    "curators": [{ "name": "Your name", "key": "did:key:z6Mkv7qJ..." }]
+  then sign again from the unsigned file, with the same key you just declared:
+    ff-cli sign <file> -r curator --key <private key for did:key:z6Mkv7qJ...>
+  Drop --key if that key is your configured one; "sign" uses the configured key otherwise, and a
+  signature from an undeclared key would not satisfy the feed. Start from the unsigned file
+  because declaring curators[] changes the signed payload: signing appends, so the earlier
+  signature would be left covering a document that no longer exists.
+```
+
+This is the most common publish failure, and it is not about credentials. The feed accepts a create when
+the document carries a signature whose `kid` matches a key declared in its own `curators[]`; posting such
+a document directly returns
+`{"error":"signature_verification_failed","message":"curator signature verification: no valid curator signature found"}`,
+which reads as a signing fault, so `ff-cli` diagnoses it locally instead.
+
+**Order matters.** A signature covers every field except `signature`/`signatures`, so `curators[]` has to
+be declared *before* signing. Adding it afterwards invalidates the signature, and signing again does not
+repair it — signing **appends**, leaving the earlier entry covering a document that no longer exists, so
+verification fails before upload.
+
+```bash
+# 1. Read your signing identity — this is the kid your signatures will carry.
+ff-cli status          # → Signing identity (did:key)  did:key:z6Mk...
+
+# 2. Declare it in the UNSIGNED playlist.
+#    "curators": [{ "name": "Your Name", "key": "did:key:z6Mk..." }]
+#    DP-1 requires `name` alongside `key`.
+
+# 3. Sign once as curator, then publish. The role must match the claim in curators[].
+ff-cli sign playlist.json -r curator
+ff-cli publish playlist.json
+```
+
+If a playlist is already signed and you need to add `curators[]`, start again from the unsigned file
+rather than re-signing: remove `signatures`, declare the curator, then sign.
+
+`ff-cli publish` checks this before uploading, so a missing declaration fails immediately with the key to
+add rather than as a server error. No API key is involved: the feed does not accept one.
+
+**Declared, but signed under a non-owner role:**
+
+```
+Publish failed
+  Playlist is signed by a declared curator, but under a non-owner role ("agent").
+
+This is ff-cli's check, not a feed's answer. Feeds are moving to role-aware ownership, where
+  a key in curators[] counts as an owner only if it also signed as "curator". A feed that
+  does not check the role yet will accept this document, and then be unable to authorize a
+  replace or a delete for it: both need an owner signature it does not carry. Publishing it is
+  what makes that permanent, so ff-cli refuses here instead.
+
+  curators[] is already correct — only the role is missing, so add that signature to this file:
+    ff-cli sign <file> -r curator --key <private key for a declared curator>
+  Any key this playlist declares will do — you do not need the one that signed under the wrong
+  role. Declared: did:key:z6Mkv7qJ...
+  It must be one of those: a curator signature from an undeclared key satisfies neither
+  this check nor role-aware ownership, since both read roles only from declared keys. "sign"
+  uses the configured key unless --key says otherwise; drop --key if a declared key is already
+  your configured one, and confirm which identity a key carries with
+  "ff-cli status --key <private key>".
+  Signing appends, and the payload hash excludes signatures, so the existing entry stays valid
+  and the document ends up carrying both. No unsigned copy is needed: you only have to start
+  from one when changing signed content such as curators[] itself.
 ```
 
+Declaring a key in `curators[]` is a claim that it owns the playlist; signing as `curator` is the proof.
+This failure means the document is right and the signature is not — the fix is the role, not `curators[]`.
+
+**This one is repairable in place**, unlike the two above. Nothing signed needs to change, so appending is
+enough — the payload hash covers the document with `signature`/`signatures` stripped, which leaves the
+earlier entry valid over bytes that did not move:
+
+```bash
+# --key only when the declared curator is not your configured key; `ff-cli status --key <k>`
+# reports which identity a key carries.
+ff-cli sign playlist.json -r curator --key <declared curator's key>   # ["agent"] -> ["agent","curator"]
+ff-cli publish playlist.json
+```
+
+The signature has to come from a key the playlist already declares — **any** of them, not specifically the
+one that signed under the wrong role. On a playlist with several curators, whoever holds one of the other
+declared keys can repair it. `sign` uses the configured key unless `--key` says otherwise, so on a machine
+whose configured key is not declared, the plain command appends a `curator` signature the feed ignores and
+the publish fails identically.
+
+Start again from an unsigned document only when the fix changes signed content — adding `curators[]`, for
+instance. There the earlier signature would cover a document that no longer exists.
+
+**This is a CLI preflight, not a report of what a feed said.** A feed that does not yet check the role
+accepts such a document, so uploading it by hand can still succeed. It is refused here because once
+accepted it can never be replaced **or** deleted: both need an owner signature it does not carry, and the
+only way to add one is to replace the document. Publishing is what makes that permanent.
+
+`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.
+
 ## Complete Flow (build → validate → sign → play → publish)
 
 ```bash
@@ -399,8 +528,12 @@ npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 -o playlist.json
 # 2. Validate it
 npm run dev -- validate playlist.json
 
-# 3. Sign it
-npm run dev -- sign playlist.json -o signed.json
+# 3. Sign it. Declare curators[] BEFORE this step: the signature covers it, and the feed only
+#    accepts a publish when a signature's kid matches a declared curator key.
+#    Run `ff-cli status` for the kid (add -k <key> if you sign with `sign --key`).
+#    -r curator: ff-cli publish requires the owner role (role-aware ownership); the kid match is
+#    what feeds enforce today.
+npm run dev -- sign playlist.json -r curator -o signed.json
 
 # 4. Play it on a device
 npm run dev -- play signed.json -d "Living Room Display"
@@ -409,6 +542,18 @@ npm run dev -- play signed.json -d "Living Room Display"
 npm run dev -- publish signed.json -s 0
 ```
 
+With a signing key configured, `find` and `build` already produce a signed `playlist.json` with your
+key declared in `curators[]`. Skip step 3 and use `playlist.json` in steps 4 and 5 — there is no
+`signed.json` on that path:
+
+```bash
+npm run dev -- play playlist.json -d "Living Room Display"
+npm run dev -- publish playlist.json -s 0
+```
+
+Set `playlist.curatorName` in the config to control the name recorded in `curators[]`; it defaults
+to `ff-cli`.
+
 `ff-cli find` can collapse build + play + publish into one command:
 
 ```bash

package/docs/PROJECT_SPEC.md

@@ -237,28 +237,41 @@ and nothing else. `enrich` is the repair path for those.
   changing the title would produce two documents claiming to be the same cached
   manifest. The replacement is derived from the original id and the title, so
   it is deterministic across runs.
+- The token standard the playlist asserts (`provenance.contract.standard`)
+  rides the lookup. The indexer keys ERC-721 and ERC-1155 tokens under
+  different CIDs (`eip155:1:erc721:…`, `eip155:1:erc1155:…`) and the client's
+  detection, having only an address, answers erc721 for every EVM contract —
+  so without the assertion an ERC-1155 work is queried as ERC-721 and never
+  found. A value outside the standards the CID can carry falls back to
+  detection.
 - The indexer resolving a token and having something worth attaching are
   different outcomes: `buildInlineManifestForToken` returns nothing when it has
-  only a title, since a title-only manifest adds payload without adding
-  information. Enrichment reports those separately from tokens it could not
-  resolve at all.
+  only a title, since on the items `find` and `build` create a title-only
+  manifest repeats what the item already says. A curator's item may carry no
+  title at all, and the tombstone then shows nothing, so enrichment does
+  synthesize a title-only manifest in that one case — the indexer's title is
+  substantiated, and `item.title` itself is still never written. An item that
+  has a title and resolves to nothing more is reported as resolved-without-
+  metadata, separately from tokens the indexer could not resolve at all.
 - A still the manifest builder suppressed is recovered against the item's own
   source. `resolveStillUri` blanks a thumbnail equal to the source it was
   handed, which is the source the *indexer* chose; for a static work that is
   often the still itself. When the curator kept a live HTML source instead, the
   item would otherwise end up with no thumbnail — the empty grid tile this
-  command exists to remove. When the indexer's source differs from the item's
-  and is http(s) **and is media the app can rasterize**, it is that suppressed
-  still
-  and becomes the thumbnail. The type check matters: `getBestMediaUrl` prefers
-  `display.animation_url` and media assets over `display.image_url`, so the
-  indexer's source is frequently a live HTML rendition, and putting one in the
-  thumbnail slot is worse than leaving it empty — the grid still cannot
-  rasterize it and the item now claims a still it does not have. The predicate
-  matches the media types `playlist-builder.js` already recognizes, images plus
-  SVG and video, and rejects HTML. A
-  thumbnail-only manifest is emitted where none was, unlike a title-only one:
-  it is the difference between a tile and an empty square.
+  command exists to remove. The lookup therefore carries the still the indexer
+  names for the token (`display.image_url`, returned beside the DP-1 item by
+  `resolveTokenBatch`), and enrichment applies the same rule against the
+  curator's source: when that still differs from the item's source it becomes
+  the thumbnail. It is the same field `find` and `build` write into
+  `thumbnails.default`, taken on the indexer's word as they take it. Nothing is
+  inferred from the indexer's *source*: `getBestMediaUrl` prefers
+  `display.animation_url` and media assets over `display.image_url`, so that
+  source is frequently a live HTML rendition, and a file-suffix check would
+  reject the extensionless CDN URLs the indexer commonly returns as stills
+  while `display.mime_type` describes the primary rendition rather than the
+  still (a live work reports `text/html` beside a PNG `image_url`). A
+  thumbnail-only manifest is emitted where none was: it is the difference
+  between a tile and an empty square.
 - `evm` names a family, and enrichment refuses to guess which member. DP-1 §6
   carries no network identity, and the indexer maps Ethereum, Polygon,
   Arbitrum, Optimism, Base, and Zora all back to `evm`, so neither the request

package/docs/README.md

@@ -36,7 +36,8 @@ ff-cli config validate
 {
   "defaultDuration": 10,
   "playlist": {
-    "privateKey": "your_ed25519_private_key_hex_or_base64_here"
+    "privateKey": "your_ed25519_private_key_hex_or_base64_here",
+    "curatorName": "YOUR_CURATOR_NAME"
   },
   "feed": { "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"] },
   "ff1Devices": {
@@ -192,8 +193,8 @@ image, video, or SVG source, but not from a live HTML work.
 
 ```bash
 ff-cli enrich playlist.json --assume-ethereum
-ff-cli enrich playlist.json -o labelled.json
-ff-cli enrich playlist.json --force        # replace existing manifests
+ff-cli enrich playlist.json --assume-ethereum -o labelled.json
+ff-cli enrich playlist.json --assume-ethereum --force   # replace existing manifests
 ```
 
 `--assume-ethereum` is needed for most playlists. DP-1 records an EVM
@@ -211,9 +212,12 @@ changes the document, so the signature is removed and the playlist must be
 re-signed before playing:
 
 ```bash
-ff-cli enrich playlist.json && ff-cli sign playlist.json
+ff-cli enrich playlist.json --assume-ethereum && ff-cli sign playlist.json
 ```
 
+That role is fine for casting. Use `ff-cli sign playlist.json -r curator` if the enriched playlist is
+also going to a feed.
+
 ### Validate, sign, and play
 
 ```bash
@@ -278,16 +282,42 @@ The `publish` command:
 
 Configure feed servers in `config.json`:
 
+Publishing needs no credentials. The feed authorizes a create from the signatures inside the playlist:
+it requires a signature whose `kid` matches a key the document declares in `curators[]`.
+
+`ff-cli publish` additionally requires that signature to carry the **`curator` role**. That is ff-cli's
+check, not every feed's answer today: feeds are moving to role-aware ownership, where being named in
+`curators[]` is a claim and signing as `curator` is the proof. A feed that does not check the role yet
+accepts an `agent`-signed document — and can then authorize neither a replace nor a delete for it, since
+both need an owner signature it does not carry. Publishing is what makes that permanent, so the CLI
+refuses first.
+
+Declare it before signing, not after: a signature covers `curators[]`, so adding the entry to an
+already-signed playlist invalidates it, and signing again appends rather than replaces. Run
+`ff-cli status` to read the `did:key` your signatures will carry, put it in `curators[]`, then sign
+once **with the owner role**:
+
+```bash
+ff-cli sign playlist.json -r curator
+```
+
+The flag is needed because plain `ff-cli sign` uses `playlist.role`, which defaults to `agent` — a
+document `ff-cli publish` then refuses. Set `"role": "curator"` under `playlist` in `config.json` to make
+that the default for hand-signed playlists.
+
+If you sign with `sign --key <privateKey>`, read that key's identity with
+`ff-cli status --key <privateKey>` — the configured identity would be the wrong one to declare. `find`
+and `build` need none of this: they declare the key and sign it as `curator` for you when a signing key
+is configured. An `apiKey` left over in an existing config is ignored.
+
 ```json
 {
   "feedServers": [
     {
-      "baseUrl": "http://localhost:8787/api/v1",
-      "apiKey": "your-api-key-optional"
+      "baseUrl": "http://localhost:8787/api/v1"
     },
     {
-      "baseUrl": "https://feed.example.com/api/v1",
-      "apiKey": "your-api-key-optional"
+      "baseUrl": "https://feed.example.com/api/v1"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
   "dependencies": {
     "@feralfile/source-resolver": "^1.0.0",
     "@napi-rs/keyring": "1.3.0",
-    "axios": "^1.6.2",
+    "axios": "^1.20.0",
     "bonjour-service": "^1.3.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
@@ -68,7 +68,7 @@
     "dp1-js": "2.3.1",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
-    "viem": "^2.38.2"
+    "viem": "^2.56.3"
   },
   "devDependencies": {
     "@types/node": "^24.7.1",