@feralfile/cli 2.3.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/index.js

@@ -28,6 +28,7 @@ const play_1 = require("./src/commands/play");
 const publish_1 = require("./src/commands/publish");
 const find_1 = require("./src/commands/find");
 const build_1 = require("./src/commands/build");
+const enrich_1 = require("./src/commands/enrich");
 const config_1 = require("./src/commands/config");
 const ssh_1 = require("./src/commands/ssh");
 const device_1 = require("./src/commands/device");
@@ -55,6 +56,7 @@ program.addCommand(sign_1.signCommand);
 program.addCommand(play_1.playCommand);
 program.addCommand(publish_1.publishCommand);
 program.addCommand(find_1.findCommand);
+program.addCommand(enrich_1.enrichCommand);
 program.addCommand(build_1.buildCommand);
 program.addCommand(config_1.configCommand);
 program.addCommand(ssh_1.sshCommand);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.3.0",
+    "version": "2.5.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",

package/dist/src/commands/enrich.js

@@ -0,0 +1,315 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichCommand = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const enrich_playlist_1 = require("../utilities/enrich-playlist");
+const playlist_verifier_1 = require("../utilities/playlist-verifier");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
+/**
+ * writePlaylistAtomically replaces a file only once the new bytes are safely on
+ * disk.
+ *
+ * The default destination is the input file, and a plain write truncates it
+ * first. Enrichment runs after a lookup that can take minutes while the indexer
+ * warms tokens, so the window between truncation and a complete write is a
+ * window in which an interruption, a full disk, or an I/O error leaves the
+ * curator with an empty or half-written playlist and no copy of what they had.
+ * A rename within the same directory is atomic, so the original file survives
+ * intact until the replacement is complete.
+ *
+ * The temporary file is created alongside the destination rather than in the
+ * system temp directory: rename is only atomic within a filesystem, and those
+ * are not guaranteed to be the same one.
+ */
+async function writePlaylistAtomically(destination, contents, expectedDigest) {
+    // Follow a symlink to its target before replacing anything. rename() would
+    // replace the link itself, silently detaching a playlist that other paths
+    // reach through that name while reporting success.
+    let target = destination;
+    const existing = await fs_1.promises.lstat(destination).catch(() => null);
+    if (existing?.isSymbolicLink()) {
+        target = await fs_1.promises.realpath(destination);
+    }
+    const temporary = (0, path_1.join)((0, path_1.dirname)(target), `.${(0, path_1.basename)(target)}.${process.pid}.${(0, crypto_1.randomBytes)(4).toString('hex')}.tmp`);
+    // The destination's mode has to be known before the file exists, not after
+    // it holds the contents. Creating at the default 0o666-minus-umask and
+    // chmod'ing afterwards leaves the enriched playlist readable by other local
+    // users for the length of the write — short, but a disclosure window on a
+    // file the curator deliberately restricted.
+    const current = await fs_1.promises.stat(target).catch(() => null);
+    const mode = current ? current.mode & 0o7777 : undefined;
+    try {
+        // 'wx' fails rather than truncating if the name somehow exists, so a
+        // collision can never destroy another process's work in progress.
+        const handle = await fs_1.promises.open(temporary, 'wx', mode);
+        try {
+            // open() applies the mode through umask, which can strip bits the
+            // destination had. chmod is not subject to umask, so this restores the
+            // exact mode — still before any bytes are written.
+            if (mode !== undefined) {
+                await handle.chmod(mode);
+            }
+            // A replacement is a new inode, so it carries this process's ownership
+            // rather than the destination's. Silently reassigning a playlist that
+            // belongs to another user or a shared group can lock collaborators out
+            // of it, or widen who can reach it. Carry the ownership across, and when
+            // that is not permitted refuse the in-place replacement instead of
+            // completing it with different access than the file had.
+            if (current && (current.uid !== process.getuid?.() || current.gid !== process.getgid?.())) {
+                try {
+                    await handle.chown(current.uid, current.gid);
+                }
+                catch {
+                    await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+                    throw new OwnershipError(target);
+                }
+            }
+            await handle.writeFile(contents);
+            // rename() is atomic against concurrent readers but says nothing about
+            // power loss: the directory entry can reach disk before the data it
+            // points at. Without this a crash mid-write can leave the playlist
+            // present and empty, which is the outcome the temporary file exists to
+            // prevent. Sync the contents first, then the directory entry after.
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // Checked here, as late as the sequence allows: everything expensive is
+        // already done, so the interval between this read and the rename below is
+        // a few syscalls rather than the minutes a lookup takes.
+        //
+        // It narrows the race; it cannot close it. Comparing and then replacing is
+        // not atomic against an editor that does not participate in any protocol,
+        // and nothing available in userspace makes it so — every tool that edits a
+        // file in place carries this. Passing no digest (a distinct --output) opts
+        // out entirely, which is the safe path when a file is being actively
+        // edited.
+        if (expectedDigest !== undefined) {
+            const current = await fs_1.promises.readFile(target).catch(() => null);
+            const digest = current && (0, crypto_1.createHash)('sha256').update(current).digest('hex');
+            if (digest !== expectedDigest) {
+                await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+                return false;
+            }
+        }
+        await fs_1.promises.rename(temporary, target);
+        await syncDirectory((0, path_1.dirname)(target));
+        return true;
+    }
+    catch (error) {
+        await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * OwnershipError marks a refusal to replace a file whose ownership this
+ * process cannot reproduce, so the caller can explain it rather than print a
+ * bare errno.
+ */
+class OwnershipError extends Error {
+    target;
+    constructor(target) {
+        super(`cannot preserve ownership of ${target}`);
+        this.target = target;
+        this.name = 'OwnershipError';
+    }
+}
+/**
+ * isSameFile reports whether two paths name the same file on disk.
+ *
+ * Compares resolved paths rather than the strings the caller typed, so
+ * `-o ./playlist.json` against `playlist.json`, and a symlink against its
+ * target, are recognized as the in-place case they are.
+ */
+async function isSameFile(a, b) {
+    if (a === b) {
+        return true;
+    }
+    const [left, right] = await Promise.all([
+        fs_1.promises.realpath(a).catch(() => null),
+        fs_1.promises.realpath(b).catch(() => null),
+    ]);
+    return left !== null && left === right;
+}
+/**
+ * syncDirectory flushes a directory entry so a rename survives power loss.
+ *
+ * Best-effort by design. Directory fsync is not portable — Windows rejects it
+ * outright — and a durability barrier that cannot be raised is not a reason to
+ * fail a write that has already succeeded. The data itself was synced before
+ * the rename, so the worst case here is the old name surviving a crash, not a
+ * corrupt file.
+ */
+async function syncDirectory(directory) {
+    try {
+        const handle = await fs_1.promises.open(directory, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        /* not supported on this platform or filesystem */
+    }
+}
+/**
+ * reportInvalid prints structural validation diagnostics and exits non-zero.
+ *
+ * Enrichment refuses to work on a document DP-1 rejects, and refuses to write
+ * one. Writing an invalid playlist would replace the operator's file with
+ * something sign, publish, and play all reject later, having reported success.
+ */
+function reportInvalid(stage, result) {
+    console.error(chalk_1.default.red(`\n${stage}`));
+    if (result.error) {
+        console.error(chalk_1.default.dim(`  ${result.error}`));
+    }
+    for (const detail of result.details ?? []) {
+        console.error(chalk_1.default.dim(`  ${detail.path}: ${detail.message}`));
+    }
+    console.error(chalk_1.default.dim('\n  The file was left unchanged.\n'));
+    process.exit(1);
+}
+/**
+ * SKIP_COPY explains each skip in the operator's terms rather than the code's.
+ * `no-provenance` is the one a person can act on, so it says what to add.
+ */
+const SKIP_COPY = {
+    'already-labelled': 'already has a manifest (use --force to replace)',
+    'external-ref': 'carries an external ref, which outranks an inline manifest',
+    'no-provenance': 'no provenance.contract chain/address/tokenId to look up',
+    'ambiguous-chain': 'chain "evm" names a family; pass --assume-ethereum to assert the network',
+    // The indexer drops unresolved tokens from its response rather than
+    // reporting why, so there is no per-item reason to relay here.
+    'not-indexed': 'the indexer returned nothing for it',
+    'no-metadata': 'the indexer resolved it but has no artist, description, or still image',
+};
+exports.enrichCommand = new commander_1.Command('enrich')
+    .description('Add missing artist, title, and thumbnail metadata to a playlist')
+    .argument('<file>', 'Path to the DP-1 playlist file')
+    .option('-o, --output <filename>', 'Write here instead of overwriting the input')
+    .option('--force', 'Replace manifests that already exist', false)
+    .option('--assume-ethereum', 'Treat DP-1 "evm" coordinates as Ethereum. Without this they are skipped, ' +
+    'because "evm" names a family and the wrong member yields another artwork.', false)
+    .option('-v, --verbose', 'Show detailed output', false)
+    .action(async (file, options) => {
+    try {
+        console.log(chalk_1.default.blue('\nEnrich playlist\n'));
+        // Hash the exact bytes parsed, not a stat taken afterwards: an edit
+        // between the read and the stat would leave the snapshot describing
+        // newer content while enrichment still worked from the older bytes.
+        const original = await fs_1.promises.readFile(file);
+        const originalDigest = (0, crypto_1.createHash)('sha256').update(original).digest('hex');
+        const playlist = JSON.parse(original.toString('utf-8'));
+        const total = Array.isArray(playlist.items) ? playlist.items.length : 0;
+        if (total === 0) {
+            console.error(chalk_1.default.red('That playlist has no items.'));
+            process.exit(1);
+        }
+        // Validate before spending minutes on indexer lookups for a document
+        // that was never going to be writable.
+        const before = await (0, playlist_verifier_1.validatePlaylist)(playlist);
+        if (!before.valid) {
+            reportInvalid('That playlist is not valid DP-1:', before);
+        }
+        // Warming previously-unseen tokens can take minutes, so a human watching
+        // this needs to see it move. Matches the progress line `find` prints.
+        let printedProgress = false;
+        const onProgress = (done, count) => {
+            printedProgress = true;
+            process.stdout.write(chalk_1.default.dim(`\r  ${done}/${count} looked up...`));
+        };
+        // getNFTTokenInfoBatch is (tokens, duration, onProgress) — the second
+        // positional is DP-1 display seconds, not the callback. Enrichment never
+        // sets duration (the curator's timing is not ours to touch), so it is
+        // passed undefined and the callback goes third. find.ts carries the same
+        // warning; getting this wrong silently returns unusable results.
+        const lookup = (tokens, onProgressCallback) => getNFTTokenInfoBatch(tokens, undefined, onProgressCallback);
+        const result = await (0, enrich_playlist_1.enrichPlaylistManifests)(playlist, lookup, {
+            force: options.force,
+            assumeEthereum: options.assumeEthereum,
+            onProgress,
+        });
+        if (printedProgress) {
+            process.stdout.write('\n');
+        }
+        // Said before anything is written, so an operator who did not mean to
+        // assert the network still has the file they started with.
+        if (result.assumedEthereum > 0) {
+            console.log(chalk_1.default.yellow(`\n  ${result.assumedEthereum} coordinate(s) gave chain "evm" and were looked up on` +
+                `\n  Ethereum because --assume-ethereum was passed. An L2 work sharing an` +
+                `\n  address and token id with an Ethereum one would take the wrong metadata.`));
+        }
+        const destination = options.output ?? file;
+        // --output names a file the caller expects to find afterwards, so it is
+        // written even when nothing was enriched. Overwriting the input on a
+        // no-op would be pure risk for no gain, so that case still writes
+        // nothing.
+        const shouldWrite = result.enriched > 0 || options.output !== undefined;
+        if (shouldWrite) {
+            // Re-validate the enriched candidate. An inline manifest is schema-
+            // checked the same way a fetched one is (playlists extension §3.6), so
+            // a malformed manifest from the indexer must not reach the file.
+            const after = await (0, playlist_verifier_1.validatePlaylist)(result.playlist);
+            if (!after.valid) {
+                reportInvalid('Enrichment produced an invalid playlist:', after);
+            }
+            const replaced = await writePlaylistAtomically(destination, JSON.stringify(result.playlist, null, 2), (await isSameFile(file, destination)) ? originalDigest : undefined);
+            if (!replaced) {
+                console.error(chalk_1.default.red('\nThat playlist changed while the lookup ran.'));
+                console.error(chalk_1.default.dim('  Enrichment was computed from the earlier version, so writing it\n' +
+                    '  would discard whatever changed. Nothing was written. Re-run to\n' +
+                    '  enrich the current file, or pass -o to write somewhere else.\n'));
+                process.exit(1);
+            }
+        }
+        console.log(result.enriched > 0
+            ? chalk_1.default.green(`\n${result.enriched} of ${total} item(s) enriched`)
+            : chalk_1.default.yellow('\nNothing to enrich'));
+        if (shouldWrite) {
+            console.log(chalk_1.default.dim(`  Output: ${destination}`));
+        }
+        if (result.skipped.length > 0) {
+            const shown = options.verbose ? result.skipped : result.skipped.slice(0, 10);
+            console.log(chalk_1.default.dim(`\n  Skipped ${result.skipped.length}:`));
+            for (const skip of shown) {
+                console.log(chalk_1.default.dim(`    ${skip.title} — ${SKIP_COPY[skip.reason]}`));
+            }
+            if (shown.length < result.skipped.length) {
+                console.log(chalk_1.default.dim(`    ...and ${result.skipped.length - shown.length} more (-v to list)`));
+            }
+        }
+        // Say this loudly. A signed playlist that silently lost its envelope
+        // fails at the device, which is the worst place to discover it.
+        if (result.signatureInvalidated) {
+            console.log(chalk_1.default.yellow('\n  Signature removed — the document changed.'));
+            console.log(chalk_1.default.dim(`  Re-sign before playing: ff-cli sign ${destination}`));
+        }
+        console.log();
+    }
+    catch (error) {
+        if (error instanceof OwnershipError) {
+            console.error(chalk_1.default.red('\nThat playlist belongs to another user or group.'));
+            console.error(chalk_1.default.dim(`  Replacing it in place would hand it to you and could lock others out,\n` +
+                `  so nothing was written. Write elsewhere instead:\n` +
+                `    ff-cli enrich ${error.target} -o enriched.json\n`));
+            process.exit(1);
+        }
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        if (options.verbose) {
+            console.error(chalk_1.default.dim(error.stack));
+        }
+        process.exit(1);
+    }
+});

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