@heroiclands/package-build 25.6.3 → 25.7.0

package/docs/configuration.md

@@ -974,23 +974,24 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                 | Type     | Default                                      |
-| ------------------- | -------- | -------------------------------------------- |
-| `site.base`         | string   | `""`                                         |
-| `site.title`        | string   | `""`, required when no manifest title exists |
-| `site.assets`       | string   | `""`, but required for `site build`          |
-| `site.description`  | string   | `""`, but required for `site build`          |
-| `site.packages`     | string[] | `[]`                                         |
-| `site.pass`         | string   | `""`                                         |
-| `site.passOptions`  | object   | `{}`                                         |
-| `site.notfound`     | object   | `null`                                       |
-| `site.search`       | boolean  | `true`                                       |
-| `site.maps`         | boolean  | `true`                                       |
-| `site.sections`     | object   | `{}`                                         |
-| `site.feed`         | string   | `""`                                         |
-| `site.tags`         | boolean  | `false`                                      |
-| `site.sitemaps`     | string[] | `[]`, and only at the root of an origin      |
-| `site.mergeIndexes` | string[] | `[]`                                         |
+| Key                 | Type     | Default                                       |
+| ------------------- | -------- | --------------------------------------------- |
+| `site.base`         | string   | `""`                                          |
+| `site.title`        | string   | `""`, required when no manifest title exists  |
+| `site.assets`       | string   | `""`; `site build` derives a CDN when omitted |
+| `site.description`  | string   | `""`, but required for `site build`           |
+| `site.packages`     | string[] | `[]`                                          |
+| `site.pass`         | string   | `""`                                          |
+| `site.passOptions`  | object   | `{}`                                          |
+| `site.notfound`     | object   | `null`                                        |
+| `site.search`       | boolean  | `true`                                        |
+| `site.maps`         | boolean  | `true`                                        |
+| `site.sections`     | object   | `{}`                                          |
+| `site.feed`         | string   | `""`                                          |
+| `site.tags`         | boolean  | `false`                                       |
+| `site.sitemaps`     | string[] | `[]`, and only at the root of an origin       |
+| `site.mergeIndexes` | string[] | `[]`                                          |
+| `site.inputs`       | string   | `""`; optional local input-provider module    |
 
 The authored content tree determines which pages reach the web. `site` is
 framing: which named pass bundle
@@ -1016,7 +1017,7 @@ renders it under the deployment root `build/site/`, at
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, search, maps, sections, feed, tags, sitemaps, mergeIndexes).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, search, maps, sections, feed, tags, sitemaps, mergeIndexes, inputs).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -1029,17 +1030,18 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
-`package-build site build` refuses a configuration with no `site.assets` at
-all — there is no defensible default, because the theme
-resolves every relative asset against it:
+`package-build site build` resolves its effective asset host from `--assets`,
+an explicit `--root`, or configured `site.assets`, in that order. If none is
+provided, it derives `https://cdn.internal.heroiclands.org` from the default
+root. Every relative asset resolves against that effective host.
 
-> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
-
-`package-build cdn publish` uploads the package's pictures under the same
-host, at `<site.assets>/<contentPackage>/icons/<basename>` and
-`…/images/<basename>`, which is the address the website gives each one. The
-bucket behind the CDN is served at `site.assets`, so an object's key is its
-path below this value.
+`package-build cdn publish --dest cloudflare` manually uploads pictures under
+this host, at `<site.assets>/<contentPackage>/icons/<basename>` and
+`…/images/<basename>`. The R2 bucket is served at `site.assets`, so an object's
+key is its path below this value. The default `--dest internal` instead publishes
+the same keys to atlas, served at `https://cdn.internal.heroiclands.org`; its set
+sources use that internal origin regardless of configured `site.assets`.
+Publication is separate from site building and deployment.
 
 The site settings carry the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
@@ -1284,10 +1286,54 @@ site:
   mergeIndexes: [sohl, thalorna, kethira, harnensemble]
 ```
 
-The optional [`site build --base-url` and `--assets` flags](commands.md#package-build-site-build)
-apply runtime overrides to these resolved settings. The base URL supplies the
-effective homepage and `site.base`; the asset URL supplies effective
-`site.assets`. The authored configuration stays unchanged and must be valid.
+[`site build --root <domain>`](commands.md#package-build-site-build) selects
+`https://www.<domain>` while preserving the homepage path. Its default domain
+is `internal.heroiclands.org`. Explicit `--root` replaces configured `site.assets`
+with `https://cdn.<domain>`; without the flag the configured asset host stays,
+or the derived CDN is used if no asset host is configured. Explicit `--base-url`
+and `--assets` independently take precedence over these derived values.
+The effective configuration exposes the chosen address as `homepage`, its path
+as `site.base`, and the asset host as `site.assets`. The authored configuration
+stays unchanged and must be valid. A root-website integration uses these resolved
+inputs rather than deriving hosts itself; canonical source-navigation drift
+checks remain against the original navigation before projecting its URLs.
+`readCachedNavigation(effectiveConfig)` projects only canonical Heroic Lands
+www links onto the effective homepage origin; `siteSettings` does the same for
+the brand license link. Neither function writes the cache or changes external
+attribution links.
+
+### Local site inputs
+
+`site.inputs` optionally names a local module relative to `rootDir`, such as
+`utils/site-inputs.mjs`. Use a plain relative path without dot segments,
+backslashes or symlinks. Its default export is a function taking `{config}`,
+the immutable effective configuration after root and URL overrides. The function
+may return a promise and must return `{navigation, files}`:
+
+```js
+export default async function ({ config }) {
+  const navigation = [{ name: "Home", url: new URL("/", config.homepage).href }];
+  return { navigation, files: { "nav.json": JSON.stringify(navigation) + "\n" } };
+}
+```
+
+The navigation uses the existing `{name, url, children?}` shape. A provider
+supplies selected URLs itself; the example reads the effective homepage instead
+of deriving hosts. A root website can compare its committed canonical navigation
+against its canonical roster before returning selected-origin navigation. A
+thrown drift finding stops the build before output is replaced. Without this
+key the builder continues to require the navigation cache from `deps fetch`.
+
+`files` maps relative output paths to UTF-8 strings. Paths use plain ASCII
+letters, numbers, dots, underscores and hyphens within segments, with each
+segment beginning with a letter or number. Absolute paths, dot segments,
+symlinks, case collisions and file/directory collisions are refused. A provider
+cannot claim HTML, theme/static assets, fonts, search/tag trees, page paths,
+feeds, sitemap files, robots or deployment headers. All files are validated
+before output replacement, then written inside the package site's output after
+the renderer clears it. Their paths are included in `written.files`.
+This prepares build inputs and text artifacts; it is not a shell command or a
+publication hook.
 
 ### What the site build reads
 
@@ -1296,17 +1342,17 @@ repository already states, a few constants of the organisation, and the
 navigation `deps fetch` cached. Every value has one source, and that source is
 where it is edited:
 
-| Setting              | Derived from                                                                                                                                          |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| base URL             | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                   |
-| title                | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                   |
-| `params.description` | `site.description`, which is required                                                                                                                 |
-| `params.author`      | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                              |
-| `params.cdnBaseURL`  | `site.assets`, which is required                                                                                                                      |
-| `params.brand`       | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                     |
-| `params.notfound`    | `site.notfound`; absent when undeclared                                                                                                               |
-| `params.scriptFonts` | the installed script fonts' stylesheet, present only when the package delivers fonts                                                                  |
-| menu                 | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as its `children` |
+| Setting              | Derived from                                                                                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| base URL             | Effective `homepage` from `siteBuildConfig`; authored `package.json` `homepage` first passes `checkHomepage`                                                                                                 |
+| title                | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                                                                          |
+| `params.description` | `site.description`, which is required                                                                                                                                                                        |
+| `params.author`      | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                                                                                     |
+| `params.cdnBaseURL`  | `site.assets`, which is required                                                                                                                                                                             |
+| `params.brand`       | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                                                                            |
+| `params.notfound`    | `site.notfound`; absent when undeclared                                                                                                                                                                      |
+| `params.scriptFonts` | the installed script fonts' stylesheet, present only when the package delivers fonts                                                                                                                         |
+| menu                 | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, with canonical owned URLs projected onto the effective homepage origin, a dropdown's entries as its `children` |
 
 The site build reads the navigation from the cache only. A cold cache is an
 error naming the command that fills it:
@@ -1322,11 +1368,9 @@ the same way when it is absent:
 
 > ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
 
-`params.cdnBaseURL` reads from `site.assets`, and the theme resolves every
-relative asset against it, so a configuration declaring none fails the site
-build the same way:
-
-> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+`params.cdnBaseURL` reads the effective `site.assets` chosen by the build
+resolver, and the theme resolves every relative asset against it. Direct
+`siteSettings` callers must supply that effective asset host.
 
 Nothing else is configurable. A site is its homepage and its pages: the
 homepage is the package root and every note is a page. A tag is a field a

package/docs/guides/release-and-deploy.md

@@ -133,23 +133,34 @@ the other actions and environment variables.
 
 ## Publish pictures to the CDN
 
-The website draws every picture a package has from
-`<site.assets>/<contentPackage>/`, and the art a Foundry package leaves out
-reaches a world from there as a named asset set. `package-build cdn publish`
-is the one command that writes there:
+Run `package-build cdn publish` manually after pictures or their provenance change.
+It uploads every icon and image flat, applies the stage's transformations, skips
+pictures already present at the same size, and writes a named set listing the
+pictures the Foundry package leaves out. Site builds and releases do not publish
+pictures.
+
+The default destination is atlas at `https://cdn.internal.heroiclands.org`:
 
 ```bash
 package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
 package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
 ```
 
-It uploads every icon and image flat, transformed as the stage transforms
-them, skips what the CDN already holds at the same size, and writes
-`<site.assets>/<contentPackage>/alt-art.json` listing the left-out pictures.
-Run it after the pictures or their provenance change; it is not part of a
-build or a release.
+Connect to the LAN or VPN. Install rsync and use your verified `atlas` SSH account
+with write access to `/srv/preview/cdn`. SSH configuration or your SSH agent supplies
+the key; unknown host keys fail. For a configured forced-rrsync publisher alias,
+set `CDN_INTERNAL_DESTINATION=your-alias:cdn`; its relative path is required by the
+restricted receiver. The command does not provision keys or change permissions.
+An internal dry run only reads HTTPS; it never opens SSH or uses R2 credentials.
+
+To publish to the public CDN, select Cloudflare explicitly:
+
+```bash
+package-build cdn publish --dest cloudflare --set alt-art.json --name "Thalorna — illustrated"
+```
 
-The bucket's credentials go in `.env.local` beside the stage paths:
+This retains the existing R2 transport and configured `site.assets` origin,
+normally `https://cdn.heroiclands.org`. The bucket's credentials go in `.env.local`:
 
 ```dotenv
 CDN_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
@@ -158,10 +169,11 @@ CDN_ACCESS_KEY_ID=<access key id>
 CDN_SECRET_ACCESS_KEY=<secret access key>
 ```
 
-A dry run with none of them set compares against the public CDN instead. A
-dispatched workflow passes the same four values as named secrets. See the
-[command reference](../commands.md#package-build-cdn-publish) for the set
-file's shape, the refusals and the exit status.
+With none of those settings present, `--dest cloudflare --dry-run` compares against
+`site.assets` read-only. Both destinations use the same keys and sets; neither
+deletes existing shared CDN objects. See the
+[command reference](../commands.md#package-build-cdn-publish) for SSH setup,
+set shape, refusals and exit status.
 
 ## Publish a package-build npm version
 

package/docs/guides/site.md

@@ -306,14 +306,35 @@ The terminal reports indexing, rendering, writing and search indexing as they
 start, including page counts where available. Progress is on stdout;
 diagnostics retain their file, line and column on stderr.
 
-For an internal main preview, supply the build's address and asset root:
+Build locally for the internal site or a public release with the selected root:
 
 ```bash
-package-build site build \
-    --base-url https://www.internal.heroiclands.org/thalorna/ \
-    --assets https://cdn.internal.heroiclands.org
+package-build site build --root internal.heroiclands.org
+package-build site build --root heroiclands.org
 ```
 
+These select `https://www.internal.heroiclands.org` and
+`https://cdn.internal.heroiclands.org`, or `https://www.heroiclands.org` and
+`https://cdn.heroiclands.org`, retaining the package's path. Without `--root`,
+the site defaults to the internal www origin and keeps configured `site.assets`
+(or derives the internal CDN if none is configured). An explicit root overrides
+the configured asset host. Build and publication are separate: this command
+writes local output, reads cached dependencies, and never uploads or fetches
+missing assets. Shared navigation and the brand license follow the selected
+site origin; external attribution and authored content links retain their URLs.
+Asset references to the exact canonical `https://cdn.heroiclands.org` origin
+also use the effective asset root, retaining their path, query and fragment;
+external image hosts keep their addresses. This happens during normal asset
+resolution and leaves authored files unchanged.
+
+A site that generates its own navigation can declare
+[`site.inputs`](../configuration.md#local-site-inputs). Its local module receives
+the selected addresses in the effective configuration and returns its menu plus
+text files such as `nav.json`. The builder renders that menu and writes those
+files together, so one build command prepares the complete site. A canonical
+roster check belongs in that module before it returns deployment-specific URLs;
+a drift finding leaves the last built site in place.
+
 For a pull request preview, include the whole prefix:
 
 ```bash
@@ -322,10 +343,12 @@ package-build site build \
     --assets https://cdn.internal.heroiclands.org
 ```
 
-The second build writes to `build/site/pr/thalorna/123/thalorna/`. Its local
+This build writes to `build/site/pr/thalorna/123/thalorna/`. Its local
 links, theme files, script fonts and search stay under that prefix; its images
 use the supplied asset root. `--out` changes the deployment directory above the
-prefix. Both URL options are optional and independent, and require absolute
+prefix. Explicit `--base-url` takes precedence over the root-derived site
+address, and explicit `--assets` takes precedence over both the root-derived and
+configured asset host. Both URL options are optional and independent, and require absolute
 HTTP(S) URLs. The base URL's path ends with `/`; the asset root may include a
 path and has trailing slashes trimmed. Use plain paths without percent escapes,
 dot segments (`.` or `..`), or doubled slashes, credentials, queries or fragments.

package/engine/cdn-publish.mjs

@@ -15,14 +15,17 @@
  * `package-build cdn publish` — every picture a package has, on the CDN, and
  * the art the package leaves out as a named asset set.
  *
+ * Internal publication uses the same plan with an atlas rsync writer and public
+ * HTTPS reads. Cloudflare publication keeps the S3-compatible transport.
+ *
  * **The layout is the deployed one.** Each icon and image is uploaded flat, as
- * `icons/<basename>` or `images/<basename>`, under `<site.assets>/<package>/`
- * — the address {@link module:engine/pathnames.resolvePathname} gives the
- * website for the same file, so the site and the CDN agree by construction.
+ * `icons/<basename>` or `images/<basename>`, under the selected CDN's package
+ * root. Cloudflare uses `site.assets`; internal uses `INTERNAL_CDN_HOST`.
+ * Select the same CDN origin for site builds that consume these pictures.
  * Shipped and excluded pictures both go up: the website shows all of them.
  *
- * **The bucket is served at `site.assets`.** An object's key is its path below
- * that URL, `<package>/images/<basename>`, so the key and the public address
+ * **Each destination preserves object keys.** An object's key is its path below
+ * the selected CDN origin, `<package>/images/<basename>`, so the key and the public address
  * differ only by the host.
  *
  * **The bytes are the staged bytes.** The repository's `assetTransform` runs
@@ -56,6 +59,9 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify, stripVTControlCharacters } from "node:util";
 
 import { AwsClient } from "aws4fetch";
 
@@ -278,7 +284,7 @@ export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch:
 export function publicStore(host, fetchImpl) {
     const base = host.replace(/\/+$/, "");
     const get = (key, method) =>
-        (fetchImpl ?? fetch)(`${base}/${key}`, {
+        (fetchImpl ?? fetch)(`${base}/${key.split("/").map(encodeURIComponent).join("/")}`, {
             method,
             headers: method === "HEAD" ? IDENTITY : undefined,
         });
@@ -300,6 +306,156 @@ export function publicStore(host, fetchImpl) {
     };
 }
 
+/** The internal CDN's public origin. Reads never require SSH credentials. */
+export const INTERNAL_CDN_HOST = "https://cdn.internal.heroiclands.org";
+
+/** The manual operator's ordinary SSH account on atlas. */
+export const INTERNAL_CDN_DESTINATION = "atlas:/srv/preview/cdn";
+
+/**
+ * Refuse traversal, absolute paths and control characters before touching a store.
+ *
+ * @param {string} key - A planned relative object key.
+ * @returns {void}
+ */
+function validateCdnKey(key) {
+    if (
+        typeof key !== "string" ||
+        !/^[\x20-\x7e]+$/.test(key) ||
+        key.includes("\\") ||
+        key.split("/").some((part) => !part || part === "." || part === "..")
+    ) {
+        throw new Error("unsafe CDN key: expected a printable relative path without traversal");
+    }
+}
+
+/**
+ * Retain the last actionable receiver diagnostic without commands or key material.
+ *
+ * @param {unknown} stderr - Child-process stderr, never the whole error message.
+ * @returns {string} Bounded, terminal-safe diagnostic text, or an empty string.
+ */
+function transferDiagnostic(stderr) {
+    if (typeof stderr !== "string" && !Buffer.isBuffer(stderr)) return "";
+    const text = stripVTControlCharacters(String(stderr).slice(-8192))
+        .replace(
+            /-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g,
+            "",
+        )
+        .replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
+    let fallback = "";
+    for (const raw of text.split("\n").reverse()) {
+        const line = raw
+            .trim()
+            .replace(/^(?:\/[^\s/]+)*\/(rrsync|rsync|ssh)(?=(?: error)?: )/i, "$1");
+        if (/command failed|command:|\brsync\s+--|\bssh\s+-/i.test(line)) continue;
+        const known = line.match(
+            /Host key verification failed\.|Permission denied(?: \([A-Za-z0-9, -]{1,80}\))?\.?|REMOTE HOST IDENTIFICATION HAS CHANGED|Connection refused|Connection timed out|Could not resolve hostname/i,
+        );
+        if (known) return known[0];
+        if (!/^(?:r?rsync|ssh)(?: error)?: /i.test(line)) continue;
+        const context = line
+            .replace(/(["'])[^"']*\1/g, "[redacted]")
+            .replace(/(?:\/|[A-Za-z]:[\\/])[^\s,;)]+/g, "[path]")
+            .replace(/[A-Za-z0-9+/=]{48,}/g, "[redacted]")
+            .slice(0, 240);
+        if (/^rrsync(?: error)?: /i.test(line)) return context;
+        fallback ||= context;
+    }
+    return fallback;
+}
+
+/**
+ * Report an operation and its structured failure code, excluding error argv/message.
+ *
+ * @param {unknown} error - A filesystem or child-process error.
+ * @param {string} operation - The operation being attempted.
+ * @returns {string} The operator-facing failure.
+ */
+function internalFailure(error, operation) {
+    const details = error && typeof error === "object" ? /** @type {any} */ (error) : {};
+    const code =
+        Number.isInteger(details.code) && details.code >= 0 && details.code <= 255 ?
+            `exit ${details.code}`
+        : typeof details.code === "string" && Object.hasOwn(os.constants.errno, details.code) ?
+            `code ${details.code}`
+        : typeof details.signal === "string" && /^SIG[A-Z0-9]{1,12}$/.test(details.signal) ?
+            `signal ${details.signal}`
+        :   "";
+    const context = operation === "rsync transfer" ? transferDiagnostic(details.stderr) : "";
+    const action =
+        operation === "rsync transfer" ? "rsync transfer failed" : `could not ${operation}`;
+    return `internal CDN ${action}${code ? `; ${code}` : ""}${context ? `: ${context}` : ""}`;
+}
+
+/**
+ * Internal storage: HTTPS reads and rsync writes of the planned bytes only.
+ *
+ * The default uses the operator's normal atlas account. An explicitly configured
+ * SSH alias may select the forced-rrsync account with a relative `cdn` destination.
+ * SSH configuration and its agent supply keys; no remote shell is requested.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.destination] - `host:/srv/preview/cdn` or `alias:cdn`.
+ * @param {typeof fetch} [opts.fetch] - The fetch to use for public reads.
+ * @param {(args: string[]) => Promise<unknown>} [opts.transfer] - Run rsync.
+ * @returns {CdnStore} The store.
+ */
+export function internalStore({
+    destination = INTERNAL_CDN_DESTINATION,
+    fetch: fetchImpl,
+    transfer = (args) => promisify(execFile)("rsync", args),
+} = {}) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*:(?:\/srv\/preview\/)?cdn\/?$/.test(destination)) {
+        throw new Error(
+            "invalid internal CDN destination: use an SSH host alias followed by :/srv/preview/cdn or :cdn",
+        );
+    }
+    const target = `${destination.replace(/\/+$/, "")}/`;
+    const reader = publicStore(INTERNAL_CDN_HOST, fetchImpl);
+    return {
+        ...reader,
+        describe: `${destination} (${INTERNAL_CDN_HOST})`,
+        async write(key, body) {
+            validateCdnKey(key);
+            let scratch;
+            let operation = "create temporary directory";
+            let failure;
+            try {
+                scratch = fs.mkdtempSync(path.join(os.tmpdir(), "package-build-cdn-"));
+                const file = path.join(scratch, ...key.split("/"));
+                operation = "create staged directories";
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                operation = "write staged file";
+                fs.writeFileSync(file, body);
+                operation = "rsync transfer";
+                await transfer([
+                    "--recursive",
+                    "--relative",
+                    "--ignore-times",
+                    "--chmod=D755,F644",
+                    "--omit-dir-times",
+                    "--rsh=ssh -o BatchMode=yes -o StrictHostKeyChecking=yes",
+                    "--",
+                    `${scratch}/./${key}`,
+                    target,
+                ]);
+            } catch (error) {
+                failure = internalFailure(error, operation);
+            } finally {
+                if (scratch) {
+                    try {
+                        fs.rmSync(scratch, { recursive: true, force: true });
+                    } catch (error) {
+                        failure ??= internalFailure(error, "remove temporary directory");
+                    }
+                }
+            }
+            if (failure) throw new Error(failure);
+        },
+    };
+}
+
 /**
  * One picture to publish.
  *
@@ -444,6 +600,8 @@ async function pooled(items, limit, work) {
  *   planned size once the run ends — or would be, in a dry run.
  */
 export async function publishToCdn(plan, { store, dryRun = false, log = () => {} }) {
+    for (const upload of plan.uploads) validateCdnKey(upload.key);
+    validateCdnKey(plan.set?.key);
     if (!dryRun && !store.write) {
         throw new Error(`the store (${store.describe}) is read-only, so it can only be dry-run`);
     }