@feralfile/cli 2.3.0 → 2.5.0

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

@@ -0,0 +1,459 @@
+"use strict";
+/**
+ * Fills in missing inline Ref Manifests on an existing DP-1 playlist.
+ *
+ * `find` and `build` attach an `inlineManifest` to every item they create, so
+ * playlists this CLI authors end to end are already labelled. Playlists that
+ * arrive any other way are not: items copied out of another playlist, items
+ * hand-written against a known contract, items inherited from a document
+ * predating §3.6. Those carry a `source` and a `provenance` block and nothing
+ * else, and there was no way to repair them short of editing JSON by hand.
+ *
+ * What the gap costs is visible on a device. The FF1 tombstone resolves its
+ * label through `ref` -> `inlineManifest` -> `item.metadata` and falls back to
+ * the item title, so an unlabelled item shows a title with no artist line. The
+ * app's grid is worse: it can rasterize a thumbnail from a direct image, video,
+ * or SVG source, but not from a live HTML work, so every generative item in an
+ * unlabelled playlist renders as an empty tile. A playlist of computational art
+ * is mostly live HTML, which is exactly the case that looks broken.
+ *
+ * Enrichment is additive and narrow on purpose. It writes `inlineManifest` and
+ * nothing else: `source`, `duration`, `id`, and `display` are the curator's
+ * decisions and are left exactly as found, even when the indexer disagrees. An
+ * item the indexer cannot resolve is reported, never guessed at — a fabricated
+ * artist line in a signed document is worse than a missing one.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichPlaylistManifests = enrichPlaylistManifests;
+const node_crypto_1 = require("node:crypto");
+const logger = __importStar(require("../logger"));
+/**
+ * CHAIN_ALIASES translates a DP-1 chain name into the indexer's, outbound.
+ *
+ * DP-1 names the EVM family `evm` (core spec §6: "evm" | "tezos" | "bitmark" |
+ * "other"), because the protocol describes a class of chains. The FF indexer
+ * names the same thing `ethereum`, because it queries a specific one. Without
+ * this every EVM item comes back unresolved, and the failure looks like a
+ * missing artwork rather than a vocabulary mismatch.
+ *
+ * Unlisted values pass through so the indexer, not this table, decides what it
+ * supports.
+ */
+const CHAIN_ALIASES = {
+    evm: 'ethereum',
+};
+/**
+ * `evm` names a family, and this maps it to one member of that family.
+ *
+ * DP-1 core §6 offers "evm" | "tezos" | "bitmark" | "other" and carries no
+ * network identity, while the indexer maps Ethereum, Polygon, Arbitrum,
+ * Optimism, Base, and Zora all back to `evm`. So a DP-1 coordinate cannot say
+ * which EVM network it means, and neither can the response.
+ *
+ * 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 everything else. A --chain flag would not widen that — it would
+ * only move the throw. The residual risk is narrow and real: an L2 work whose
+ * address and token id also exist on Ethereum would be enriched with the
+ * Ethereum work's metadata, and nothing in the response could reveal it.
+ *
+ * The count is surfaced so the assumption is stated at the point of use rather
+ * than buried here. Widening it belongs upstream, in the indexer client.
+ */
+const AMBIGUOUS_CHAIN = 'evm';
+/**
+ * One CLI invocation stamps one manifest timestamp, matching ref-manifest.ts:
+ * a run that synthesizes several manifests should not write several clocks.
+ */
+const MANIFEST_CREATED = new Date().toISOString();
+/**
+ * canonicalChain collapses both vocabularies onto one name so a coordinate
+ * sent to the indexer and a coordinate read back off its response compare
+ * equal. The direction is deliberately the reverse of CHAIN_ALIASES: this one
+ * is for matching, that one is for querying.
+ */
+function canonicalChain(chain) {
+    const lower = chain.trim().toLowerCase();
+    return lower === 'ethereum' ? 'evm' : lower;
+}
+/**
+ * coordinateKeyOf builds the correlation key for a provenance block, or null
+ * when the block cannot identify a single work.
+ *
+ * The address is lowercased because the indexer echoes it checksummed while
+ * callers typically write it lowercase, and the two must still match.
+ */
+function coordinateKeyOf(provenance) {
+    const contract = provenance?.contract;
+    if (!contract) {
+        return null;
+    }
+    const { chain, address, tokenId } = contract;
+    if (!chain || !address || tokenId === undefined || tokenId === null) {
+        return null;
+    }
+    const token = String(tokenId).trim();
+    if (token.length === 0) {
+        return null;
+    }
+    return `${canonicalChain(chain)}:${address.trim().toLowerCase()}:${token}`;
+}
+/**
+ * describeItem names an item for operator output, preferring its title.
+ */
+function describeItem(item, index) {
+    const title = typeof item.title === 'string' ? item.title.trim() : '';
+    return title.length > 0 ? title : `item ${index + 1}`;
+}
+/**
+ * coordinateFor extracts a lookup key from an item, or null when the item
+ * carries no usable on-chain coordinate.
+ *
+ * All three parts are required. A contract with no token id identifies a
+ * collection rather than a work, and resolving that would attach some other
+ * item's manifest to this one.
+ */
+function coordinateFor(item) {
+    const contract = item.provenance?.contract;
+    if (!contract) {
+        return null;
+    }
+    const { chain, address, tokenId } = contract;
+    if (!chain || !address || tokenId === undefined || tokenId === null) {
+        return null;
+    }
+    const token = String(tokenId).trim();
+    if (token.length === 0) {
+        return null;
+    }
+    const normalized = chain.trim().toLowerCase();
+    return {
+        chain: CHAIN_ALIASES[normalized] ?? normalized,
+        contractAddress: address,
+        tokenId: token,
+    };
+}
+/**
+ * stillFromIndexerSource recovers a thumbnail the manifest builder suppressed.
+ *
+ * `resolveStillUri` blanks a still that equals the source it was given, on the
+ * reasonable ground that pointing a thumbnail at the artwork itself adds
+ * payload and no information. But the source it was given is the one the
+ * INDEXER chose, not the one the curator kept. For a static work the indexer
+ * commonly selects the still as the source, so the thumbnail is dropped —
+ * and when the curator's item points at a live HTML generator instead, the
+ * item ends up with no still at all. That is precisely the case this command
+ * exists to repair: a live work the app cannot rasterize, whose grid tile
+ * stays empty.
+ *
+ * Recovering it is the inverse of the suppression. When the indexer's source
+ * differs from the item's and is an http(s) URL, that source IS the still that
+ * was elided, so it becomes the thumbnail relative to the item's own source.
+ */
+function stillFromIndexerSource(item, resolved) {
+    const indexerSource = typeof resolved.source === 'string' ? resolved.source.trim() : '';
+    const itemSource = typeof item.source === 'string' ? item.source.trim() : '';
+    if (!indexerSource || indexerSource === itemSource) {
+        return '';
+    }
+    if (!indexerSource.startsWith('http://') && !indexerSource.startsWith('https://')) {
+        return '';
+    }
+    // The indexer's source is not necessarily a still. getBestMediaUrl prefers
+    // display.animation_url and media assets over display.image_url, so it is
+    // frequently a live HTML rendition — and writing one into the thumbnail slot
+    // is worse than leaving the slot empty: the grid still cannot rasterize it,
+    // and the item now claims a still it does not have.
+    //
+    // Only a URL that is demonstrably an image is used. The indexer exposes no
+    // separately identified still on the item this command receives, so the file
+    // extension is the evidence available; carrying a real image field through
+    // the batch result would be the better fix and belongs upstream.
+    return looksLikeImage(indexerSource) ? indexerSource : '';
+}
+/**
+ * Media the app can draw a grid tile from, matching the types
+ * playlist-builder.js already recognizes. SVG and video belong here: the app
+ * rasterizes both, and excluding them left works with the empty tile this
+ * command exists to remove. HTML is deliberately absent — an unrasterizable
+ * page in the thumbnail slot is worse than an empty slot, because the item
+ * then claims a still it does not have.
+ */
+const RASTERIZABLE_EXTENSIONS = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.bmp',
+    '.svg',
+    '.mp4',
+    '.webm',
+];
+/**
+ * looksLikeImage tests a URL's path extension, ignoring query and fragment.
+ */
+function looksLikeImage(url) {
+    let pathname = url;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url.split('?')[0].split('#')[0];
+    }
+    const lower = pathname.toLowerCase();
+    return RASTERIZABLE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+/**
+ * hasThumbnail reports whether a manifest already carries a default still.
+ */
+function hasThumbnail(manifest) {
+    const thumbnails = manifest.metadata
+        ?.thumbnails;
+    return typeof thumbnails?.default?.uri === 'string' && thumbnails.default.uri.length > 0;
+}
+/**
+ * manifestFor returns the manifest to write onto an item, or undefined when
+ * the indexer resolved the token without building one.
+ *
+ * The curator's own title wins. `item.title` survives enrichment untouched,
+ * but the tombstone reads the manifest first, so attaching an indexer title
+ * that disagrees would change the displayed label while appearing to preserve
+ * it — the indexer writes "Pre-Process #0" where a curator wrote
+ * "Pre-Process". Everything else in the manifest (artist, description,
+ * thumbnails) is what enrichment exists to fetch and is taken as given.
+ */
+function manifestFor(item, resolved) {
+    const still = stillFromIndexerSource(item, resolved);
+    let manifest = resolved.inlineManifest;
+    let rekey = false;
+    if (manifest && still && !hasThumbnail(manifest)) {
+        manifest = {
+            ...manifest,
+            metadata: {
+                ...(manifest.metadata ?? {}),
+                thumbnails: { default: { uri: still } },
+            },
+        };
+        rekey = true;
+    }
+    else if (!manifest && still) {
+        // Nothing was emitted because the still was the only content the token
+        // had, and it had been suppressed. A thumbnail-only manifest is worth its
+        // payload in a way a title-only one is not: it is the difference between
+        // a grid tile and an empty square.
+        const synthesizedTitle = typeof item.title === 'string' ? item.title.trim() : '';
+        manifest = {
+            refVersion: '1.1.0',
+            id: derivedManifestId('', `${synthesizedTitle}\n${still}`),
+            created: MANIFEST_CREATED,
+            locale: 'en',
+            metadata: {
+                ...(synthesizedTitle ? { title: synthesizedTitle } : {}),
+                thumbnails: { default: { uri: still } },
+            },
+        };
+    }
+    if (!manifest) {
+        return undefined;
+    }
+    const metadata = manifest.metadata ?? {};
+    const curatorTitle = typeof item.title === 'string' ? item.title.trim() : '';
+    const overrideTitle = curatorTitle.length > 0 && metadata.title !== curatorTitle;
+    // The id is derived from the finished payload every time, not 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
+    // rather than floating free of it, and stays deterministic across runs.
+    //
+    // `rekey` is read only to record that a thumbnail was recovered; the
+    // derivation below covers it either way.
+    void rekey;
+    const finalMetadata = overrideTitle ? { ...metadata, title: curatorTitle } : metadata;
+    return {
+        ...manifest,
+        id: derivedManifestId(typeof manifest.id === 'string' ? manifest.id : '', stableStringify(finalMetadata)),
+        metadata: finalMetadata,
+    };
+}
+/**
+ * stableStringify serializes a value with object keys in sorted order, so the
+ * same content hashes the same however it was assembled.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * derivedManifestId produces a stable id for a manifest whose title this
+ * command replaced, shaped as a UUID so it reads like every other manifest id.
+ */
+function derivedManifestId(originalId, title) {
+    const digest = (0, node_crypto_1.createHash)('sha256').update(`${originalId}\n${title}`).digest('hex');
+    return [
+        digest.slice(0, 8),
+        digest.slice(8, 12),
+        digest.slice(12, 16),
+        digest.slice(16, 20),
+        digest.slice(20, 32),
+    ].join('-');
+}
+/**
+ * enrichPlaylistManifests attaches an inline Ref Manifest to every item that
+ * lacks one and can be resolved on chain.
+ *
+ * The playlist is mutated in place and returned; callers that need the
+ * original should read it twice. Items are looked up in one batch so the
+ * indexer sees a single burst rather than a request per item — warming
+ * previously-unseen tokens is the slow path, and it parallelizes internally.
+ *
+ * Signatures are dropped when anything changed, in both the DP-1 v1.1.0
+ * `signatures[]` form and the legacy flat `signature` this repo still verifies.
+ * A signature covers the document bytes, and an enriched document is a
+ * different document; leaving a stale envelope in place would produce a file
+ * that fails verification at the device with no explanation of why.
+ */
+async function enrichPlaylistManifests(playlist, lookup, options = {}) {
+    const items = Array.isArray(playlist.items) ? playlist.items : [];
+    const skipped = [];
+    const pending = [];
+    // One lookup per distinct artwork, not per item. getNFTTokenInfoBatch runs a
+    // lookup for each token it is handed, and a token the indexer has not seen
+    // triggers an indexing job and a poll that can take minutes. A playlist that
+    // deliberately repeats a work — the same piece at two points in a loop —
+    // would otherwise submit that job once per appearance.
+    const coordinates = new Map();
+    items.forEach((item, index) => {
+        // An item with a `ref` is already labelled, by a manifest this command
+        // cannot see. Ref outranks inlineManifest in the resolution order, so
+        // enriching one writes a manifest the device will ignore while still
+        // invalidating the signature: damage with no visible change.
+        //
+        // --force does not override this. Making the inline manifest win would
+        // mean deleting the curator's `ref` and `refHash`, which is a different
+        // and larger decision than filling in missing metadata — and one that
+        // silently discards the integrity hash the remote manifest is checked
+        // against. If that conversion is ever wanted it should be its own flag,
+        // named for what it does.
+        if (typeof item.ref === 'string' && item.ref.trim().length > 0) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'external-ref' });
+            return;
+        }
+        if (item.inlineManifest && !options.force) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'already-labelled' });
+            return;
+        }
+        const coordinate = coordinateFor(item);
+        const key = coordinateKeyOf(item.provenance);
+        if (!coordinate || !key) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'no-provenance' });
+            return;
+        }
+        // `evm` names a family and the response cannot narrow it, so enriching one
+        // on the assumption of Ethereum can attach a different artwork's artist,
+        // description, and still — into a document the curator then signs. The
+        // operator has to assert the network; the command will not assume it.
+        if (key.startsWith(`${AMBIGUOUS_CHAIN}:`) && !options.assumeEthereum) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'ambiguous-chain' });
+            return;
+        }
+        pending.push({ index, key });
+        if (!coordinates.has(key)) {
+            coordinates.set(key, coordinate);
+        }
+    });
+    const assumedEthereum = [...coordinates.keys()].filter((key) => key.startsWith(`${AMBIGUOUS_CHAIN}:`)).length;
+    if (pending.length === 0) {
+        return { playlist, enriched: 0, skipped, signatureInvalidated: false, assumedEthereum: 0 };
+    }
+    const resolved = await lookup([...coordinates.values()], options.onProgress);
+    // Index what came back by its own coordinate. A response carrying no usable
+    // provenance cannot be attributed to any request, so it is dropped rather
+    // than guessed at; the affected item then reports as not-indexed, which is
+    // exactly what happened.
+    const byCoordinate = new Map();
+    for (const entry of resolved) {
+        const key = coordinateKeyOf(entry.provenance);
+        if (key && !byCoordinate.has(key)) {
+            byCoordinate.set(key, entry);
+        }
+    }
+    let enriched = 0;
+    for (const entry of pending) {
+        const item = items[entry.index];
+        const match = byCoordinate.get(entry.key);
+        const manifest = match ? manifestFor(item, match) : undefined;
+        if (!manifest) {
+            // The indexer resolving a token and the indexer having anything worth
+            // attaching are different outcomes. buildInlineManifestForToken returns
+            // undefined when it has only a title, because a title-only manifest adds
+            // payload to every transfer without adding information. Reporting that
+            // as "the indexer returned nothing" would be false.
+            skipped.push({
+                index: entry.index,
+                title: describeItem(item, entry.index),
+                reason: match ? 'no-metadata' : 'not-indexed',
+            });
+            continue;
+        }
+        item.inlineManifest = manifest;
+        enriched += 1;
+    }
+    const hadSignature = playlist.signatures !== undefined || playlist.signature !== undefined;
+    const signatureInvalidated = enriched > 0 && hadSignature;
+    if (signatureInvalidated) {
+        delete playlist.signatures;
+        delete playlist.signature;
+        logger.debug('[Enrich] Dropped signatures: the enriched document must be re-signed.');
+    }
+    skipped.sort((a, b) => a.index - b.index);
+    return { playlist, enriched, skipped, signatureInvalidated, assumedEthereum };
+}

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/nft-indexer.js

@@ -4,10 +4,19 @@
  * to retrieve comprehensive token information.
  */
 const { PlaylistItemBuilder, ProvenanceBuilder, ContractBuilder } = require('dp1-js');
-// Production by default. INDEXER_API_URL exists so tests can point the
-// client at a local mock, the same way RASTER_API_URL already works — it
-// is not user-facing configuration, which stays removed (initializeIndexer).
-const GRAPHQL_ENDPOINT = process.env.INDEXER_API_URL || 'https://indexer.feralfile.com/graphql';
+// The production endpoint is hardcoded, as PROJECT_SPEC states, and stays
+// that way. INDEXER_API_URL is a test hook, not configuration: the
+// find-command suite spawns the CLI as a child process, so the only way to
+// point it at a local mock is through the environment.
+//
+// It is gated on NODE_ENV=test because index.ts loads dotenv at startup. An
+// ungated read would mean a stray INDEXER_API_URL in someone's .env, or an
+// inherited shell value, silently redirecting every token lookup and indexing
+// mutation — a configuration surface nobody documented and no one would think
+// to check. The gate keeps the hook usable without creating that surface.
+const GRAPHQL_ENDPOINT = process.env.NODE_ENV === 'test' && process.env.INDEXER_API_URL
+    ? process.env.INDEXER_API_URL
+    : 'https://indexer.feralfile.com/graphql';
 const { fetchWithTimeout } = require('./http');
 const logger = require('../logger');
 const { applyTimingToItemBuilder, buildDefaultDisplay } = require('./playlist-builder');

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);
+}