@moewolf/moe-icons-cli 0.0.1 → 0.0.2

package/dist/core/resource-variant.js

@@ -1,59 +1,100 @@
 /**
- * G0/G1/G2: styleGroupId vs resourceVariantId.
- * Variant ids are deterministic: `<styleGroupId>-<webp|png>-<64|128|256|512>`.
- * Parse from the right: size, then format, remainder is styleGroupId.
+ * MEDIA-FORMAT-V2: styleGroupId vs resourceVariantId.
+ *
+ * Canonical variant ids are the actual source directory names:
+ * `<styleGroupId>-<imageSize>-<format>` (e.g. `example-bitmap-style-256-webp`). Parsing
+ * is controlled keyword-token based, never substring based; `3d` is an ordinary
+ * token. The legacy `<group ending -3d>-<format>-<size>` form is only readable
+ * through the explicit `parseLegacyResourceVariantId` compatibility branch.
  */
-export const BITMAP_STYLE_GROUP_RE = /^moe-[a-z0-9]+(?:-[a-z0-9]+)*-3d$/;
-export const BITMAP_FORMATS = ["webp", "png"];
+export const BITMAP_STYLE_GROUP_RE = /^moe-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const LEGACY_BITMAP_STYLE_GROUP_RE = /^moe-[a-z0-9]+(?:-[a-z0-9]+)*-3d$/;
+export const BITMAP_FORMATS = ["png", "webp"];
 export const BITMAP_SIZES = [64, 128, 256, 512];
 export const DEFAULT_BITMAP_FORMAT = "webp";
 export const DEFAULT_BITMAP_SIZE = 256;
-export function isBitmapStyleGroupId(id) {
-    return BITMAP_STYLE_GROUP_RE.test(id);
-}
 export function isBitmapFormat(value) {
     return BITMAP_FORMATS.includes(value);
 }
 export function isBitmapSize(value) {
     return BITMAP_SIZES.includes(value);
 }
-/** Build a resourceVariantId; never invent aliases. */
+/** Build the canonical v2 resourceVariantId (`<group>-<size>-<format>`). */
 export function buildResourceVariantId(styleGroupId, format = DEFAULT_BITMAP_FORMAT, imageSize = DEFAULT_BITMAP_SIZE) {
-    if (!isBitmapStyleGroupId(styleGroupId)) {
-        throw new Error(`styleGroupId "${styleGroupId}" is not a bitmap style group`);
+    if (!BITMAP_STYLE_GROUP_RE.test(styleGroupId)) {
+        throw new Error(`styleGroupId "${styleGroupId}" is not a valid style group`);
     }
-    return `${styleGroupId}-${format}-${imageSize}`;
+    if (!isBitmapFormat(format))
+        throw new Error(`unsupported bitmap format "${format}"`);
+    if (!isBitmapSize(imageSize))
+        throw new Error(`unsupported bitmap imageSize ${String(imageSize)}`);
+    return `${styleGroupId}-${imageSize}-${format}`;
 }
 /**
- * Parse `<styleGroupId>-<format>-<size>` from the right.
- * Rejects guessing by scanning for an arbitrary `-3d` substring.
+ * Parse a v2 name using complete `-` tokens. Returns undefined when the name is
+ * not a bitmap candidate (no format token); throws on duplicate/conflicting
+ * keywords; returns undefined when the canonical rebuilt id differs (e.g. the
+ * legacy format-before-size order).
  */
+export function parseBitmapName(name) {
+    const tokens = name.split("-");
+    const formatIndexes = [];
+    const sizeIndexes = [];
+    tokens.forEach((token, index) => {
+        if (isBitmapFormat(token))
+            formatIndexes.push(index);
+        if (/^(?:64|128|256|512)$/.test(token))
+            sizeIndexes.push(index);
+    });
+    if (formatIndexes.length === 0)
+        return undefined;
+    if (formatIndexes.length !== 1 || sizeIndexes.length !== 1) {
+        throw new Error(`bitmap name "${name}" must contain exactly one format token and one size token`);
+    }
+    const format = tokens[formatIndexes[0]];
+    const imageSize = Number(tokens[sizeIndexes[0]]);
+    const removed = new Set([formatIndexes[0], sizeIndexes[0]]);
+    const styleGroupId = tokens.filter((_, index) => !removed.has(index)).join("-");
+    if (!BITMAP_STYLE_GROUP_RE.test(styleGroupId)) {
+        throw new Error(`bitmap name "${name}" derives an invalid styleGroupId "${styleGroupId}"`);
+    }
+    const canonical = `${styleGroupId}-${imageSize}-${format}`;
+    if (canonical !== name)
+        return undefined;
+    return { styleGroupId, format, imageSize, resourceVariantId: canonical };
+}
+/** Parse a canonical v2 resourceVariantId or throw. */
 export function parseResourceVariantId(resourceVariantId) {
-    const parts = resourceVariantId.split("-");
-    if (parts.length < 4) {
+    const parsed = parseBitmapName(resourceVariantId);
+    if (!parsed)
         throw new Error(`invalid resourceVariantId "${resourceVariantId}"`);
-    }
-    const sizeToken = parts[parts.length - 1] ?? "";
-    const formatToken = parts[parts.length - 2] ?? "";
-    const imageSize = Number(sizeToken);
-    if (!isBitmapSize(imageSize)) {
+    return parsed;
+}
+/**
+ * Explicit v1 compatibility branch: legacy ids are
+ * `<styleGroupId ending -3d>-<format>-<size>`. Never guessed by the v2 parser.
+ */
+export function parseLegacyResourceVariantId(resourceVariantId) {
+    const parts = resourceVariantId.split("-");
+    if (parts.length < 4)
+        throw new Error(`invalid legacy resourceVariantId "${resourceVariantId}"`);
+    const imageSize = Number(parts[parts.length - 1]);
+    const format = parts[parts.length - 2] ?? "";
+    const styleGroupId = parts.slice(0, -2).join("-");
+    if (!isBitmapSize(imageSize))
         throw new Error(`invalid imageSize in resourceVariantId "${resourceVariantId}"`);
-    }
-    if (!isBitmapFormat(formatToken)) {
+    if (!isBitmapFormat(format))
         throw new Error(`invalid format in resourceVariantId "${resourceVariantId}"`);
+    if (!LEGACY_BITMAP_STYLE_GROUP_RE.test(styleGroupId)) {
+        throw new Error(`invalid legacy styleGroupId derived from "${resourceVariantId}"`);
     }
-    const styleGroupId = parts.slice(0, -2).join("-");
-    if (!isBitmapStyleGroupId(styleGroupId)) {
-        throw new Error(`invalid styleGroupId derived from "${resourceVariantId}"`);
-    }
-    return {
-        styleGroupId,
-        format: formatToken,
-        imageSize,
-        resourceVariantId: buildResourceVariantId(styleGroupId, formatToken, imageSize),
-    };
+    return { styleGroupId, format, imageSize, resourceVariantId };
 }
-/** Resolve format/size for a bitmap theme, applying catalog defaults when omitted. */
+/**
+ * Build a canonical variant from a group id and optional format/size, applying
+ * the schema defaults `webp`/`256`. Availability must still be checked against
+ * the catalog by the caller (MEDIA-FORMAT-V2 D-05/B6).
+ */
 export function resolveResourceVariant(styleGroupId, options = {}) {
     const format = options.format === undefined ? DEFAULT_BITMAP_FORMAT : options.format;
     const imageSize = options.imageSize === undefined ? DEFAULT_BITMAP_SIZE : options.imageSize;

package/dist/core/selected-resources.d.ts

@@ -0,0 +1,59 @@
+import { type CacheIo } from "./cache.js";
+import { type IconCatalog } from "../catalog/catalog.js";
+import type { MoeiconsConfigFile } from "../project/config.js";
+export interface ResourceRef {
+    readonly filename: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface ResourceRefs {
+    readonly schemaVersion: 1;
+    readonly index: ResourceRef;
+    readonly bundle: ResourceRef;
+}
+export interface ResourceFile {
+    readonly offset: number;
+    readonly compressedSize: number;
+    readonly compressedSha256: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly requires: readonly string[];
+}
+export interface ResourceIndex {
+    readonly schemaVersion: 1;
+    readonly version: string;
+    readonly tier: "free" | "pro";
+    readonly artifactSha256: string;
+    readonly bundle: ResourceRef;
+    readonly files: Readonly<Record<string, ResourceFile>>;
+}
+export declare function parseResourceRefs(value: unknown): ResourceRefs;
+export declare function parseResourceIndex(bytes: Uint8Array, refs: ResourceRefs, expected: {
+    version: string;
+    tier: "free" | "pro";
+    artifactSha256: string;
+}): ResourceIndex;
+export declare const EMPTY_DOWNLOAD_SELECTION_MESSAGE = "config.icons must contain at least one icon ID before install/update; edit icons in moeicons.config.json or run moeicons init";
+export declare function assertDownloadSelection(config: MoeiconsConfigFile): void;
+export declare function planSelectedResources(config: MoeiconsConfigFile, catalog: IconCatalog, index: ResourceIndex): {
+    paths: readonly string[];
+    payloadBytes: number;
+    expandedBytes: number;
+    fallbacks: readonly string[];
+};
+export declare function verifyResource(bytes: Uint8Array, entry: ResourceFile, name: string): Uint8Array;
+export declare function downloadSelectedResources(index: ResourceIndex, indexSha256: string, paths: readonly string[], deps: {
+    io: CacheIo;
+    cacheDir: string;
+    fetch: typeof fetch;
+    signal: AbortSignal;
+    allowedHosts: readonly string[];
+    allowLoopback?: boolean;
+    offline?: boolean;
+    getBundleUrl: () => Promise<string>;
+    readRange?: (start: number, size: number) => Promise<Uint8Array>;
+}): Promise<{
+    files: Record<string, Uint8Array>;
+    networkBytes: number;
+    cacheHits: number;
+}>;

package/dist/core/selected-resources.js

@@ -0,0 +1,350 @@
+import { gunzipSync } from "node:zlib";
+import { join } from "node:path";
+import { sha256Bytes } from "../project/install-metadata.js";
+import { CliError } from "../errors/index.js";
+import { cacheArtifact } from "./cache.js";
+import { resolveIconTheme } from "./icon-selection.js";
+import { findCatalogStyleGroup } from "../catalog/catalog.js";
+import { toProxyName } from "./icon-names.js";
+import { resolveResourceVariant } from "./resource-variant.js";
+const SHA = /^[a-f0-9]{64}$/;
+const safe = (path) => /^(react|vue|vanilla|assets)\/[A-Za-z0-9_./-]+$/.test(path) &&
+    path.split("/").every((part) => part && part !== "." && part !== "..");
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fail = (message) => {
+    throw new CliError("VALIDATION_ERROR", message);
+};
+export function parseResourceRefs(value) {
+    if (!record(value) ||
+        value.schemaVersion !== 1 ||
+        Object.keys(value).some((k) => !["schemaVersion", "index", "bundle"].includes(k)))
+        return fail("invalid selected resource contract");
+    for (const kind of ["index", "bundle"]) {
+        const ref = value[kind];
+        if (!record(ref) ||
+            Object.keys(ref).some((k) => !["filename", "size", "sha256"].includes(k)) ||
+            typeof ref.filename !== "string" ||
+            !/^[A-Za-z0-9._-]+$/.test(ref.filename) ||
+            typeof ref.size !== "number" ||
+            !Number.isSafeInteger(ref.size) ||
+            ref.size < 1 ||
+            typeof ref.sha256 !== "string" ||
+            !SHA.test(ref.sha256))
+            return fail(`invalid resources.${kind}`);
+    }
+    if (value.index.size > 8 * 1024 * 1024)
+        return fail("resource index exceeds 8 MiB compressed limit");
+    return value;
+}
+export function parseResourceIndex(bytes, refs, expected) {
+    if (bytes.length !== refs.index.size || sha256Bytes(bytes) !== refs.index.sha256)
+        return fail("resource index length/SHA-256 mismatch");
+    let raw;
+    try {
+        raw = JSON.parse(gunzipSync(bytes, { maxOutputLength: 64 * 1024 * 1024 }).toString("utf8"));
+    }
+    catch {
+        return fail("invalid or oversized compressed resource index");
+    }
+    if (!record(raw) ||
+        Object.keys(raw).some((k) => !["schemaVersion", "version", "tier", "artifactSha256", "bundle", "files"].includes(k)) ||
+        raw.schemaVersion !== 1 ||
+        raw.version !== expected.version ||
+        raw.tier !== expected.tier ||
+        raw.artifactSha256 !== expected.artifactSha256 ||
+        !record(raw.bundle) ||
+        Object.keys(raw.bundle).some((k) => !["filename", "size", "sha256"].includes(k)) ||
+        raw.bundle.filename !== refs.bundle.filename ||
+        raw.bundle.sha256 !== refs.bundle.sha256 ||
+        raw.bundle.size !== refs.bundle.size ||
+        !record(raw.files))
+        return fail("resource index release identity mismatch");
+    if (Object.keys(raw.files).length > 250000)
+        return fail("too many indexed resources");
+    const folded = new Set();
+    const intervals = [];
+    for (const [name, value] of Object.entries(raw.files)) {
+        if (!safe(name) || folded.has(name.toLowerCase()) || !record(value))
+            return fail(`unsafe/duplicate indexed path: ${name}`);
+        folded.add(name.toLowerCase());
+        if (Object.keys(value).some((k) => !["offset", "compressedSize", "compressedSha256", "size", "sha256", "requires"].includes(k)) ||
+            ![value.offset, value.compressedSize, value.size].every((n) => typeof n === "number" && Number.isSafeInteger(n)) ||
+            value.offset < 0 ||
+            value.compressedSize < 1 ||
+            value.size < 0 ||
+            value.size > 32 * 1024 * 1024 ||
+            typeof value.sha256 !== "string" ||
+            !SHA.test(value.sha256) ||
+            typeof value.compressedSha256 !== "string" ||
+            !SHA.test(value.compressedSha256) ||
+            !Array.isArray(value.requires) ||
+            value.requires.length > 10000 ||
+            value.requires.some((d) => typeof d !== "string" ||
+                !safe(d) ||
+                d.split("/")[0] !== name.split("/")[0] ||
+                !Object.hasOwn(raw.files, d)))
+            return fail(`invalid indexed resource: ${name}`);
+        const end = value.offset + value.compressedSize;
+        if (!Number.isSafeInteger(end) || end > refs.bundle.size)
+            return fail(`resource range escapes bundle: ${name}`);
+        intervals.push([value.offset, end]);
+    }
+    for (const name of folded) {
+        const parts = name.split("/");
+        for (let i = 1; i < parts.length; i++)
+            if (folded.has(parts.slice(0, i).join("/")))
+                return fail(`indexed file/directory collision: ${name}`);
+    }
+    intervals.sort((a, b) => a[0] - b[0]);
+    if (intervals[0]?.[0] !== 0 ||
+        intervals.at(-1)?.[1] !== refs.bundle.size ||
+        intervals.some((interval, i) => i > 0 && interval[0] !== intervals[i - 1][1]))
+        return fail("resource ranges overlap or leave unindexed bytes");
+    return raw;
+}
+export const EMPTY_DOWNLOAD_SELECTION_MESSAGE = "config.icons must contain at least one icon ID before install/update; edit icons in moeicons.config.json or run moeicons init";
+export function assertDownloadSelection(config) {
+    if (config.icons.length === 0)
+        throw new CliError("VALIDATION_ERROR", EMPTY_DOWNLOAD_SELECTION_MESSAGE);
+}
+export function planSelectedResources(config, catalog, index) {
+    assertDownloadSelection(config);
+    if (config.tier !== index.tier)
+        return fail(`config.tier=${config.tier} does not match resource tier=${index.tier}`);
+    const chosen = new Set();
+    const fallbacks = new Set();
+    const visit = (name) => {
+        const pending = [name];
+        while (pending.length) {
+            const path = pending.pop();
+            if (chosen.has(path))
+                continue;
+            const entry = index.files[path];
+            if (!entry)
+                return fail(`configured resource is missing from this release: ${path}; check icons/themes/target or choose another fixed release`);
+            chosen.add(path);
+            if (chosen.size > 20000)
+                return fail("selected resources exceed 20,000 files; reduce icons/themes or explicitly use downloadMode=full");
+            pending.push(...entry.requires);
+        }
+    };
+    if (config.target !== "assets")
+        visit(`${config.target}/types.d.ts`);
+    let assets = config.target === "assets" || config.target === "vanilla";
+    for (const id of config.icons)
+        for (const requested of Object.keys(config.themes)) {
+            const actual = resolveIconTheme(config, catalog, requested, id);
+            if (!actual)
+                return fail(`icons[${id}]: no selected variant for themes.${requested}; register/select a variant or change missingIconPolicy`);
+            if (actual !== requested)
+                fallbacks.add(`${id}: ${requested} -> ${actual}`);
+            const theme = config.themes[actual];
+            const group = findCatalogStyleGroup(theme.styleGroup, catalog);
+            if (group.type === "bitmap") {
+                if (config.target === "vanilla")
+                    return fail(`themes.${actual}: Vanilla does not support bitmap icons; choose assets/react/vue`);
+                const variant = resolveResourceVariant(group.id, {
+                    ...(theme.format ? { format: theme.format } : {}),
+                    ...(theme.imageSize ? { imageSize: theme.imageSize } : {}),
+                });
+                visit(`assets/${variant.resourceVariantId}/${id}.${variant.format}`);
+                assets = true;
+            }
+            else if (config.target === "assets") {
+                visit(`assets/${group.id}/${id}.svg`);
+                assets = true;
+            }
+            else {
+                const base = `${config.target}/${group.id}/${toProxyName(id)}${config.target === "vue" ? ".vue" : ""}`;
+                visit(`${base}.js`);
+                visit(`${base}.d.ts`);
+                if (config.target === "vanilla") {
+                    visit(`assets/${group.id}/${id}.svg`);
+                    assets = true;
+                }
+            }
+        }
+    if (assets)
+        visit("assets/manifest.json");
+    const paths = [...chosen].sort();
+    const payloadBytes = paths.reduce((sum, p) => sum + index.files[p].compressedSize, 0);
+    const expandedBytes = paths.reduce((sum, p) => sum + index.files[p].size, 0);
+    if (paths.length > 20000 || expandedBytes > 512 * 1024 * 1024 || payloadBytes > 512 * 1024 * 1024)
+        return fail("selected resources exceed 20,000 files/512 MiB budget; reduce icons/themes or explicitly use downloadMode=full");
+    return { paths, payloadBytes, expandedBytes, fallbacks: [...fallbacks].sort() };
+}
+export function verifyResource(bytes, entry, name) {
+    if (bytes.length !== entry.compressedSize || sha256Bytes(bytes) !== entry.compressedSha256)
+        return fail(`compressed resource length/SHA-256 mismatch: ${name}`);
+    let expanded;
+    try {
+        expanded = gunzipSync(bytes, { maxOutputLength: Math.max(1, entry.size) });
+    }
+    catch {
+        return fail(`invalid compressed resource: ${name}`);
+    }
+    if (expanded.length !== entry.size || sha256Bytes(expanded) !== entry.sha256)
+        return fail(`resource length/SHA-256 mismatch: ${name}`);
+    return expanded;
+}
+export async function downloadSelectedResources(index, indexSha256, paths, deps) {
+    const files = {};
+    let networkBytes = 0;
+    let cacheHits = 0;
+    let cursor = 0;
+    let urlPromise;
+    let failure;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    deps.signal.addEventListener("abort", abort, { once: true });
+    if (deps.signal.aborted)
+        controller.abort();
+    const getUrl = () => (urlPromise ??= deps.getBundleUrl());
+    try {
+        await Promise.all(Array.from({ length: Math.min(4, paths.length) }, async () => {
+            while (cursor < paths.length && !failure) {
+                const name = paths[cursor++];
+                const entry = index.files[name];
+                const cached = join(deps.cacheDir, "resources", index.tier, index.version, indexSha256, entry.compressedSha256);
+                try {
+                    if (controller.signal.aborted)
+                        throw new CliError("CANCELLED", "selected resource download cancelled");
+                    if (deps.io.existsSync(cached) && deps.io.readFileSync) {
+                        try {
+                            files[name] = verifyResource(deps.io.readFileSync(cached), entry, name);
+                            cacheHits++;
+                            continue;
+                        }
+                        catch {
+                            /* corrupt cache is never used */
+                        }
+                    }
+                    if (deps.offline)
+                        throw new CliError("NETWORK_ERROR", `offline resource is missing or corrupt: ${name}; reconnect and run moeicons install, then retry offline`);
+                    let bytes;
+                    for (let attempt = 0; attempt < 3; attempt++) {
+                        if (controller.signal.aborted)
+                            throw new CliError("CANCELLED", "selected resource download cancelled");
+                        try {
+                            if (deps.readRange)
+                                bytes = await deps.readRange(entry.offset, entry.compressedSize);
+                            else {
+                                let url = new URL(await getUrl());
+                                let response;
+                                const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(30000)]);
+                                for (let redirects = 0; redirects <= 5; redirects++) {
+                                    const loopback = deps.allowLoopback &&
+                                        url.protocol === "http:" &&
+                                        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+                                    if ((url.protocol !== "https:" && !loopback) ||
+                                        url.username ||
+                                        url.password ||
+                                        !deps.allowedHosts.includes(url.host))
+                                        return fail("resource URL uses an untrusted host or protocol");
+                                    response = await deps.fetch(url, {
+                                        headers: {
+                                            Range: `bytes=${entry.offset}-${entry.offset + entry.compressedSize - 1}`,
+                                            "Accept-Encoding": "identity",
+                                        },
+                                        redirect: "manual",
+                                        signal,
+                                    });
+                                    if ([301, 302, 303, 307, 308].includes(response.status)) {
+                                        const location = response.headers.get("location");
+                                        await response.body?.cancel();
+                                        if (!location || redirects === 5)
+                                            return fail("resource redirect limit exceeded");
+                                        url = new URL(location, url);
+                                        continue;
+                                    }
+                                    break;
+                                }
+                                if (!response)
+                                    throw new Error("resource response unavailable");
+                                if ([401, 403].includes(response.status)) {
+                                    await response.body?.cancel();
+                                    if (attempt === 2)
+                                        throw new CliError("AUTH_ERROR", "resource URL expired or access revoked; retry moeicons install/login");
+                                    urlPromise = undefined;
+                                    continue;
+                                }
+                                if ([429, 500, 502, 503, 504].includes(response.status)) {
+                                    await response.body?.cancel();
+                                    throw new Error(`resource service returned ${response.status}`);
+                                }
+                                if (response.status !== 206 ||
+                                    response.headers.get("content-range") !==
+                                        `bytes ${entry.offset}-${entry.offset + entry.compressedSize - 1}/${index.bundle.size}` ||
+                                    (response.headers.get("content-encoding") &&
+                                        response.headers.get("content-encoding") !== "identity")) {
+                                    await response.body?.cancel();
+                                    return fail(`server did not honor the exact resource Range for ${name}; retry or explicitly set downloadMode=full`);
+                                }
+                                const length = response.headers.get("content-length");
+                                if (length && Number(length) !== entry.compressedSize) {
+                                    await response.body?.cancel();
+                                    return fail(`resource response length mismatch: ${name}`);
+                                }
+                                const reader = response.body?.getReader();
+                                if (!reader)
+                                    return fail("resource response has no body");
+                                const chunks = [];
+                                let lengthRead = 0;
+                                try {
+                                    for (;;) {
+                                        const part = await reader.read();
+                                        if (part.done)
+                                            break;
+                                        lengthRead += part.value.length;
+                                        if (lengthRead > entry.compressedSize) {
+                                            await reader.cancel();
+                                            return fail(`oversized resource response: ${name}`);
+                                        }
+                                        chunks.push(part.value);
+                                    }
+                                }
+                                finally {
+                                    reader.releaseLock();
+                                }
+                                bytes = Buffer.concat(chunks);
+                                networkBytes += lengthRead;
+                            }
+                            break;
+                        }
+                        catch (error) {
+                            if (error instanceof CliError || attempt === 2 || controller.signal.aborted)
+                                throw error;
+                            await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+                        }
+                    }
+                    if (!bytes)
+                        throw new CliError("NETWORK_ERROR", `resource download failed: ${name}`);
+                    files[name] = verifyResource(bytes, entry, name);
+                    cacheArtifact(deps.io, cached, bytes, entry.compressedSha256);
+                }
+                catch (error) {
+                    const code = typeof error === "object" && error !== null && "code" in error
+                        ? error.code
+                        : undefined;
+                    failure ??=
+                        error instanceof CliError
+                            ? error
+                            : code === "ENOSPC" || code === "EDQUOT"
+                                ? new CliError("DISK_FULL", `not enough disk space for verified resource cache: ${name}; free space and retry; project files were not changed`)
+                                : controller.signal.aborted
+                                    ? new CliError("CANCELLED", "selected resource download cancelled")
+                                    : code === "EACCES" || code === "EROFS" || code === "EISDIR"
+                                        ? new CliError("UNEXPECTED", `resource cache is not writable: ${name}; check MOEICONS_CACHE_DIR permissions`)
+                                        : new CliError("NETWORK_ERROR", `resource request failed after retries: ${name}; retry the same release; no full archive was downloaded`);
+                    controller.abort();
+                }
+            }
+        }));
+        if (failure)
+            throw failure;
+        return { files, networkBytes, cacheHits };
+    }
+    finally {
+        deps.signal.removeEventListener("abort", abort);
+    }
+}

package/dist/core/signed-artifact.d.ts

@@ -4,9 +4,15 @@ export interface SignedArtifactDescriptor {
     readonly size: number;
     readonly sha256: string;
 }
+export declare function parseSignedDescriptor(value: unknown, now: number, options?: {
+    readonly allowLoopback?: boolean;
+}): SignedArtifactDescriptor;
 /**
  * Exchange an access token for a descriptor. The caller supplies only the
- * frozen API path; credentials can never be sent to another origin.
+ * frozen API path; credentials can never be sent to another origin. The
+ * descriptor request uses `redirect: "error"` — an API endpoint must never
+ * bounce us to an untrusted host mid-handshake (unlike the large signed-artifact
+ * download below, which follows a bounded number of CDN redirects).
  */
 export declare function fetchSignedArtifactDescriptor(apiPath: string, accessToken: string, deps?: {
     readonly fetch?: typeof fetch;
@@ -22,6 +28,7 @@ export declare function downloadSignedArtifact(descriptor: SignedArtifactDescrip
     readonly timeoutMs?: number;
     readonly maxRedirects?: number;
     readonly now?: number;
+    readonly allowLoopback?: boolean;
     readonly onProgress?: (event: {
         readonly downloadedBytes: number;
         readonly totalBytes?: number;

package/dist/core/signed-artifact.js

@@ -2,14 +2,21 @@ import { CliError } from "../errors/index.js";
 import { downloadArtifact, verifyArtifact } from "../project/install.js";
 const API_ORIGIN = "https://api.moeicons.com";
 const SHA256 = /^[a-f0-9]{64}$/;
-function parseDescriptor(value, now) {
+function isLoopback(hostname) {
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+}
+export function parseSignedDescriptor(value, now, options = {}) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         throw new CliError("VALIDATION_ERROR", "invalid signed artifact descriptor");
     const item = value;
     if (Object.keys(item).some((key) => !["url", "expiresAt", "size", "sha256"].includes(key)) ||
-        typeof item.url !== "string" || typeof item.expiresAt !== "string" ||
-        typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 1 ||
-        typeof item.sha256 !== "string" || !SHA256.test(item.sha256)) {
+        typeof item.url !== "string" ||
+        typeof item.expiresAt !== "string" ||
+        typeof item.size !== "number" ||
+        !Number.isSafeInteger(item.size) ||
+        item.size < 1 ||
+        typeof item.sha256 !== "string" ||
+        !SHA256.test(item.sha256)) {
         throw new CliError("VALIDATION_ERROR", "invalid signed artifact descriptor");
     }
     let url;
@@ -20,13 +27,18 @@ function parseDescriptor(value, now) {
         throw new CliError("VALIDATION_ERROR", "invalid signed artifact URL");
     }
     const expires = Date.parse(item.expiresAt);
-    if (url.protocol !== "https:" || !Number.isFinite(expires) || expires <= now)
+    const loopbackHttp = options.allowLoopback === true && url.protocol === "http:" && isLoopback(url.hostname);
+    if ((url.protocol !== "https:" && !loopbackHttp) || !Number.isFinite(expires) || expires <= now) {
         throw new CliError("VALIDATION_ERROR", "signed artifact descriptor is expired or insecure");
+    }
     return item;
 }
 /**
  * Exchange an access token for a descriptor. The caller supplies only the
- * frozen API path; credentials can never be sent to another origin.
+ * frozen API path; credentials can never be sent to another origin. The
+ * descriptor request uses `redirect: "error"` — an API endpoint must never
+ * bounce us to an untrusted host mid-handshake (unlike the large signed-artifact
+ * download below, which follows a bounded number of CDN redirects).
  */
 export async function fetchSignedArtifactDescriptor(apiPath, accessToken, deps = {}) {
     const url = new URL(apiPath, API_ORIGIN);
@@ -40,12 +52,18 @@ export async function fetchSignedArtifactDescriptor(apiPath, accessToken, deps =
     deps.signal?.addEventListener("abort", abort, { once: true });
     try {
         const response = await (deps.fetch ?? fetch)(url, {
-            method: "GET", redirect: "error", signal: controller.signal,
+            method: "GET",
+            redirect: "error",
+            signal: controller.signal,
             headers: { accept: "application/json", authorization: `Bearer ${accessToken}` },
         });
         if (!response.ok)
-            throw new CliError(response.status === 401 ? "AUTH_ERROR" : response.status === 403 ? "FORBIDDEN" : "NETWORK_ERROR", `pro descriptor request failed with ${response.status}`);
-        return parseDescriptor(await response.json(), deps.now ?? Date.now());
+            throw new CliError(response.status === 401
+                ? "AUTH_ERROR"
+                : response.status === 403
+                    ? "FORBIDDEN"
+                    : "NETWORK_ERROR", `pro descriptor request failed with ${response.status}`);
+        return parseSignedDescriptor(await response.json(), deps.now ?? Date.now());
     }
     catch (error) {
         if (error instanceof CliError)
@@ -59,17 +77,23 @@ export async function fetchSignedArtifactDescriptor(apiPath, accessToken, deps =
 }
 /** Download signed bytes without forwarding API credentials or cookies. */
 export async function downloadSignedArtifact(descriptor, options) {
-    const checked = parseDescriptor(descriptor, options.now ?? Date.now());
+    if (options.signal?.aborted)
+        throw new CliError("CANCELLED", "signed resource download cancelled");
+    const checked = parseSignedDescriptor(descriptor, options.now ?? Date.now(), options);
     const result = await downloadArtifact(checked.url, {
         maxBytes: checked.size,
-        timeoutMs: options.timeoutMs ?? 30_000,
+        timeoutMs: options.timeoutMs ??
+            Math.min(600_000, Math.max(30_000, Math.ceil(checked.size / (128 * 1024)) * 1_000 + 15_000)),
         maxRedirects: options.maxRedirects ?? 5,
         allowedHosts: options.allowedHosts,
+        ...(options.allowLoopback ? { allowHttpLoopback: true } : {}),
         ...(options.onProgress ? { onProgress: options.onProgress } : {}),
     }, {
         ...(options.fetch ? { fetchFn: options.fetch } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
     });
+    if (options.signal?.aborted)
+        throw new CliError("CANCELLED", "signed resource download cancelled");
     if (!result.ok)
         throw new CliError(result.code === "NETWORK_ERROR" ? "NETWORK_ERROR" : "VALIDATION_ERROR", result.message);
     if (result.bytes.byteLength !== checked.size)