@cardinali-studio/adminkit 2.2.37 → 2.2.38

package/README.md

@@ -196,6 +196,14 @@ It is opinionated about the useful narrow case: Hugo content, React 19, Zod 4, C
 
 This narrowness is intentional. A smaller system with explicit failure modes is easier to trust around content that people have edited by hand.
 
+## Delivery ZIP compatibility (2.2.38)
+
+New delivery archives use STORE members with their CRC and sizes in each local header, without data descriptors. This prevents streaming extractors from mistaking descriptor-shaped bytes inside a photograph for the end of the file. CRC preparation reads bounded 4 MiB slices and remains pausable and cancellable; source changes fail closed. ZIP64 sizes and offsets are promoted independently.
+
+Persistent checkpoints record `store-header-v1`. Checkpoints from earlier releases continue with `store-descriptor-v1`, preserving confirmed multipart bytes and derivative retries. The update affects newly generated archives; it does not rewrite existing stored ZIPs. Consumers must update the dependency, rebuild and redeploy.
+
+The regression includes 208 synthetic members with the collision at member 53, streaming and indexed readers, ZIP64 offsets, and byte-identical resume against fixtures from 2.2.37.
+
 ## Development
 
 ```sh

package/dist/app/lib/delivery-upload.d.ts

@@ -1,5 +1,8 @@
 import { type UploadControl } from "./delivery-network.js";
 export { UploadCancelled, type UploadControl } from "./delivery-network.js";
+declare const ZIP_FORMAT = "store-header-v1";
+declare const LEGACY_ZIP_FORMAT = "store-descriptor-v1";
+type ZipFormat = typeof ZIP_FORMAT | typeof LEGACY_ZIP_FORMAT;
 export interface DeliveryUploadProgress {
     phase: "originals" | "derivatives" | "finalizing";
     file: string;
@@ -57,6 +60,8 @@ interface MemberCheckpoint {
     dataOffset: number;
     time: number;
     date: number;
+    zipFormat?: ZipFormat;
+    headerCrc?: number;
 }
 export declare function uploadDeliveryPackage(deliveryId: string, packageId: string, selected: File[], options: UploadOptions, onProgress: (progress: DeliveryUploadProgress) => void, control?: UploadControl): Promise<UploadResult>;
 interface ZipSink {
@@ -69,9 +74,10 @@ export declare class ZipStream {
     private sink;
     private offset;
     private entries;
-    constructor(sink: ZipSink, utc?: boolean);
+    private format;
+    constructor(sink: ZipSink, utc?: boolean, format?: ZipFormat);
     restore(entries: DeliveryManifestEntry[], files: File[], offset: number): void;
-    add(nameValue: string, blob: Blob, progress?: (read: number) => void, modified?: Date, checkpoint?: (current: MemberCheckpoint, offset: number) => Promise<void>, resume?: MemberCheckpoint): Promise<ZipMember>;
+    add(nameValue: string, blob: Blob, progress?: (read: number, preparing?: boolean) => void, modified?: Date, checkpoint?: (current: MemberCheckpoint, offset: number) => Promise<void>, resume?: MemberCheckpoint): Promise<ZipMember>;
     close(): Promise<void>;
     private sinkGate;
     private push;

package/dist/app/lib/delivery-upload.js

@@ -14,6 +14,8 @@ const READ = 4 * 1024 * 1024;
 const UPLOAD_CONCURRENCY = 4;
 const IMAGE = /\.(jpe?g|png|webp)$/i;
 const enc = new TextEncoder();
+const ZIP_FORMAT = "store-header-v1";
+const LEGACY_ZIP_FORMAT = "store-descriptor-v1";
 const droppedPaths = new WeakMap();
 /* Il cancello di pausa e annullamento.
  *
@@ -154,7 +156,9 @@ async function buildDeliveryPackage(deliveryId, packageId, selected, options, on
     let currentOriginal = "";
     const originalsSink = new B2Sink(deliveryId, packageId, "originals", reportOriginals, control, options.manifestVersion === 2);
     sinks.push(originalsSink);
-    const originals = new ZipStream(originalsSink, options.manifestVersion === 2);
+    // Confirmed multipart prefixes and derivative retries keep their original layout.
+    const zipFormat = checkpoint ? (checkpoint.current?.zipFormat || LEGACY_ZIP_FORMAT) : ZIP_FORMAT;
+    const originals = new ZipStream(originalsSink, options.manifestVersion === 2, zipFormat);
     if (checkpoint) {
         if (checkpoint.complete) {
             originalsSink.totalBytes = checkpoint.offset;
@@ -175,12 +179,13 @@ async function buildDeliveryPackage(deliveryId, packageId, selected, options, on
             checkpoint: { version: 1, fileIndex: processed, offset, sequence, current } }, control);
         lastCheckpoint = offset;
     }
-    function reportOriginals() {
+    function reportOriginals(_read, preparing = false) {
         onProgress({
             phase: "originals", file: currentOriginal, doneFiles: processed, totalFiles: files.length,
             sourceBytes, uploadedBytes: originalsSink.uploadedBytes,
             transferredBytes: originalsSink.transferredBytes, startedAt,
             transferStartedAt: originalsSink.transferStartedAt || undefined,
+            note: preparing ? "Verifico il file prima del caricamento…" : undefined,
         });
     }
     for (const file of files.slice(processed)) {
@@ -188,7 +193,7 @@ async function buildDeliveryPackage(deliveryId, packageId, selected, options, on
             await control.gate();
         const name = safePath(deliveryRelativeName(file));
         currentOriginal = name;
-        const member = await originals.add(name, file, reportOriginals, new Date(file.lastModified), options.manifestVersion === 2 ? saveCheckpoint : undefined, checkpoint && processed === checkpoint.fileIndex ? checkpoint.current : undefined);
+        const member = await originals.add(name, file, reportOriginals, new Date(file.lastModified), options.manifestVersion === 2 ? saveCheckpoint : undefined, checkpoint && !checkpoint.complete && processed === checkpoint.fileIndex ? checkpoint.current : undefined);
         entryByName.set(name, entries.length);
         entries.push({ name, type: file.type || mimeFromName(name), original: member });
         await saveMetadata(entries.length - 1, entries[entries.length - 1]);
@@ -200,7 +205,7 @@ async function buildDeliveryPackage(deliveryId, packageId, selected, options, on
     await flushMetadata();
     if (options.manifestVersion === 2 && !checkpoint?.complete) {
         await deliveryJson("/admin/api/deliveries", { action: "manifestCheckpoint", id: deliveryId, packageId,
-            checkpoint: { version: 1, fileIndex: files.length, offset: originalsSink.totalBytes, sequence, complete: true } }, control);
+            checkpoint: { version: 1, fileIndex: files.length, offset: originalsSink.totalBytes, sequence, complete: true, current: { zipFormat } } }, control);
     }
     phase = "variants";
     sequence = 0;
@@ -213,12 +218,12 @@ async function buildDeliveryPackage(deliveryId, packageId, selected, options, on
     if (wantWebArchive) {
         webSink = new B2Sink(deliveryId, packageId, "web", undefined, control, options.manifestVersion === 2);
         sinks.push(webSink);
-        webZip = new ZipStream(webSink, options.manifestVersion === 2);
+        webZip = new ZipStream(webSink, options.manifestVersion === 2, zipFormat);
     }
     if (options.galleryEnabled) {
         thumbsSink = new B2Sink(deliveryId, packageId, "thumbs", undefined, control, options.manifestVersion === 2);
         sinks.push(thumbsSink);
-        thumbsZip = new ZipStream(thumbsSink, options.manifestVersion === 2);
+        thumbsZip = new ZipStream(thumbsSink, options.manifestVersion === 2, zipFormat);
     }
     if (webZip) {
         let imageDone = 0;
@@ -494,9 +499,13 @@ export class ZipStream {
     sink;
     offset = 0;
     entries = [];
-    constructor(sink, utc = false) {
+    format;
+    constructor(sink, utc = false, format = ZIP_FORMAT) {
+        if (![ZIP_FORMAT, LEGACY_ZIP_FORMAT].includes(format))
+            throw new Error("Formato del checkpoint ZIP non supportato.");
         this.utc = utc;
         this.sink = sink;
+        this.format = format;
     }
     restore(entries, files, offset) {
         this.offset = offset;
@@ -509,22 +518,46 @@ export class ZipStream {
         });
     }
     async add(nameValue, blob, progress, modified = new Date(), checkpoint, resume) {
+        await this.sinkGate();
         const name = enc.encode(safePath(nameValue));
         const size = blob.size;
         const localOffset = resume?.localOffset ?? this.offset;
         const zip64 = size >= 0xffffffff;
+        const legacy = this.format === LEGACY_ZIP_FORMAT;
+        if (resume && (resume.zipFormat || LEGACY_ZIP_FORMAT) !== this.format)
+            throw new Error("Formato del checkpoint ZIP diverso dal caricamento.");
+        // STORE has a known size, but needs a CRC before its local header can
+        // be self-contained. Two bounded reads avoid buffering whole photos.
+        let headerCrc = 0;
+        if (!legacy) {
+            let value = 0xffffffff;
+            progress?.(0, true);
+            for (let offset = 0; offset < size; offset += READ) {
+                await this.sinkGate();
+                const length = Math.min(READ, size - offset);
+                const chunk = new Uint8Array(await blob.slice(offset, offset + length).arrayBuffer());
+                if (chunk.length !== length)
+                    throw new Error("Lettura sorgente incompleta durante la verifica.");
+                value = crc32Update(value, chunk);
+                progress?.(offset + length, true);
+            }
+            headerCrc = (value ^ 0xffffffff) >>> 0;
+            if (resume && resume.headerCrc !== headerCrc)
+                throw new Error("Il file è cambiato: il checksum non corrisponde al checkpoint.");
+        }
         const extra = zip64 ? zip64Extra([size, size]) : new Uint8Array();
         const local = bytes(30 + name.length + extra.length);
         const v = view(local);
         v.setUint32(0, 0x04034b50, true);
         v.setUint16(4, zip64 ? 45 : 20, true);
-        v.setUint16(6, 0x0808, true); // descriptor + nomi UTF-8
+        v.setUint16(6, legacy ? 0x0808 : 0x0800, true); // UTF-8; descriptor only for legacy checkpoints
         v.setUint16(8, 0, true); // STORE
         const [time, date] = dosDate(modified, this.utc);
         v.setUint16(10, time, true);
         v.setUint16(12, date, true);
-        v.setUint32(18, zip64 ? 0xffffffff : 0, true);
-        v.setUint32(22, zip64 ? 0xffffffff : 0, true);
+        v.setUint32(14, legacy ? 0 : headerCrc, true);
+        v.setUint32(18, zip64 ? 0xffffffff : legacy ? 0 : size, true);
+        v.setUint32(22, zip64 ? 0xffffffff : legacy ? 0 : size, true);
         v.setUint16(26, name.length, true);
         v.setUint16(28, extra.length, true);
         local.set(name, 30);
@@ -564,46 +597,56 @@ export class ZipStream {
             read += chunk.byteLength;
             await this.push(chunk);
             if (checkpoint && this.offset % PART === 0)
-                await checkpoint({ name: nameValue, size, read, crc, chain, localOffset, dataOffset, time, date }, this.offset);
+                await checkpoint({ name: nameValue, size, read, crc, chain, localOffset, dataOffset, time, date,
+                    zipFormat: this.format, ...(!legacy ? { headerCrc } : {}) }, this.offset);
             progress?.(read);
         }
         crc = (crc ^ 0xffffffff) >>> 0;
-        const descriptor = bytes(zip64 ? 24 : 16);
-        const d = view(descriptor);
-        d.setUint32(0, 0x08074b50, true);
-        d.setUint32(4, crc, true);
-        if (zip64) {
-            setU64(d, 8, size);
-            setU64(d, 16, size);
-        }
-        else {
-            d.setUint32(8, size, true);
-            d.setUint32(12, size, true);
+        if (!legacy && crc !== headerCrc)
+            throw new Error("Il file è cambiato durante il caricamento. Riseleziona i file e riprova.");
+        if (legacy) {
+            const descriptor = bytes(zip64 ? 24 : 16);
+            const d = view(descriptor);
+            d.setUint32(0, 0x08074b50, true);
+            d.setUint32(4, crc, true);
+            if (zip64) {
+                setU64(d, 8, size);
+                setU64(d, 16, size);
+            }
+            else {
+                d.setUint32(8, size, true);
+                d.setUint32(12, size, true);
+            }
+            await this.push(descriptor);
         }
-        await this.push(descriptor);
         this.entries.push({ name, size, crc, localOffset, time, date });
         return { offset: dataOffset, length: size, crc32: crc };
     }
     async close() {
         const centralOffset = this.offset;
         for (const entry of this.entries) {
-            const large = entry.size >= 0xffffffff || entry.localOffset >= 0xffffffff;
-            const extra = large ? zip64Extra([entry.size, entry.size, entry.localOffset]) : new Uint8Array();
+            const legacy = this.format === LEGACY_ZIP_FORMAT;
+            const largeSize = entry.size >= 0xffffffff;
+            const largeOffset = entry.localOffset >= 0xffffffff;
+            const large = largeSize || largeOffset;
+            const values = legacy && large ? [entry.size, entry.size, entry.localOffset]
+                : [...(largeSize ? [entry.size, entry.size] : []), ...(largeOffset ? [entry.localOffset] : [])];
+            const extra = values.length ? zip64Extra(values) : new Uint8Array();
             const central = bytes(46 + entry.name.length + extra.length);
             const v = view(central);
             v.setUint32(0, 0x02014b50, true);
             v.setUint16(4, 45, true);
             v.setUint16(6, large ? 45 : 20, true);
-            v.setUint16(8, 0x0808, true);
+            v.setUint16(8, legacy ? 0x0808 : 0x0800, true);
             v.setUint16(10, 0, true);
             v.setUint16(12, entry.time, true);
             v.setUint16(14, entry.date, true);
             v.setUint32(16, entry.crc, true);
-            v.setUint32(20, large ? 0xffffffff : entry.size, true);
-            v.setUint32(24, large ? 0xffffffff : entry.size, true);
+            v.setUint32(20, largeSize || (legacy && large) ? 0xffffffff : entry.size, true);
+            v.setUint32(24, largeSize || (legacy && large) ? 0xffffffff : entry.size, true);
             v.setUint16(28, entry.name.length, true);
             v.setUint16(30, extra.length, true);
-            v.setUint32(42, large ? 0xffffffff : entry.localOffset, true);
+            v.setUint32(42, largeOffset || (legacy && large) ? 0xffffffff : entry.localOffset, true);
             central.set(entry.name, 46);
             central.set(extra, 46 + entry.name.length);
             await this.push(central);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardinali-studio/adminkit",
-  "version": "2.2.37",
+  "version": "2.2.38",
   "type": "module",
   "description": "Motore riusabile di un pannello di amministrazione per siti Hugo su Cloudflare Pages: codec del front matter guidato dallo schema, form React, libreria media su R2. NIENTE di specifico di un sito qui dentro.",
   "license": "0BSD",
@@ -104,6 +104,7 @@
     "react-dom": "^19.2.8",
     "react-hook-form": "^7.85.0",
     "typescript": "^5.9.3",
+    "unzipper": "0.12.5",
     "wrangler": "4.114.0",
     "zod": "^4.4.3"
   },