@feralfile/cli 2.4.0 → 2.6.0

package/dist/src/utilities/nft-indexer.js

@@ -128,6 +128,33 @@ function detectTokenStandard(chain, contractAddress) {
     }
     return 'other';
 }
+/**
+ * Token standards the indexer keys CIDs on. An asserted standard outside this
+ * set says nothing the CID can carry, so detection decides instead.
+ */
+const CID_STANDARDS = new Set(['erc721', 'erc1155', 'fa2']);
+/**
+ * resolveTokenStandard picks the standard a CID is built with.
+ *
+ * detectTokenStandard cannot tell ERC-721 from ERC-1155 — it has only a chain
+ * and an address, and answers erc721 for every EVM contract. The indexer keys
+ * the two differently (`eip155:1:erc721:…` and `eip155:1:erc1155:…`), so an
+ * ERC-1155 token looked up by detection alone is simply never found. When the
+ * caller knows the standard — a DP-1 playlist carries it in
+ * `provenance.contract.standard` — that assertion wins.
+ *
+ * @param {string} chain - Blockchain network
+ * @param {string} contractAddress - Contract address
+ * @param {string} [asserted] - Standard the caller vouches for, if any
+ * @returns {string} Token standard for the CID
+ */
+function resolveTokenStandard(chain, contractAddress, asserted) {
+    const normalized = typeof asserted === 'string' ? asserted.trim().toLowerCase() : '';
+    if (CID_STANDARDS.has(normalized)) {
+        return normalized;
+    }
+    return detectTokenStandard(chain, contractAddress);
+}
 /**
  * Build CAIP-2 token CID for indexer v2
  *
@@ -137,15 +164,19 @@ function detectTokenStandard(chain, contractAddress) {
  * @param {string} chain - Blockchain network (ethereum, polygon, tezos, etc)
  * @param {string} contractAddress - Contract address
  * @param {string} tokenId - Token ID
+ * @param {string} [standard] - Asserted token standard; detected when omitted
  * @returns {string} Token CID in CAIP-2 format
  * @example
  * // Returns: eip155:1:erc721:0xabc123:456
  * const cid = buildTokenCID('ethereum', '0xabc123', '456');
  * @example
+ * // Returns: eip155:1:erc1155:0xabc123:456
+ * const cid = buildTokenCID('ethereum', '0xabc123', '456', 'erc1155');
+ * @example
  * // Returns: tezos:mainnet:fa2:KT1abc:789
  * const cid = buildTokenCID('tezos', 'KT1abc', '789');
  */
-function buildTokenCID(chain, contractAddress, tokenId) {
+function buildTokenCID(chain, contractAddress, tokenId, standard) {
     // Map chain names to CAIP-2 format (supports only Ethereum and Tezos)
     const caip2Map = {
         ethereum: 'eip155:1',
@@ -157,8 +188,8 @@ function buildTokenCID(chain, contractAddress, tokenId) {
     if (!caip2Chain) {
         throw new Error(`Unsupported chain: ${chain}. Only ethereum and tezos are supported.`);
     }
-    const standard = detectTokenStandard(chain, contractAddress);
-    return `${caip2Chain}:${standard}:${contractAddress}:${tokenId}`;
+    const resolvedStandard = resolveTokenStandard(chain, contractAddress, standard);
+    return `${caip2Chain}:${resolvedStandard}:${contractAddress}:${tokenId}`;
 }
 /**
  * Unified GraphQL query for tokens from indexer v2
@@ -319,9 +350,10 @@ function getBestMediaUrl(display = {}, mediaAssets = []) {
  *
  * @param {Object} indexerData - Token fields from indexer GraphQL
  * @param {string} chain - Blockchain network
+ * @param {string} [standard] - Asserted token standard; detected when omitted
  * @returns {Object} Standardized token data
  */
-function mapIndexerDataToStandardFormat(indexerData, chain) {
+function mapIndexerDataToStandardFormat(indexerData, chain, standard) {
     if (!indexerData) {
         return {
             success: false,
@@ -334,14 +366,14 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
     const artistName = extractArtistName(display.artists);
     const name = display.name || `Token #${indexerData.token_number}`;
     const description = display.description || '';
-    const standard = detectTokenStandard(chain, indexerData.contract_address);
+    const resolvedStandard = resolveTokenStandard(chain, indexerData.contract_address, standard);
     return {
         success: true,
         token: {
             chain,
             contractAddress: indexerData.contract_address,
             tokenId: indexerData.token_number,
-            standard,
+            standard: resolvedStandard,
             name,
             description,
             image: {
@@ -492,8 +524,34 @@ function convertToDP1Item(tokenData, duration) {
     return {
         success: true,
         item: dp1Item,
+        still: stillOf(token),
     };
 }
+/**
+ * stillOf names the token's still image as the indexer identifies it, or ''.
+ *
+ * This is `display.image_url`, the field the indexer reserves for a still and
+ * the same one `buildInlineManifestForToken` writes into `thumbnails.default`.
+ * It is returned beside the DP-1 item rather than inside it because the item
+ * only carries the still when it differs from the item's own source, and a
+ * consumer building a manifest against a *different* source (see
+ * enrich-playlist.ts) needs the still regardless. Nothing about the URL's
+ * shape is inspected: the indexer's word that it is an image is the evidence,
+ * and a suffix check would reject the extensionless CDN URLs it commonly
+ * returns.
+ *
+ * @param {Object} token - Token in the internal standard format
+ * @returns {string} http(s) still URL, or '' when the indexer named none
+ */
+function stillOf(token) {
+    const image = token.image;
+    // Only `thumbnail` qualifies. `image.url` is the media getBestMediaUrl
+    // selected as the source, which is the live rendition whenever one exists —
+    // exactly what must never land in a thumbnail slot.
+    const candidate = typeof image === 'string' ? image : typeof image === 'object' && image ? image.thumbnail : '';
+    const trimmed = String(candidate || '').trim();
+    return trimmed.startsWith('http://') || trimmed.startsWith('https://') ? trimmed : '';
+}
 /**
  * Get NFT token information from indexer and return as DP1 item (supports single or batch)
  * @param {Object|Array} params - Token parameters (single object or array)
@@ -507,8 +565,8 @@ async function getNFTTokenInfo(params) {
         return await getNFTTokenInfoBatch(params.tokens, duration);
     }
     // Handle single token
-    const { chain, contractAddress, tokenId } = params;
-    const result = await getNFTTokenInfoSingle({ chain, contractAddress, tokenId }, duration);
+    const { chain, contractAddress, tokenId, standard } = params;
+    const result = await getNFTTokenInfoSingle({ chain, contractAddress, tokenId, standard }, duration);
     return result;
 }
 /**
@@ -530,7 +588,7 @@ async function getNFTTokenInfo(params) {
  */
 async function getNFTTokenInfoSingle(params, duration, options = {}) {
     let chain = params.chain;
-    const { contractAddress, tokenId } = params;
+    const { contractAddress, tokenId, standard } = params;
     // DEFENSIVE: Auto-detect and correct chain based on contract address format
     if (contractAddress.startsWith('KT') && chain !== 'tezos') {
         logger.warn(`[NFT Indexer] Chain mismatch detected! Contract ${contractAddress} starts with KT but chain="${chain}". Auto-correcting to "tezos".`);
@@ -547,7 +605,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
     });
     try {
         // Build token CID in CAIP-2 format
-        const tokenCID = buildTokenCID(chain, contractAddress, tokenId);
+        const tokenCID = buildTokenCID(chain, contractAddress, tokenId, standard);
         logger.info(`[NFT Indexer] Built token CID: ${tokenCID}`);
         // Query the indexer
         logger.info(`[NFT Indexer] Querying indexer GraphQL for token...`);
@@ -556,7 +614,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
         if (!indexerData) {
             logger.info(`[NFT Indexer] Token not in database, triggering async indexing...`);
             // Trigger background indexing workflow
-            const indexResult = await triggerIndexingAsync(chain, contractAddress, tokenId);
+            const indexResult = await triggerIndexingAsync(chain, contractAddress, tokenId, standard);
             if (!indexResult.success) {
                 logger.debug(`[NFT Indexer] Failed to trigger indexing:`, indexResult.error);
                 return {
@@ -609,7 +667,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
             }
         }
         // Map to standard format and convert to DP1
-        const tokenData = mapIndexerDataToStandardFormat(indexerData, chain);
+        const tokenData = mapIndexerDataToStandardFormat(indexerData, chain, standard);
         return convertToDP1Item(tokenData, duration);
     }
     catch (error) {
@@ -621,15 +679,21 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
     }
 }
 /**
- * Get NFT token information in batch and return as DP1 items (parallel processing)
+ * Resolve a batch of tokens and return every outcome (parallel processing)
  *
  * For missing tokens: triggers indexing per token, polls by job_id, then fetches again.
  *
- * @param {Array} tokens - Array of token parameters
+ * Unlike getNFTTokenInfoBatch this keeps one result per input token, in input
+ * order: a resolved token as `{ success: true, item, still }`, a failed one as
+ * `{ success: false, error, token }`. Callers that must know which request an
+ * answer belongs to, or that need the still beside the item, use this.
+ *
+ * @param {Array} tokens - Array of token parameters (chain, contractAddress, tokenId, standard?)
  * @param {number} duration - Display duration in seconds
- * @returns {Promise<Array>} Array of DP1 items
+ * @param {Function} [onProgress] - Called with (done, total) after each batch
+ * @returns {Promise<Array>} One result per input token
  */
-async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
+async function resolveTokenBatch(tokens, duration, onProgress) {
     logger.info(`[NFT Indexer] 📦 Starting batch processing for ${tokens.length} token(s)...`);
     logger.debug('[NFT Indexer] Batch tokens:', tokens);
     const results = [];
@@ -669,6 +733,23 @@ async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
     const successCount = results.filter((r) => r.success && r.item).length;
     const failedCount = results.length - successCount;
     logger.info(`[NFT Indexer] Final: ${successCount} items with data, ${failedCount} without`);
+    return results;
+}
+/**
+ * Get NFT token information in batch and return as DP1 items (parallel processing)
+ *
+ * For missing tokens: triggers indexing per token, polls by job_id, then fetches again.
+ *
+ * Returns only the resolved items. Failures are dropped, not represented, so
+ * the result is neither aligned with nor as long as the input; a caller that
+ * needs the association uses resolveTokenBatch.
+ *
+ * @param {Array} tokens - Array of token parameters
+ * @param {number} duration - Display duration in seconds
+ * @returns {Promise<Array>} Array of DP1 items
+ */
+async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
+    const results = await resolveTokenBatch(tokens, duration, onProgress);
     // Return only items (not error objects)
     const items = results.filter((r) => r.success && r.item).map((r) => r.item);
     logger.info(`[NFT Indexer] Returning ${items.length} items`);
@@ -719,10 +800,10 @@ async function getCollectionInfo(params) {
  * @returns {number} [returns.job_id] - Postgres queue job id; use with jobStatus / pollForJobCompletion
  * @returns {string} [returns.error] - Error message if failed
  */
-async function triggerIndexingAsync(chain, contractAddress, tokenId) {
+async function triggerIndexingAsync(chain, contractAddress, tokenId, standard) {
     try {
         // Build token CID
-        const tokenCID = buildTokenCID(chain, contractAddress, tokenId);
+        const tokenCID = buildTokenCID(chain, contractAddress, tokenId, standard);
         logger.debug('[NFT Indexer] Triggering token indexing job via GraphQL mutation:', {
             tokenCID,
         });
@@ -1050,6 +1131,7 @@ module.exports = {
     getNFTTokenInfo,
     // Batch processing
     getNFTTokenInfoBatch,
+    resolveTokenBatch,
     // Single token processing
     getNFTTokenInfoSingle,
     // Additional functions

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

@@ -10,9 +10,18 @@
 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';
+/**
+ * DP-1 signature role that carries ownership of a playlist.
+ *
+ * The feed derives a playlist's owners from `curators[]` and then requires one of those keys to have
+ * signed as `curator`: being named is a claim, signing in this role is the proof. Playlist groups use
+ * the same role; channels use `publisher`, which ff-cli does not publish.
+ */
+const PLAYLIST_OWNER_ROLE = 'curator';
 /**
  * isTimeBasedMedia reports whether an item's media has an intrinsic runtime
  * (video or audio) per DP-1 §4.1 "time-based sources".
@@ -482,10 +491,30 @@ 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) {
-            playlist.signatures = [await signPlaylist(playlist, 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 }];
+            }
+            // Sign in the `curator` role, not the configured one. Declaring the key in curators[] is the
+            // document claiming that key is an owner; the feed treats a declared key as an owner only when the
+            // same key also signed in the owner role, so any other role leaves the document declared, verified
+            // and unpublishable — the exact shape that made every ff-cli playlist fail before (#107). The role
+            // has to follow the claim the builder just wrote. `playlist.role` still governs `ff-cli sign`,
+            // where the user chooses what claim to make; to build under a different role, build without a
+            // configured key and sign the result explicitly.
+            playlist.signatures = [
+                await signPlaylist(playlist, playlistConfig.privateKey, PLAYLIST_OWNER_ROLE),
+            ];
             delete playlist.signature;
         }
     }

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

@@ -34,6 +34,25 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.castPlaylist = castPlaylist;
+/**
+ * DP-1 signature role used when signing a playlist for playback.
+ *
+ * A cast never passes through a feed, so a document signed here carries no `feed` signature and its own
+ * entry is the only one a player could judge. DP-1 §7.1.1 rule 1 has players verify a `feed` or `curator`
+ * signature, so the configured role (shipped default `agent`) is the weakest choice available for a
+ * document this CLI is minting itself.
+ *
+ * Scope: this governs only the envelope the CLI *creates* — direct media, which arrives unsigned and must
+ * be signed before delivery. A playlist that already carries signatures is cast verbatim whatever its
+ * roles, because rewriting someone else's envelope is not this function's business. No player in this
+ * ecosystem enforces rule 1 today (ff-player performs no signature verification at all), so this is about
+ * not minting the weakest document we could, rather than about a failure observed on a device.
+ *
+ * This also has to match what the builder wrote: a wrapped media URL arrives here already declaring the
+ * signing key in `curators[]` and signed as `curator`, and signing REPLACES `signatures[]` rather than
+ * appending — so any other role here silently downgrades that envelope on its way to the device.
+ */
+const PLAYBACK_SIGNING_ROLE = 'curator';
 // playlist-signer and ff1-device are still CommonJS; require keeps interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { signPlaylist } = require('./playlist-signer');
@@ -68,7 +87,7 @@ async function castPlaylist(playlist, options = {}) {
                 };
             }
             try {
-                const signature = await signPlaylist(current, options.signingKey);
+                const signature = await signPlaylist(current, options.signingKey, PLAYBACK_SIGNING_ROLE);
                 current = {
                     ...current,
                     signature: undefined,

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

@@ -7,6 +7,12 @@ exports.publishPlaylist = publishPlaylist;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = __importDefault(require("fs"));
 const playlist_verifier_1 = require("./playlist-verifier");
+/**
+ * DP-1 signature role that carries ownership of a playlist.
+ *
+ * Mirrors the feed's owner role for playlists (channels use `publisher`, which ff-cli does not publish).
+ */
+const OWNER_ROLE = 'curator';
 /**
  * Publish a verified playlist to a DP-1 feed server
  *
@@ -18,17 +24,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 +53,33 @@ 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> -r ${OWNER_ROLE}\n` +
+                    `  The role matters: a declared key counts as an owner only when it also signed as "${OWNER_ROLE}",\n` +
+                    `  and plain "ff-cli sign" uses playlist.role, which defaults to "agent".`,
+            };
+        }
+        // Step 3: Verify signature integrity before publishing.
         const deliveryResult = await (0, playlist_verifier_1.verifyPlaylist)(playlist);
         if (!deliveryResult.valid) {
             return {
@@ -57,17 +88,103 @@ 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);
+        const declaredSignatures = signatures.filter((sig) => curatorKeys.has(typeof sig?.kid === 'string' ? sig.kid.trim() : ''));
+        // Same predicate as `no declared signature`, expressed through the set the next gate also needs.
+        if (signingKids.length > 0 && declaredSignatures.length === 0) {
+            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, with the same key you just declared:\n` +
+                    `    ff-cli sign <file> -r ${OWNER_ROLE} --key <private key for ${signingKids[0]}>\n` +
+                    `  Drop --key if that key is your configured one; "sign" uses the configured key otherwise, and a\n` +
+                    `  signature from an undeclared key would not satisfy the feed. The role is ff-cli's requirement\n` +
+                    `  rather than every feed's: see the owner-role check for why publishing without it is refused.\n` +
+                    `  Start from the unsigned file\n` +
+                    `  because declaring curators[] changes the signed payload: signing appends, so the earlier\n` +
+                    `  signature would be left covering a document that no longer exists.`,
+            };
+        }
+        // Step 4b: a declared key must also have signed AS curator.
+        //
+        // Being named in curators[] is a claim; signing in the owner role is the proof, and the feed requires
+        // both before it treats a key as an owner. A document that is declared but signed under another role
+        // (ff-cli's own default was `agent`) verifies cleanly and is still refused, and the server answers in
+        // terms of ownership — which reads as "fix curators[]", the one part that is already correct. Naming
+        // the role and the remedy here is the difference between a one-flag fix and a wrong-end search.
+        //
+        // This is deliberately stricter than a feed that ignores the role: such a feed accepts the document
+        // today and freezes it the moment role-aware ownership lands, because a replace and a delete both
+        // need an owner signature the document does not carry. Refusing now keeps that document from being
+        // created at all.
+        if (declaredSignatures.length > 0 &&
+            !declaredSignatures.some((sig) => sig.role === OWNER_ROLE)) {
+            const rolesUsed = [
+                ...new Set(declaredSignatures
+                    .map((sig) => (typeof sig.role === 'string' ? sig.role.trim() : ''))
+                    .filter((role) => role.length > 0)),
+            ];
+            const seen = rolesUsed.length > 0 ? rolesUsed.map((role) => `"${role}"`).join(', ') : 'no role';
+            // List every key eligible to repair this, not the one that happens to have signed.
+            //
+            // The gate above accepts an owner-role signature from ANY declared key, so on a playlist declaring
+            // several curators the holder of any one of them can append it. Naming only the key that signed
+            // under the wrong role describes an impossible fix to everyone else — they may not hold it — while
+            // a key they do hold would have worked. `sign` still defaults to the configured key, which need not
+            // be declared at all, so the eligible set has to be stated rather than assumed.
+            const eligibleKeys = [...curatorKeys];
+            const eligibleList = eligibleKeys.length > 0 ? eligibleKeys.join(', ') : 'a key declared in curators[]';
+            return {
+                success: false,
+                error: `Playlist is signed by a declared curator, but under a non-owner role (${seen}).`,
+                message: `This is ff-cli's check, not a feed's answer. Feeds are moving to role-aware ownership, where\n` +
+                    `  a key in curators[] counts as an owner only if it also signed as "${OWNER_ROLE}". A feed that\n` +
+                    `  does not check the role yet will accept this document, and then be unable to authorize a\n` +
+                    `  replace or a delete for it: both need an owner signature it does not carry. Publishing it is\n` +
+                    `  what makes that permanent, so ff-cli refuses here instead.\n` +
+                    `\n` +
+                    `  curators[] is already correct — only the role is missing, so add that signature to this file:\n` +
+                    `    ff-cli sign <file> -r ${OWNER_ROLE} --key <private key for a declared curator>\n` +
+                    `  Any key this playlist declares will do — you do not need the one that signed under the wrong\n` +
+                    `  role. Declared: ${eligibleList}\n` +
+                    `  It must be one of those: a ${OWNER_ROLE} signature from an undeclared key satisfies neither\n` +
+                    `  this check nor role-aware ownership, since both read roles only from declared keys. "sign"\n` +
+                    `  uses the configured key unless --key says otherwise; drop --key if a declared key is already\n` +
+                    `  your configured one, and confirm which identity a key carries with\n` +
+                    `  "ff-cli status --key <private key>".\n` +
+                    `  Signing appends, and the payload hash excludes signatures, so the existing entry stays valid\n` +
+                    `  and the document ends up carrying both. No unsigned copy is needed: you only have to start\n` +
+                    `  from one when changing signed content such as curators[] itself.`,
+            };
         }
+        // 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,7 +50,20 @@ 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.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`).
+- `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 used by `ff-cli sign`. 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`). It does **not** apply to `find` and `build`, which always sign as `curator` — see [Signing role and ownership](#signing-role-and-ownership).
 
 ### Generate an Ed25519 private key
 
@@ -75,6 +88,33 @@ Paste the value into `playlist.privateKey`. Any of these are accepted:
 
 If you need a different role, set `playlist.role` to one of the DP-1 signing roles such as `agent`, `feed`, `curator`, `institution`, or `licensor`. The CLI rejects any other string before it reaches `dp1-js`.
 
+### Signing role and ownership
+
+A feed decides who owns a playlist from the document itself: the keys in `curators[]` are the owner set.
+Under **role-aware ownership**, a key counts as an owner only when that same key *also signed in the
+`curator` role* — being named is a claim, signing as `curator` is the proof.
+
+`ff-cli publish` requires that role. **This is ff-cli's check, not every feed's answer today**: a feed that
+does not yet enforce roles accepts an `agent`-signed document, so a manual upload of the same file can
+still succeed. It is refused here because once accepted, such a document 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 it. Publishing is
+what makes that permanent.
+
+The `kid`-to-`curators[]` match is different: feeds enforce that today, and a playlist failing it is
+rejected by the server regardless of ff-cli.
+
+Two consequences:
+
+- `find` and `build` declare your key in `curators[]` and therefore always sign as `curator`, whatever
+  `playlist.role` says. To build under a different role, build without a configured signing key and sign the
+  result yourself with `ff-cli sign --role`.
+- `ff-cli publish` refuses a playlist whose declared key signed under another role, and names the fix
+  (`ff-cli sign <file> -r curator`, from any key declared in `curators[]`). This runs before any request,
+  so it costs nothing — and deliberately does not defer to a feed that would accept the document today,
+  because acceptance is what makes it unfixable.
+
+Channels use `publisher` as the owner role instead of `curator`; ff-cli does not publish channels.
+
 If you already have a base64 key and want hex, convert it:
 
 ```bash