@feralfile/cli 2.3.0 → 2.5.0

package/docs/CONFIGURATION.md

@@ -50,6 +50,19 @@ Used for signing DP‑1 playlists.
 
   ff-cli normalizes whichever form you supply to base64 PKCS#8 DER before handing it to **`dp1-js`** (`SignMultiEd25519`). A malformed key fails with an actionable message (e.g. _"Invalid Ed25519 signing key … run `ff-cli setup` to generate one"_) instead of dp1-js's cryptic OpenSSL ASN.1 error (`header too long` / `wrong tag`).
 
+- `playlist.curatorName` (string): Display name recorded alongside your signing key in the `curators[]`
+  of playlists built by `find` and `build`. Defaults to `ff-cli`; you can also set it via
+  `PLAYLIST_CURATOR_NAME`. The feed authorizes a create by matching a signature's `kid` against a key
+  declared in the document's own `curators[]`, so those commands write that declaration **before**
+  signing — a name is required next to the key by DP-1, and the value is public and covered by the
+  signature. The sample `YOUR_CURATOR_NAME` in `config.json.example` is treated as unset, so an untouched
+  config falls through to `PLAYLIST_CURATOR_NAME` or the default rather than publishing under a
+  placeholder.
+
+  To read the `did:key` your signatures will carry, run `ff-cli status`. It reports the identity from
+  `PLAYLIST_PRIVATE_KEY` even when no config file exists yet, and `ff-cli status --key <privateKey>`
+  reports it for an explicit key — the one `sign --key` would use.
+
 - `playlist.role` (string): DP-1 signing role that travels with the private key. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`).
 
 ### Generate an Ed25519 private key

package/docs/EXAMPLES.md

@@ -232,6 +232,44 @@ JSON
 npm run dev -- build /tmp/mixed.json -o playlist-mixed.json -v
 ```
 
+## Enrich an existing playlist
+
+A playlist whose items carry `provenance` but no `inlineManifest` labels
+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
+```
+
+```text
+Enrich playlist
+
+  18/18 looked up...
+
+18 of 18 item(s) enriched
+  Output: playlist.json
+```
+
+Items the indexer cannot resolve are listed rather than guessed at:
+
+```text
+Nothing to enrich
+
+  Skipped 2:
+    Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
+    Untitled — the indexer returned nothing for it
+```
+
+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 sign playlist.json
+ff-cli play playlist.json -d "living room"
+```
+
 ## Validate / Sign / Play
 
 ```bash
@@ -279,12 +317,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"
     }
   ]
 }
@@ -345,13 +381,61 @@ 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
 ```
 
+Run `ff-cli sign <file>` before publishing. (Posting the same 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 — signing appends, so re-signing an already-signed
+  playlist leaves the earlier signature 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, then publish.
+ff-cli sign playlist.json
+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.
+
 ## Complete Flow (build → validate → sign → play → publish)
 
 ```bash
@@ -361,7 +445,9 @@ 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
+# 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`).
 npm run dev -- sign playlist.json -o signed.json
 
 # 4. Play it on a device
@@ -371,6 +457,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

@@ -197,6 +197,128 @@ nowhere to host a manifest document. Behavior worth knowing downstream:
 - An inline manifest has no `refHash`; its integrity comes from the playlist
   signature.
 
+### Enriching a playlist the CLI did not build
+
+`find` and `build` attach a manifest as they create each item. A playlist that
+arrives another way — assembled by hand, copied out of another document, or
+written before §3.6 existed — has items with a `source` and a `provenance` block
+and nothing else. `enrich` is the repair path for those.
+
+- Enrichment is keyed on `provenance.contract` (chain, address, token id), not
+  on `source`. A source URL is one rendition of a work and several renditions
+  share one; the coordinate is what identifies the artwork.
+- It writes `inlineManifest` and nothing else. `source`, `duration`, `title`,
+  `id`, and `display` are curator decisions and survive untouched even when the
+  indexer disagrees with them.
+- An item the indexer cannot resolve is reported, never synthesized. The same
+  rule the manifest mapping follows applies here: the CLI does not invent fields
+  it cannot substantiate, and an invented artist line inside a signed document
+  is worse than an absent one.
+- DP-1 names the EVM family `evm`; the FF indexer names it `ethereum`. Enrich
+  translates between the two. Unlisted chain names pass through so the indexer
+  decides what it supports.
+- Enrichment changes the document, so both the `signatures[]` envelope and the
+  legacy flat `signature` are removed and the playlist must be re-signed.
+  Leaving a stale envelope in place would produce a file that fails
+  verification at the device with no explanation.
+- An item carrying a `ref` is already labelled by a manifest the CLI cannot
+  see, and `ref` outranks `inlineManifest` in the resolution order, so
+  enrichment skips it. `--force` does not override that: making the inline
+  manifest win would mean deleting the curator's `ref` and `refHash`, which
+  discards the integrity hash the remote manifest is checked against. That
+  conversion, if ever wanted, belongs behind its own flag.
+- Enrichment looks each distinct coordinate up once, however many items share
+  it. A token the indexer has not seen triggers an indexing job and a poll that
+  can take minutes, and a playlist that repeats a work would otherwise submit
+  that job once per appearance.
+- Overriding an item's title changes the manifest's content, so it also changes
+  the manifest's `id`. The indexer derives that id from the token coordinate,
+  so two items of one artwork receive the same one; leaving it alone while
+  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 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.
+- 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.
+- `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
+  nor the response can say which network is meant. Ethereum is chosen because
+  it is the only EVM network this client can reach — `buildTokenCID` maps
+  ethereum to `eip155:1` and tezos to `tezos:mainnet` and throws for anything
+  else. The residual risk is narrow: an L2 work whose address and token id also
+  exist on Ethereum would take the Ethereum work's metadata. The command
+  is the operator's to make: `--assume-ethereum` asserts it, and without that
+  flag `evm` items are skipped with a reason that names the flag. The warning
+  prints before anything is written, so an operator who did not mean to assert
+  it still has the file they started with. Reaching an actual L2 belongs in the
+  indexer client, which maps only `ethereum` and `tezos` today.
+- In-place writes refuse to run over an input that changed while the lookup
+  was in flight. The comparison is a hash of the bytes actually parsed, against
+  the resolved write target, so `-o` naming the input by another spelling and a
+  symlink pointing at it are both recognized as the in-place case. It runs
+  immediately before the rename, so the exposed interval is a few syscalls
+  rather than the minutes a lookup takes. It narrows the race and does not
+  close it: compare-then-replace is not atomic against an editor participating
+  in no protocol, and no userspace sequence makes it so. Writing to a distinct
+  `--output` opts out of in-place replacement entirely, which is the right
+  choice when a file is being actively edited.
+- An attached manifest's id is derived from its whole finished metadata block,
+  every time rather than only when this command changed something. The indexer
+  keys its id on the token coordinate, so every rendition of one artwork
+  carries the same id whatever its content, and under `--force` the indexer may
+  itself return a different artist or description under that unchanged id.
+  Deriving from the payload is the only rule that holds in every case:
+  identical content keeps one identity, differing content never shares one. The
+  original id is folded in so the result stays anchored to the token and stays
+  deterministic across runs.
+- In-place writes refuse to run over an input that changed while the lookup
+  was in flight. The lookup can take minutes and the default destination is the
+  input, so a curator's edit or re-sign in that window would otherwise be
+  overwritten by a result computed from older bytes.
+- In-place writes are atomic and crash-durable: the contents are synced before
+  the rename and the containing directory after it, so a power loss cannot
+  leave the destination name pointing at incomplete data. The directory sync is
+  best-effort, since it is not portable.
+- In-place writes are atomic: the candidate goes to a temporary file beside the
+  destination and is renamed over it, so an interruption cannot leave a
+  truncated playlist. A symlinked destination is followed to its target rather
+  than replaced, and the existing file's permission mode is read before the
+  temporary file is created and applied to it before any bytes are written, so
+  a curator-restricted playlist is never briefly world-readable mid-write. The
+  destination's owner and group are carried across too, since a replacement is
+  a new inode and would otherwise take this process's ownership — silently
+  reassigning a shared playlist. Where that cannot be done, the in-place
+  replacement is refused and `--output` is offered instead. Extended ACLs are
+  not preserved, because Node exposes no portable way to read them; a playlist
+  carrying them should be enriched through `--output`.
+- `--output` names a file the caller expects to exist afterwards, so it is
+  written even when nothing was enriched. A no-op without `--output` writes
+  nothing rather than rewriting the input for no gain.
+- The playlist is validated before lookup and the enriched candidate is
+  validated before writing. On either failure the diagnostics are printed and
+  the file is left untouched, rather than replaced with a document that sign,
+  publish, and play would each reject later.
+
 ## Deterministic-first behavior
 
 The CLI is deterministic end to end. There is no natural-language interface; any natural-language layer lives in the user's coding agent, which drives these commands:

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": {
@@ -104,6 +105,9 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - OpenSea forms: `/assets/ethereum/{contract}/{tokenId}`, `/item/ethereum/{contract}/{tokenId}`, and `/collection/{slug}` (Ethereum collections; the slug is resolved from the public collection page, no API key needed)
   - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
   - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes`, `--skip-verify`
+- `enrich <file>` – Add missing artist, title, and thumbnail metadata to a playlist that already exists. Resolves each item by its `provenance.contract` and writes an inline Ref Manifest; `source`, `duration`, `title`, and `id` are never touched. Drops the signature when it changes anything, so re-sign afterwards
+  - 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)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
@@ -176,6 +180,41 @@ cat params.json | ff-cli build -o playlist.json
 }
 ```
 
+### Enrich a playlist that came from somewhere else
+
+`find` and `build` label every item they create. A playlist assembled by hand,
+copied from another document, or written before inline manifests existed has no
+`inlineManifest`, and on a device that shows as a tombstone with no artist line
+and an empty tile in the app's grid — the app can draw a thumbnail from an
+image, video, or SVG source, but not from a live HTML work.
+
+`ff-cli enrich` fills that in from the indexer, keyed on each item's
+`provenance.contract`:
+
+```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
+```
+
+`--assume-ethereum` is needed for most playlists. DP-1 records an EVM
+coordinate as `chain: "evm"`, which names Ethereum, Polygon, Arbitrum,
+Optimism, Base and Zora alike, and the indexer's answer collapses back to the
+same word. Enrichment will not pick one for you, because the wrong member
+returns a different artwork's artist and still — into a document you then sign.
+
+It writes `inlineManifest` and nothing else. Items with no
+`provenance.contract` chain, address, and token id cannot be looked up and are
+reported rather than guessed at, and items carrying an external `ref` are left
+alone because `ref` outranks an inline manifest at the device. The playlist is
+validated before and after; on failure the file is left untouched. Enriching
+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
+```
+
 ### Validate, sign, and play
 
 ```bash
@@ -240,16 +279,24 @@ 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[]`.
+
+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. 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` do this 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.3.0",
+  "version": "2.5.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",