@feralfile/cli 2.7.0 → 2.8.0

package/dist/src/utilities/feed-mutation.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * Shared machinery for the feed's two owner-bound mutations: `PUT` (replace) and `DELETE`.
+ *
+ * The feed has no API key. Every mutating request is authorized by signatures the body carries, and for
+ * replace and delete those signatures must come from a key the *stored* resource already names as an
+ * owner (dp1-feed-v2 `docs/api_design.md`, "Authentication and authorization"). A create signs the
+ * document itself; a replace and a delete additionally sign a short-lived **intent** envelope, because an
+ * owner's document signatures are public via `GET` and could otherwise be replayed — the per-signature
+ * `ts` is not covered by the signature, so only a `created` inside a signed payload can bound replay.
+ *
+ * Both intents therefore share the same shape and the same failure modes, which is why they live here
+ * rather than in the publisher and unpublisher separately: the envelope, the freshness rule, the
+ * ownership rule and the error vocabulary are one contract with two verbs.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OWNER_ROLE = void 0;
+exports.intentTimestamp = intentTimestamp;
+exports.buildDeleteIntent = buildDeleteIntent;
+exports.buildReplaceIntent = buildReplaceIntent;
+exports.documentPayloadHash = documentPayloadHash;
+exports.signIntent = signIntent;
+exports.resolvePlaylistIdentifier = resolvePlaylistIdentifier;
+exports.fetchStoredPlaylist = fetchStoredPlaylist;
+exports.storedOwnerKeys = storedOwnerKeys;
+exports.storedOwnership = storedOwnership;
+exports.ownershipPreflight = ownershipPreflight;
+exports.describeFeedMutationError = describeFeedMutationError;
+exports.asPlaylist = asPlaylist;
+const axios_1 = __importDefault(require("axios"));
+// playlist-signer is still CommonJS; require keeps the interop simple.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { normalizeSigningKeyToBase64Pkcs8 } = require('./playlist-signer');
+/**
+ * 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).
+ * Intents are always signed in this role: only an owner signature authorizes a replace or a delete, so
+ * signing an intent under any other role produces a body the feed answers with `403`.
+ */
+exports.OWNER_ROLE = 'curator';
+/**
+ * Whole-second RFC 3339 timestamp for an intent's `created`.
+ *
+ * The feed compares this against its own clock and rejects anything outside `auth.intent_max_clock_skew`
+ * (default 5 minutes) with `400 invalid_timestamp`. Milliseconds are stripped to match the form the
+ * playlist signer already emits, so both timestamps in a request read alike.
+ */
+function intentTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Build the DELETE body's unsigned half.
+ *
+ * `id` and `slug` must match the stored row exactly — the feed compares both and answers `400
+ * bad_request` on any disagreement — which is why callers read them from a `GET` rather than from
+ * whatever the user typed.
+ */
+function buildDeleteIntent(id, slug, created) {
+    return { action: 'delete', target: { type: 'playlist', id, slug }, created };
+}
+/**
+ * Build the `authorization` half of a PUT body.
+ *
+ * `payloadHash` binds the intent to the exact document being installed, so a captured intent cannot be
+ * replayed to install different bytes. It is the DP-1 signing digest of the accompanying document.
+ */
+function buildReplaceIntent(id, slug, payloadHash, created) {
+    return { action: 'replace', target: { type: 'playlist', id, slug }, payloadHash, created };
+}
+/**
+ * DP-1 signing digest of a document, in the `sha256:<hex>` form the feed's `payloadHash` expects.
+ *
+ * dp1-js strips `signature`/`signatures` and JCS-canonicalizes internally, so the full signed document
+ * is passed through unchanged; computing it any other way risks diverging from the digest the document's
+ * own signatures were taken over.
+ */
+async function documentPayloadHash(document) {
+    const dp1 = await import('dp1-js');
+    return dp1.PayloadHashString(Buffer.from(JSON.stringify(document)));
+}
+/**
+ * Sign an intent with the playlist signing key, in the owner role.
+ *
+ * The signature covers the intent bytes with `signatures` stripped and JCS-canonicalized — the same
+ * payload rule DP-1 uses for documents — so the unsigned intent object is passed here as-is and the
+ * caller attaches the result afterwards. `ts` is set to the intent's own `created` so the two timestamps
+ * a reviewer sees in a request body agree.
+ */
+async function signIntent(intent, privateKeyMaterial) {
+    const dp1 = await import('dp1-js');
+    const normalizedKey = normalizeSigningKeyToBase64Pkcs8(privateKeyMaterial);
+    return (await dp1.SignMultiEd25519(Buffer.from(JSON.stringify(intent)), normalizedKey, exports.OWNER_ROLE, intent.created));
+}
+/**
+ * Reduce user input to the path segment the feed resolves.
+ *
+ * Operators copy playlist URLs out of a browser far more often than they copy bare UUIDs, and the feed's
+ * `{id}` parameter accepts either an id or a slug. Anything that parses as an HTTP(S) URL contributes
+ * its last non-empty path segment; everything else is passed through trimmed.
+ */
+function resolvePlaylistIdentifier(input) {
+    const trimmed = input.trim();
+    if (!/^https?:\/\//i.test(trimmed)) {
+        return trimmed;
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+    const segments = parsed.pathname.split('/').filter((segment) => segment.length > 0);
+    return segments.length > 0 ? decodeURIComponent(segments[segments.length - 1]) : trimmed;
+}
+/**
+ * Fetch the stored playlist a mutation will target.
+ *
+ * Both mutations need the stored copy before they can be built at all: the delete intent must name the
+ * stored `slug`, and a replace must prove its identity fields still equal the stored ones. Reading the
+ * owners from here rather than from the local file is the point — a local document can claim any
+ * `curators[]`, but only the stored set decides who may write.
+ */
+async function fetchStoredPlaylist(feedServerUrl, identifier) {
+    const response = await axios_1.default.get(`${feedServerUrl}/playlists/${encodeURIComponent(identifier)}`, {
+        headers: { Accept: 'application/json' },
+        timeout: 30000,
+    });
+    const stored = response.data;
+    if (!stored || typeof stored !== 'object') {
+        throw new Error('Feed returned no playlist document');
+    }
+    return stored;
+}
+/** Owner `did:key`s the stored playlist declares, in declaration order. */
+function storedOwnerKeys(stored) {
+    const curators = Array.isArray(stored.curators) ? stored.curators : [];
+    return curators
+        .map((curator) => (typeof curator?.key === 'string' ? curator.key.trim() : ''))
+        .filter((key) => key.length > 0);
+}
+/**
+ * Resolve who can actually authorize a mutation on a stored playlist.
+ *
+ * Each candidate signature is verified individually rather than through a whole-envelope check: a stored
+ * document legitimately carries entries this CLI does not depend on — the feed's own `feed` signature,
+ * and any co-curator's — and one unverifiable stranger among them must not invalidate a proof that is
+ * itself sound. Verification is over the stored bytes with `signatures` stripped and JCS-canonicalized,
+ * so re-serializing the parsed document here is safe: canonicalization removes key-order and whitespace
+ * differences before the digest is taken.
+ *
+ * @param stored - The playlist as the feed serves it
+ * @returns Declared and proven owner keys
+ */
+async function storedOwnership(stored) {
+    const declared = storedOwnerKeys(stored);
+    const signatures = Array.isArray(stored.signatures)
+        ? (stored.signatures ?? []).filter(Boolean)
+        : [];
+    if (declared.length === 0 || signatures.length === 0) {
+        return { declared, proven: [] };
+    }
+    const dp1 = await import('dp1-js');
+    const raw = Buffer.from(JSON.stringify(stored));
+    const proven = [];
+    for (const signature of signatures) {
+        const kid = typeof signature?.kid === 'string' ? signature.kid.trim() : '';
+        if (signature?.role !== exports.OWNER_ROLE || !declared.includes(kid) || proven.includes(kid)) {
+            continue;
+        }
+        try {
+            dp1.VerifyMultiSignature(raw, signature);
+            proven.push(kid);
+        }
+        catch {
+            // An entry that does not verify is not proof. It is also not this command's business to report:
+            // a stale or tampered signature on someone else's key changes nothing about whether the
+            // configured key can act, and the answer below is derived from the set that survived.
+        }
+    }
+    return { declared, proven };
+}
+/**
+ * Refuse locally when the configured key cannot authorize a mutation on the stored playlist.
+ *
+ * The feed's own answer to every case here is a bare `403 forbidden`, which says nothing about which
+ * identity was offered, which ones would have worked, or whether the problem is the declaration or the
+ * proof. Separating them costs no request beyond the `GET` the mutation already had to make, and the
+ * three answers point in genuinely different directions: switch keys, nothing can ever work, or the
+ * declaration is right and the signature that would back it was never made.
+ *
+ * @param stored - The playlist as the feed serves it
+ * @param signerDidKey - `did:key` the configured signing key will assert
+ * @param action - Which mutation is being authorized, for the wording
+ * @returns A failure to report, or `null` when the configured key is a proven owner.
+ */
+async function ownershipPreflight(stored, signerDidKey, action) {
+    const { declared, proven } = await storedOwnership(stored);
+    if (proven.includes(signerDidKey)) {
+        return null;
+    }
+    const verb = action === 'delete' ? 'delete' : 'replace';
+    // A playlist with no declared curators is not "owned by someone else" — it is owned by nobody, and
+    // nothing can ever authorize a write to it. Telling that operator to switch keys sends them looking
+    // for one that does not exist; this is the state a playlist published without any curator declaration
+    // is frozen in, and it is exactly what the publish-time curator check now prevents.
+    if (declared.length === 0) {
+        return {
+            error: `This playlist declares no owners, so no key can ${verb} it.`,
+            message: `The feed derives ownership from the stored document's curators[], and this one is empty — the\n` +
+                `  shape a playlist published without an owner-role signature is frozen in. No signature can\n` +
+                `  authorize a ${verb}, including yours (${signerDidKey}).\n` +
+                `  Nothing can repair it: the owner set is immutable, and only an owner could change it. Publish\n` +
+                `  a corrected playlist under a new id instead.`,
+        };
+    }
+    // Declared, but nobody proved it. Same terminal outcome as the case above, different cause and
+    // therefore a different message: curators[] is correct and the owner-role signature that would back
+    // it was never made. This is the state of everything published from 2.5.0 with the default `agent`
+    // role, so it is the case an operator is most likely to meet on an older playlist.
+    if (proven.length === 0) {
+        return {
+            error: `No key has proved ownership of this playlist, so none can ${verb} it.`,
+            message: `A key counts as an owner only when it is named in curators[] AND signed the document as\n` +
+                `  "${exports.OWNER_ROLE}". This playlist names ${declared.length === 1 ? 'a curator' : `${declared.length} curators`} and carries no valid ${exports.OWNER_ROLE} signature\n` +
+                `  from ${declared.length === 1 ? 'that key' : 'any of them'} — the shape of a playlist published while the default signing role was\n` +
+                `  "agent".\n` +
+                `  Declared:\n` +
+                `${declared.map((key) => `    ${key}`).join('\n')}\n` +
+                `  Nothing can repair it, including holding one of those keys: adding the missing signature\n` +
+                `  would be a replace, and a replace needs the very proof that is missing. Publish a corrected\n` +
+                `  playlist under a new id instead.`,
+        };
+    }
+    // Declared, and someone proved it — but not this key. Distinct from the case above: an owner exists,
+    // it is simply not the one configured here.
+    if (declared.includes(signerDidKey)) {
+        return {
+            error: `Your key is declared on this playlist but never signed it as ${exports.OWNER_ROLE}, so it cannot ${verb} it.`,
+            message: `The feed treats a declared key as an owner only once it has also signed the stored document\n` +
+                `  as "${exports.OWNER_ROLE}". Yours is named in curators[] but carries no such signature, so an intent\n` +
+                `  signed with it would be refused.\n` +
+                `  Your configured identity:\n` +
+                `    ${signerDidKey}\n` +
+                `  Keys that have proved ownership:\n` +
+                `${proven.map((key) => `    ${key}`).join('\n')}\n` +
+                `  Point playlist.privateKey at one of those (confirm any key's identity with\n` +
+                `  "ff-cli status --key <private key>"). Your own declaration cannot be upgraded after the fact:\n` +
+                `  the proof would have to be a signature over the document as published.`,
+        };
+    }
+    return {
+        error: `The configured signing key is not an owner of this playlist, so it cannot ${verb} it.`,
+        message: `Only a key the stored playlist names in curators[] AND that signed it as "${exports.OWNER_ROLE}" can\n` +
+            `  authorize a ${verb}; the feed derives ownership from the stored document, not from a local copy.\n` +
+            `  Your configured identity:\n` +
+            `    ${signerDidKey}\n` +
+            `  Keys that have proved ownership:\n` +
+            `${proven.map((key) => `    ${key}`).join('\n')}\n` +
+            `  Point playlist.privateKey at a key listed above (confirm any key's identity with\n` +
+            `  "ff-cli status --key <private key>"). Ownership cannot be granted after the fact: the owner set\n` +
+            `  is immutable, so a playlist signed by the wrong key stays that way.`,
+    };
+}
+/** Feed error code carried in an error response body, when there is one. */
+function feedErrorCode(error) {
+    const data = error.response?.data;
+    const code = data?.error ?? data?.code;
+    return typeof code === 'string' ? code : '';
+}
+/** Human-readable detail the feed supplied, if any. */
+function feedErrorDetail(error) {
+    const data = error.response?.data;
+    if (typeof data?.message === 'string' && data.message.trim().length > 0) {
+        return data.message.trim();
+    }
+    return '';
+}
+/**
+ * Translate a feed mutation failure into the CLI's diagnosis-plus-remedy shape.
+ *
+ * The feed's status codes each mean something specific for an owner-bound write, and the raw JSON body
+ * does not say which of them the operator hit — `400` alone covers both a stale intent and a target
+ * mismatch. Mapping them here keeps `unpublish` and `publish --replace` answering in the same
+ * vocabulary, and keeps that vocabulary next to the contract it mirrors.
+ *
+ * The codes handled are exactly those dp1-feed-v2 documents for these routes; anything else falls
+ * through with the server's own words rather than being guessed at.
+ */
+function describeFeedMutationError(error, action) {
+    const axiosError = error;
+    const status = axiosError.response?.status;
+    const code = feedErrorCode(axiosError);
+    const detail = feedErrorDetail(axiosError);
+    const verb = action === 'delete' ? 'Delete' : 'Replace';
+    const suffix = detail ? `\n  Feed said: ${detail}` : '';
+    if (status === undefined) {
+        return { error: `${verb} failed: ${axiosError.message}` };
+    }
+    if (status === 401) {
+        return {
+            error: `${verb} refused: the feed saw no signatures on the request.`,
+            message: `Every mutating request is authorized by the signatures in its body — there is no API key.\n` +
+                `  This usually means no signing key is configured: run "ff-cli status" to check, and\n` +
+                `  "ff-cli setup" to generate one.${suffix}`,
+        };
+    }
+    // A 403 that reaches here has already passed the local ownership proof: the configured key was found
+    // in the stored curators[] with a valid curator-role signature over the stored bytes. Repeating "your
+    // key is not declared" would therefore be a lie, and it is the wrong place to send someone — the
+    // remaining causes are the feed disagreeing about the stored document, or a replace touching the
+    // owner set. Say that the feed refused, and that the local check disagreed.
+    if (status === 403) {
+        return {
+            error: `${verb} refused by the feed: it did not accept the signing key as an owner.`,
+            message: `The local check disagreed — the configured key is named in the stored playlist's curators[]\n` +
+                `  and carries a valid "${exports.OWNER_ROLE}" signature over the stored document — so this is the feed's\n` +
+                `  own judgement, not a missing declaration.\n` +
+                (action === 'replace'
+                    ? `  For a replace the usual cause is the submitted document changing the owner set: curators[]\n` +
+                        `  is immutable, and altering it is refused as a forbidden write rather than as a bad field.\n`
+                    : '') +
+                `  Otherwise the stored document changed since it was read; run the command again, and report it\n` +
+                `  if it persists.${suffix}`,
+        };
+    }
+    if (status === 400 && code === 'invalid_timestamp') {
+        return {
+            error: `${verb} refused: the signed intent was outside the feed's freshness window.`,
+            message: `An intent is valid for about five minutes, and the window is wall-clock, so a machine whose\n` +
+                `  clock has drifted fails every attempt. Check the system clock, then run the command again — a\n` +
+                `  new intent is signed each time.${suffix}`,
+        };
+    }
+    if (status === 400) {
+        return {
+            error: `${verb} refused: the request did not match the stored playlist.`,
+            message: action === 'delete'
+                ? `  The delete intent must name the stored id and slug exactly. They are read from the feed\n` +
+                    `  immediately before the request, so this means the playlist changed in between: run the\n` +
+                    `  command again.${suffix}`
+                : `  A replace may not change identity: id, slug, and created must equal the stored document's,\n` +
+                    `  and every signature must verify. Re-read the stored copy and re-sign from it.${suffix}`,
+        };
+    }
+    if (status === 404) {
+        return {
+            error: `${verb} refused: the feed has no such playlist.`,
+            message: `Either the id or slug is wrong for this feed, or the playlist was already deleted. Deleted ids\n` +
+                `  are tombstoned and never reused, so a deleted playlist cannot be restored under the same id.${suffix}`,
+        };
+    }
+    if (status === 409) {
+        return {
+            error: `${verb} refused: the playlist changed between authorization and the write.`,
+            message: `Another write landed first. Re-read the playlist and run the command again.${suffix}`,
+        };
+    }
+    const body = axiosError.response?.data
+        ? JSON.stringify(axiosError.response.data)
+        : axiosError.message;
+    return { error: `${verb} failed with status ${status}: ${body}` };
+}
+/** Narrow a stored playlist to a `Playlist` for the shared verification paths. */
+function asPlaylist(stored) {
+    return stored;
+}