@feralfile/cli 2.4.0 → 2.5.0

package/config.json.example

@@ -7,17 +7,16 @@
   },
   "feedServers": [
     {
-      "baseUrl": "https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1",
-      "apiKey": "YOUR_FEED_SERVER_API_KEY_OPTIONAL"
+      "baseUrl": "https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"
     },
     {
-      "baseUrl": "http://localhost:8787",
-      "apiKey": "YOUR_FEED_SERVER_API_KEY_OPTIONAL"
+      "baseUrl": "http://localhost:8787"
     }
   ],
   "playlist": {
     "privateKey": "YOUR_ED25519_PRIVATE_KEY__base64_PKCS8_DER_recommended__or_32byte_raw_seed_as_hex_or_base64__run_ff-cli_setup_to_generate",
-    "role": "agent"
+    "role": "agent",
+    "curatorName": "YOUR_CURATOR_NAME"
   },
   "ff1Relayer": {
     "baseUrl": "https://tv-cast-coordination.autonomy-system.workers.dev"

package/dist/package.json

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

package/dist/src/commands/find.js

@@ -641,8 +641,7 @@ async function doPublish(savedPath, serverArg, nonInteractive) {
         serverIndex = n;
     }
     const serverUrl = feedConfig.baseURLs[serverIndex];
-    const serverApiKey = feedConfig.servers?.[serverIndex]?.apiKey ?? feedConfig.apiKey;
-    const result = await publishPlaylist(savedPath, serverUrl, serverApiKey);
+    const result = await publishPlaylist(savedPath, serverUrl);
     if (result.success) {
         console.log(chalk_1.default.green('✓ Published'));
         if (result.playlistId) {

package/dist/src/commands/play.js

@@ -128,7 +128,6 @@ exports.playCommand = new commander_1.Command('play')
             console.log(chalk_1.default.yellow(`\nTry:  ff-cli find "${source}" --play${deviceFlag}`));
             process.exit(1);
         }
-        const config = (0, config_1.getConfig)();
         // No explicit duration: a direct video/audio URL plays its natural
         // length (DP-1 §4.1); static media uses config.defaultDuration.
         const resolved = probed ?? (await (0, playlist_source_1.resolvePlaySource)(source));
@@ -143,7 +142,11 @@ exports.playCommand = new commander_1.Command('play')
         // A direct media/web URL is wrapped in an unsigned single-item playlist,
         // so it must be signed before the verify gate; a loaded playlist is sent
         // as-is. castPlaylist owns the sign → verify → send sequence.
-        const privateKey = config.playlist?.privateKey || process.env.PLAYLIST_PRIVATE_KEY;
+        // Resolve through getPlaylistConfig rather than reading config.playlist directly: it is the one
+        // place that knows a config value may still be the config.json.example placeholder, in which case a
+        // valid PLAYLIST_PRIVATE_KEY must win. Duplicating the `config || env` precedence here is what made
+        // this path sign with the template literal while every other signing path used the real key.
+        const privateKey = (0, config_1.getPlaylistConfig)().privateKey || undefined;
         const result = await (0, playlist_cast_1.castPlaylist)(resolved.playlist, {
             deviceName: options.device,
             skipVerify: options.skipVerify,

package/dist/src/commands/publish.js

@@ -56,7 +56,6 @@ exports.publishCommand = new commander_1.Command('publish')
             process.exit(1);
         }
         let serverUrl = feedConfig.baseURLs[0];
-        let serverApiKey = feedConfig.apiKey;
         if (feedConfig.baseURLs.length > 1) {
             if (!options.server) {
                 console.log(chalk_1.default.yellow('Multiple feed servers found. Select one:'));
@@ -77,14 +76,8 @@ exports.publishCommand = new commander_1.Command('publish')
                 process.exit(1);
             }
             serverUrl = feedConfig.baseURLs[serverIndex];
-            if (feedConfig.servers && feedConfig.servers[serverIndex]) {
-                serverApiKey = feedConfig.servers[serverIndex].apiKey;
-            }
-        }
-        else if (feedConfig.servers && feedConfig.servers[0]) {
-            serverApiKey = feedConfig.servers[0].apiKey;
         }
-        const result = await publishPlaylist(file, serverUrl, serverApiKey);
+        const result = await publishPlaylist(file, serverUrl);
         if (result.success) {
             console.log(chalk_1.default.green('Published'));
             if (result.playlistId) {

package/dist/src/commands/status.js

@@ -10,15 +10,47 @@ const config_files_1 = require("./helpers/config-files");
 const config_1 = require("../config");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+const signing_identity_1 = require("../utilities/signing-identity");
 const config_placeholders_1 = require("../utilities/config-placeholders");
 exports.statusCommand = new commander_1.Command('status')
     .description('Show configuration status')
-    .action(async () => {
+    // Identity discovery must cover every key `sign` accepts, not just the configured one. `sign --key`
+    // signs with a key the config never mentions, so reporting only the configured identity would hand the
+    // user the wrong did:key to declare in curators[] — and a wrong declaration fails exactly like a
+    // missing one.
+    .option('-k, --key <privateKey>', 'Report the signing identity for this key instead of the configured one')
+    .action(async (options) => {
     try {
+        const overrideKey = options.key?.trim();
+        if (overrideKey) {
+            try {
+                console.log(chalk_1.default.green(`Signing identity (did:key) ${(0, signing_identity_1.playlistSigningDidKey)(overrideKey)}`));
+                console.log(chalk_1.default.dim("  declare this in the playlist's curators[] before signing"));
+                return;
+            }
+            catch (error) {
+                console.log(chalk_1.default.red(`--key unusable: ${error.message}`));
+                process.exit(1);
+            }
+        }
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
             console.log(chalk_1.default.red('config.json not found'));
             console.log(chalk_1.default.dim('Run: ff-cli setup'));
+            // PLAYLIST_PRIVATE_KEY is a supported signing source on its own, and the did:key it implies is
+            // the one value a user must know before they can write a publishable playlist — it has to be
+            // declared in curators[] before signing. Exiting silently here would leave an environment-only
+            // user unable to obtain it from anywhere. The exit status still reports "not configured".
+            const envKey = process.env.PLAYLIST_PRIVATE_KEY?.trim();
+            if (envKey) {
+                try {
+                    console.log(chalk_1.default.green(`\nSigning identity (did:key) ${(0, signing_identity_1.playlistSigningDidKey)(envKey)}`));
+                    console.log(chalk_1.default.dim("  from PLAYLIST_PRIVATE_KEY; declare it in the playlist's curators[]"));
+                }
+                catch (error) {
+                    console.log(chalk_1.default.red(`\nPLAYLIST_PRIVATE_KEY unusable: ${error.message}`));
+                }
+            }
             process.exit(1);
         }
         const config = await (0, config_files_1.readConfigFile)(configPath);
@@ -38,6 +70,17 @@ exports.statusCommand = new commander_1.Command('status')
                 playlistRoleError = playlistRoleMaterial;
             }
         }
+        // The feed matches a signature's kid against the document's own curators[], so this value is not
+        // decoration: without it a user cannot write a publishable playlist, and it appears nowhere else.
+        let signingDidKey;
+        if (hasPlaylistSigningKey) {
+            try {
+                signingDidKey = (0, signing_identity_1.playlistSigningDidKey)(playlistKeyMaterial);
+            }
+            catch {
+                signingDidKey = undefined;
+            }
+        }
         const statuses = [
             {
                 label: 'Config file',
@@ -55,6 +98,13 @@ exports.statusCommand = new commander_1.Command('status')
                         : undefined,
                 hint: ' (needed for signing and legacy verification)',
             },
+            {
+                label: 'Signing identity (did:key)',
+                ok: Boolean(signingDidKey),
+                optional: false,
+                detail: signingDidKey,
+                hint: " (declare this in the playlist's curators[] so the feed accepts a publish)",
+            },
             {
                 label: 'Playlist signing role',
                 ok: hasValidPlaylistRole,

package/dist/src/config.js

@@ -121,10 +121,38 @@ function getPlaylistConfig() {
     const config = getConfig();
     const playlistConfig = config.playlist || {};
     return {
-        privateKey: playlistConfig.privateKey || process.env.PLAYLIST_PRIVATE_KEY || null,
+        // `config init` writes the sample file through verbatim, so an untouched config carries the
+        // YOUR_ED25519_PRIVATE_KEY... literal. It is truthy, so without this it would beat a perfectly good
+        // PLAYLIST_PRIVATE_KEY and every signing path would fail on a key the user never chose.
+        privateKey: (0, config_placeholders_1.isMissingConfigValue)(playlistConfig.privateKey)
+            ? process.env.PLAYLIST_PRIVATE_KEY || null
+            : playlistConfig.privateKey || null,
         role: playlistConfig.role || process.env.PLAYLIST_ROLE || null,
+        curatorName: resolveCuratorName(playlistConfig.curatorName),
     };
 }
+/** The literal shipped in config.json.example, and the only curator name treated as unset. */
+const CURATOR_NAME_TEMPLATE = 'YOUR_CURATOR_NAME';
+/**
+ * Resolve the curator name recorded in a built playlist's signed `curators[]`.
+ *
+ * Two hazards meet here, and they pull in opposite directions. The sample value must not win over the
+ * environment, or a freshly initialized config publishes under a placeholder. But the generic
+ * YOUR_/your_ placeholder test is too broad for a human name — a real studio called "YOUR_STUDIO" would
+ * be silently replaced, and the wrong attribution would then be sealed inside a signature. So only the
+ * exact template literal counts as unset.
+ *
+ * A non-string value is treated as unset rather than passed through: config.json is arbitrary runtime
+ * JSON, and this value is assigned into the document *after* the builder has validated it, so a number
+ * here would be signed into a malformed playlist instead of being rejected.
+ */
+function resolveCuratorName(configured) {
+    const fromConfig = typeof configured === 'string' ? configured.trim() : '';
+    if (fromConfig && fromConfig !== CURATOR_NAME_TEMPLATE) {
+        return fromConfig;
+    }
+    return process.env.PLAYLIST_CURATOR_NAME?.trim() || null;
+}
 /**
  * Resolve the effective playlist signing role used by runtime paths.
  *
@@ -146,12 +174,15 @@ function resolveEffectivePlaylistRole(config) {
 /**
  * Get feed configuration for DP1 feed API
  *
- * Supports both legacy (feed.baseURLs/apiKey) and new (feedServers array) formats.
+ * Supports both legacy (feed.baseURLs) and new (feedServers array) formats.
+ *
+ * No API key is returned. The feed authorizes writes from the signatures inside the document, so a key
+ * is neither sent nor accepted; an `apiKey` left in an existing config file is simply ignored rather
+ * than being an error, so old configs keep working.
  *
  * @returns {Object} Feed configuration
  * @returns {string[]} returns.baseURLs - Array of base URLs for feed APIs
- * @returns {string} [returns.apiKey] - Optional API key for authentication (legacy)
- * @returns {Array<Object>} [returns.servers] - Array of feed servers with individual API keys (new)
+ * @returns {Array<Object>} [returns.servers] - Array of configured feed servers (new format)
  */
 function getFeedConfig() {
     const config = getConfig();
@@ -179,7 +210,6 @@ function getFeedConfig() {
     }
     return {
         baseURLs: urls,
-        apiKey: feedConfig.apiKey,
     };
 }
 /**
@@ -281,6 +311,16 @@ function validateConfig() {
                 }
             }
         }
+        // curatorName is signed into curators[] as a public name, and it is written into the document after
+        // the builder has validated it — so a malformed value is not caught anywhere downstream. Reporting a
+        // clean config while `build` emits an invalid signed playlist is the failure worth preventing here.
+        const curatorNameValue = config.playlist
+            ?.curatorName;
+        if (curatorNameValue !== undefined && curatorNameValue !== null) {
+            if (typeof curatorNameValue !== 'string' || curatorNameValue.trim().length === 0) {
+                errors.push('playlist.curatorName must be a non-empty string');
+            }
+        }
         if (config.playlist?.role !== undefined || process.env.PLAYLIST_ROLE !== undefined) {
             try {
                 resolveEffectivePlaylistRole(config);

package/dist/src/utilities/index.js

@@ -505,7 +505,7 @@ async function buildPlaylistDirect(params, options = {}) {
         console.log(chalk.cyan('\nPublishing to feed server...'));
         try {
             const { publishPlaylist } = require('./playlist-publisher');
-            publishResult = await publishPlaylist(savedPath, playlistSettings.feedServer.baseUrl, playlistSettings.feedServer.apiKey);
+            publishResult = await publishPlaylist(savedPath, playlistSettings.feedServer.baseUrl);
             if (publishResult.success) {
                 console.log(chalk.green(`✓ Published to feed server`));
                 if (publishResult.playlistId) {

package/dist/src/utilities/playlist-builder.js

@@ -10,6 +10,7 @@
 const { PlaylistBuilder, PlaylistItemBuilder, DisplayPrefsBuilder, ProvenanceBuilder, ContractBuilder, ValidatePlaylist, slugify: dp1Slugify, generateId, } = require('dp1-js');
 const { getPlaylistConfig, getConfig } = require('../config');
 const { signPlaylist } = require('./playlist-signer');
+const { playlistSigningDidKey } = require('./signing-identity');
 const { buildInlineManifestForToken } = require('./ref-manifest');
 /** Default display background that passes DP-1 hex color validation. */
 const DEFAULT_BACKGROUND = '#111111';
@@ -482,9 +483,20 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
     }
     const playlist = playlistBuilder.build();
     // Sign the playlist if private key is configured.
+    //
+    // The curator declaration has to be written BEFORE signing. The feed accepts a create only when a
+    // signature's kid matches a key in the document's own curators[], and a signature covers curators[],
+    // so declaring it afterwards would invalidate the signature we just produced. A playlist built without
+    // this entry is signed but unpublishable, which is how `find --publish` used to fail.
     try {
         const playlistConfig = getPlaylistConfig();
         if (playlistConfig.privateKey) {
+            const key = playlistSigningDidKey(playlistConfig.privateKey);
+            const declared = Array.isArray(playlist.curators) ? playlist.curators : [];
+            // Respect a curator the caller already declared for this key; only add what is missing.
+            if (!declared.some((curator) => curator && curator.key === key)) {
+                playlist.curators = [...declared, { name: playlistConfig.curatorName || 'ff-cli', key }];
+            }
             playlist.signatures = [await signPlaylist(playlist, playlistConfig.privateKey)];
             delete playlist.signature;
         }

package/dist/src/utilities/playlist-publisher.js

@@ -18,17 +18,16 @@ const playlist_verifier_1 = require("./playlist-verifier");
  *
  * @param {string} filePath - Path to playlist JSON file
  * @param {string} feedServerUrl - Feed server base URL
- * @param {string} [apiKey] - Optional API key for authentication
  * @returns {Promise<Object>} Result with success status, playlistId, or error
  * @example
- * const result = await publishPlaylist('playlist.json', 'http://localhost:8787/api/v1', 'api-key');
+ * const result = await publishPlaylist('playlist.json', 'http://localhost:8787/api/v1');
  * if (result.success) {
  *   console.log(`Published with ID: ${result.playlistId}`);
  * } else {
  *   console.error(`Failed: ${result.error}`);
  * }
  */
-async function publishPlaylist(filePath, feedServerUrl, apiKey) {
+async function publishPlaylist(filePath, feedServerUrl) {
     try {
         // Step 1: Read and parse playlist file
         if (!fs_1.default.existsSync(filePath)) {
@@ -48,7 +47,31 @@ async function publishPlaylist(filePath, feedServerUrl, apiKey) {
                 error: `Invalid JSON in playlist file: ${filePath}`,
             };
         }
-        // Step 2: Verify signature integrity before publishing.
+        // Step 2: refuse legacy flat-signature documents outright, before verification.
+        //
+        // A flat `signature` string carries no kid, so the curator rule below has nothing to match and such
+        // a document would reach the feed only to be refused as unauthenticated — verified against a running
+        // feed. This runs ahead of verification deliberately: the document is unpublishable whether or not
+        // its legacy signature is valid, and 're-sign as a v1.1 envelope' is the remedy either way, which
+        // 'signature verification failed' would not convey.
+        const hasLegacyFlatSignature = typeof playlist.signature === 'string' &&
+            playlist.signature.trim().length > 0;
+        const hasEnvelope = Array.isArray(playlist.signatures)
+            ? (playlist.signatures ?? []).length > 0
+            : false;
+        if (!hasEnvelope && hasLegacyFlatSignature) {
+            return {
+                success: false,
+                error: 'Playlist carries a legacy flat signature, which the feed cannot authorize.',
+                message: `The feed authorizes a publish from a signatures[] envelope, matching a signature's kid\n` +
+                    `  against the playlist's own curators[]. A flat "signature" string carries no kid.\n` +
+                    `  Re-sign it as a DP-1 v1.1 envelope:\n` +
+                    `    1. remove the "signature" field\n` +
+                    `    2. declare your key: "curators": [{ "name": "Your name", "key": "<did:key from ff-cli status>" }]\n` +
+                    `    3. ff-cli sign <file>`,
+            };
+        }
+        // Step 3: Verify signature integrity before publishing.
         const deliveryResult = await (0, playlist_verifier_1.verifyPlaylist)(playlist);
         if (!deliveryResult.valid) {
             return {
@@ -57,17 +80,42 @@ async function publishPlaylist(filePath, feedServerUrl, apiKey) {
                 message: deliveryResult.details?.map((d) => `  • ${d.path}: ${d.message}`).join('\n'),
             };
         }
-        // Step 3: Send validated playlist to feed server
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        // Use provided apiKey, fallback to environment variable, or use empty string as last resort
-        const authKey = apiKey !== undefined ? apiKey : process.env.FEED_API_KEY || '';
-        if (authKey) {
-            headers['Authorization'] = `Bearer ${authKey}`;
+        // Step 4: fail here, not at the feed, when the signer is not declared as a curator.
+        //
+        // The feed accepts a create only when a signature's `kid` matches a key the document declares in
+        // `curators[]`. Signing alone does not satisfy that, and the server's answer — "no valid curator
+        // signature found" — reads as a signing problem, which sends people to check their key instead of
+        // their document. Checking locally turns a confusing 400 into an instruction, and costs no request.
+        const curatorKeys = new Set((Array.isArray(playlist.curators)
+            ? (playlist.curators ?? [])
+            : [])
+            .map((c) => (typeof c?.key === 'string' ? c.key.trim() : ''))
+            .filter((k) => k.length > 0));
+        const signatures = Array.isArray(playlist.signatures)
+            ? (playlist.signatures ?? [])
+            : [];
+        const signingKids = signatures
+            .map((sig) => (typeof sig?.kid === 'string' ? sig.kid.trim() : ''))
+            .filter((k) => k.length > 0);
+        if (signingKids.length > 0 && !signingKids.some((kid) => curatorKeys.has(kid))) {
+            return {
+                success: false,
+                error: 'Playlist is signed, but the signing key is not declared as a curator.',
+                message: `The feed accepts a publish when a signature's kid appears in the playlist's own curators[].\n` +
+                    `  Add this to the playlist before signing:\n` +
+                    `    "curators": [{ "name": "Your name", "key": "${signingKids[0]}" }]\n` +
+                    `  then sign again from the unsigned file — signing appends, so re-signing an already-signed\n` +
+                    `  playlist leaves the earlier signature covering a document that no longer exists.`,
+            };
         }
+        // Step 5: Send validated playlist to feed server.
+        //
+        // No auth header. The feed authorizes a create from the document's own signatures: it requires a
+        // signature whose kid matches a key declared in the playlist's `curators[]`. An API key is neither
+        // sent nor accepted -- the feed removed that path entirely -- so a playlist that is not self-signed
+        // by a declared curator is rejected no matter what credentials accompany it.
         const response = await axios_1.default.post(`${feedServerUrl}/playlists`, playlist, {
-            headers,
+            headers: { 'Content-Type': 'application/json' },
             timeout: 30000,
         });
         const playlistId = response.data?.id || response.data?.uuid;

package/dist/src/utilities/signing-identity.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * The `did:key` a signature from the configured playlist key will carry as its `kid`.
+ *
+ * The feed authorizes a create by matching a signature's `kid` against a key the document declares in
+ * `curators[]`. Until now that value existed nowhere a user could see: it appeared for the first time
+ * *inside* a signature, so learning it meant signing something first. That made the only correct
+ * publishing sequence — declare the curator, then sign — impossible to follow, and the obvious
+ * workaround is broken: signing appends to `signatures[]`, so signing to discover the kid, adding
+ * `curators[]`, then signing again leaves the first signature covering a document that no longer exists,
+ * and verification fails before upload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playlistSigningDidKey = playlistSigningDidKey;
+const node_crypto_1 = require("node:crypto");
+const ed25519_key_derive_1 = require("./ed25519-key-derive");
+/**
+ * Derive the `did:key` for playlist signing key material.
+ *
+ * Accepts everything the signer accepts (PKCS#8 base64, raw seed hex/base64, PEM), because a user who
+ * can sign with a key must be able to see the identity that signing will assert.
+ */
+function playlistSigningDidKey(privateKeyMaterial) {
+    const privateKey = (0, ed25519_key_derive_1.parsePlaylistPrivateKeyToKeyObject)(privateKeyMaterial);
+    const raw = (0, node_crypto_1.createPublicKey)(privateKey).export({ format: 'jwk' });
+    if (!raw.x) {
+        throw new Error('Could not derive a public key from the configured playlist signing key');
+    }
+    // JWK `x` for Ed25519 is the 32-byte public key, base64url.
+    const publicKey = Buffer.from(raw.x, 'base64url');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Ed25519DIDKey } = require('dp1-js');
+    return Ed25519DIDKey(publicKey);
+}

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

@@ -317,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"
     }
   ]
 }
@@ -383,12 +381,60 @@ 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)
 
@@ -399,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
@@ -409,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/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": {
@@ -278,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.4.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",