@particle/tachyon-image 0.1.0

package/dist/slots/index.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Qualcomm UEFI A/B slot selection via GPT partition-entry attribute bits.
+ * Canonical home (shared by particle-cli and the on-device OTA service).
+ *
+ *   bits 48-49  PRIORITY     (higher preferred; 0 = not selected by priority)
+ *   bit  50     ACTIVE       (slot the loader currently selects)
+ *   bits 51-53  RETRY/tries  (decremented per boot; 0 + !success => give up)
+ *   bit  54     SUCCESS      (booted OK; commit)
+ *   bit  55     UNBOOTABLE   (never select)
+ *
+ * NOTE: confirm exact positions vs the BP QcomPkg/.../PartitionTableUpdate.h
+ * before trusting on hardware — wrong bits brick slot selection. These match
+ * the standard Qualcomm boot_control layout. Pure BigInt helpers: unit-testable
+ * with no device.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RETRY = exports.MAX_PRIORITY = exports.UNBOOTABLE_BIT = exports.SUCCESS_BIT = exports.RETRY_MASK = exports.RETRY_SHIFT = exports.ACTIVE_BIT = exports.PRIORITY_MASK = exports.PRIORITY_SHIFT = void 0;
+exports.getSlotState = getSlotState;
+exports.makeActivePending = makeActivePending;
+exports.makeInactiveFallback = makeInactiveFallback;
+exports.markSuccessful = markSuccessful;
+exports.markUnbootable = markUnbootable;
+exports.activeSlot = activeSlot;
+exports.planSlotSwitch = planSlotSwitch;
+exports.PRIORITY_SHIFT = 48n;
+exports.PRIORITY_MASK = 0x3n;
+exports.ACTIVE_BIT = 50n;
+exports.RETRY_SHIFT = 51n;
+exports.RETRY_MASK = 0x7n;
+exports.SUCCESS_BIT = 54n;
+exports.UNBOOTABLE_BIT = 55n;
+exports.MAX_PRIORITY = 3;
+exports.MAX_RETRY = 7;
+const bit = (attr, n) => (attr >> n) & 1n;
+const setBit = (attr, n, v) => (v ? attr | (1n << n) : attr & ~(1n << n));
+const getField = (attr, shift, mask) => Number((attr >> shift) & mask);
+const setField = (attr, shift, mask, value) => (attr & ~(mask << shift)) | ((BigInt(value) & mask) << shift);
+function getSlotState(attr) {
+    const a = BigInt(attr);
+    return {
+        priority: getField(a, exports.PRIORITY_SHIFT, exports.PRIORITY_MASK),
+        active: bit(a, exports.ACTIVE_BIT) === 1n,
+        retries: getField(a, exports.RETRY_SHIFT, exports.RETRY_MASK),
+        success: bit(a, exports.SUCCESS_BIT) === 1n,
+        unbootable: bit(a, exports.UNBOOTABLE_BIT) === 1n,
+    };
+}
+function makeActivePending(attr, opts = {}) {
+    let a = BigInt(attr);
+    a = setField(a, exports.PRIORITY_SHIFT, exports.PRIORITY_MASK, opts.priority ?? exports.MAX_PRIORITY);
+    a = setField(a, exports.RETRY_SHIFT, exports.RETRY_MASK, opts.retries ?? exports.MAX_RETRY);
+    a = setBit(a, exports.ACTIVE_BIT, true);
+    a = setBit(a, exports.SUCCESS_BIT, false);
+    a = setBit(a, exports.UNBOOTABLE_BIT, false);
+    return a;
+}
+function makeInactiveFallback(attr, opts = {}) {
+    let a = BigInt(attr);
+    a = setField(a, exports.PRIORITY_SHIFT, exports.PRIORITY_MASK, opts.priority ?? exports.MAX_PRIORITY - 1);
+    a = setBit(a, exports.ACTIVE_BIT, false);
+    return a;
+}
+function markSuccessful(attr, opts = {}) {
+    let a = BigInt(attr);
+    a = setBit(a, exports.SUCCESS_BIT, true);
+    a = setBit(a, exports.UNBOOTABLE_BIT, false);
+    a = setField(a, exports.RETRY_SHIFT, exports.RETRY_MASK, opts.retries ?? exports.MAX_RETRY);
+    return a;
+}
+function markUnbootable(attr) {
+    let a = BigInt(attr);
+    a = setBit(a, exports.UNBOOTABLE_BIT, true);
+    a = setBit(a, exports.ACTIVE_BIT, false);
+    a = setField(a, exports.PRIORITY_SHIFT, exports.PRIORITY_MASK, 0);
+    return a;
+}
+function activeSlot(attrA, attrB) {
+    const a = getSlotState(attrA);
+    const b = getSlotState(attrB);
+    if (a.active && !b.active)
+        return 'a';
+    if (b.active && !a.active)
+        return 'b';
+    const aBootable = !a.unbootable && a.priority > 0;
+    const bBootable = !b.unbootable && b.priority > 0;
+    if (aBootable && (!bBootable || a.priority >= b.priority))
+        return 'a';
+    if (bBootable)
+        return 'b';
+    return 'a';
+}
+function planSlotSwitch(slotParts, target) {
+    if (target !== 'a' && target !== 'b') {
+        throw new Error(`slot target must be 'a' or 'b' (got '${target}')`);
+    }
+    const sys = slotParts.filter((p) => /^system_[ab]$/.test(p.label));
+    const ref = sys.length ? sys : slotParts;
+    const a = ref.find((p) => p.slot === 'a');
+    const b = ref.find((p) => p.slot === 'b');
+    const current = activeSlot(a ? a.attr : 0n, b ? b.attr : 0n);
+    const changes = [];
+    for (const p of slotParts) {
+        const fromAttr = BigInt(p.attr);
+        const toAttr = p.slot === target ? makeActivePending(fromAttr) : makeInactiveFallback(fromAttr);
+        if (toAttr !== fromAttr) {
+            changes.push({ label: p.label, lun: p.lun, slot: p.slot, fromAttr, toAttr });
+        }
+    }
+    return { current, target, changes };
+}

package/dist/sparse/decode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Android sparse image decoder. Yields an ordered op stream so a writer can
+ * stream straight to a block device (seek past holes) and a hasher can count
+ * holes as zeros — without ever materializing the whole expanded image.
+ *
+ * Reference (not a dependency): AOSP libsparse sparse_format.h.
+ */
+export declare const SPARSE_MAGIC = 3978755898;
+export type SparseOp = {
+    kind: 'data';
+    data: Buffer;
+} | {
+    kind: 'skip';
+    length: number;
+};
+export interface SparseHeader {
+    blockSize: number;
+    totalBlocks: number;
+    totalChunks: number;
+}
+export declare function isSparse(buf: Buffer): boolean;
+export declare function readSparseHeader(buf: Buffer): SparseHeader;
+/**
+ * Decode a sparse image buffer into an ordered op stream.
+ * FILL is expanded into data (the fill word repeated); DONT_CARE becomes skip.
+ */
+export declare function decodeSparse(buf: Buffer): Generator<SparseOp, void, unknown>;
+/** Expand a sparse image to its full raw buffer (holes become zeros). Tests/small images only. */
+export declare function sparseToRaw(buf: Buffer): Buffer;

package/dist/sparse/decode.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPARSE_MAGIC = void 0;
+exports.isSparse = isSparse;
+exports.readSparseHeader = readSparseHeader;
+exports.decodeSparse = decodeSparse;
+exports.sparseToRaw = sparseToRaw;
+/**
+ * Android sparse image decoder. Yields an ordered op stream so a writer can
+ * stream straight to a block device (seek past holes) and a hasher can count
+ * holes as zeros — without ever materializing the whole expanded image.
+ *
+ * Reference (not a dependency): AOSP libsparse sparse_format.h.
+ */
+exports.SPARSE_MAGIC = 0xed26ff3a;
+const CHUNK_RAW = 0xcac1;
+const CHUNK_FILL = 0xcac2;
+const CHUNK_DONT_CARE = 0xcac3;
+const CHUNK_CRC32 = 0xcac4;
+function isSparse(buf) {
+    return buf.length >= 4 && buf.readUInt32LE(0) === exports.SPARSE_MAGIC;
+}
+function readSparseHeader(buf) {
+    if (!isSparse(buf))
+        throw new Error('not a sparse image (bad magic)');
+    const fileHdrSize = buf.readUInt16LE(8);
+    const blockSize = buf.readUInt32LE(12);
+    const totalBlocks = buf.readUInt32LE(16);
+    const totalChunks = buf.readUInt32LE(20);
+    if (fileHdrSize < 28)
+        throw new Error('sparse: short file header');
+    return { blockSize, totalBlocks, totalChunks };
+}
+/**
+ * Decode a sparse image buffer into an ordered op stream.
+ * FILL is expanded into data (the fill word repeated); DONT_CARE becomes skip.
+ */
+function* decodeSparse(buf) {
+    if (!isSparse(buf)) {
+        // already raw
+        yield { kind: 'data', data: buf };
+        return;
+    }
+    const fileHdrSize = buf.readUInt16LE(8);
+    const chunkHdrSize = buf.readUInt16LE(10);
+    const blockSize = buf.readUInt32LE(12);
+    const totalChunks = buf.readUInt32LE(20);
+    let off = fileHdrSize;
+    for (let i = 0; i < totalChunks; i++) {
+        const chunkType = buf.readUInt16LE(off);
+        const chunkBlocks = buf.readUInt32LE(off + 4);
+        const totalSz = buf.readUInt32LE(off + 8);
+        const dataOff = off + chunkHdrSize;
+        const dataLen = totalSz - chunkHdrSize;
+        const outBytes = chunkBlocks * blockSize;
+        switch (chunkType) {
+            case CHUNK_RAW:
+                yield { kind: 'data', data: buf.subarray(dataOff, dataOff + outBytes) };
+                break;
+            case CHUNK_FILL: {
+                const fill = buf.subarray(dataOff, dataOff + 4);
+                if (fill.readUInt32LE(0) === 0) {
+                    yield { kind: 'skip', length: outBytes }; // zero fill == hole
+                }
+                else {
+                    const out = Buffer.allocUnsafe(outBytes);
+                    for (let p = 0; p < outBytes; p += 4)
+                        fill.copy(out, p);
+                    yield { kind: 'data', data: out };
+                }
+                break;
+            }
+            case CHUNK_DONT_CARE:
+                yield { kind: 'skip', length: outBytes };
+                break;
+            case CHUNK_CRC32:
+                break; // metadata only
+            default:
+                throw new Error(`sparse: unknown chunk type 0x${chunkType.toString(16)}`);
+        }
+        off = dataOff + dataLen;
+    }
+}
+/** Expand a sparse image to its full raw buffer (holes become zeros). Tests/small images only. */
+function sparseToRaw(buf) {
+    const parts = [];
+    for (const op of decodeSparse(buf)) {
+        parts.push(op.kind === 'data' ? op.data : Buffer.alloc(op.length));
+    }
+    return Buffer.concat(parts);
+}

package/dist/validate/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared validator — used by composer CI, the cloud server, and the CLI so the
+ * checks live in one place. Operates on a parsed particle_image_v1 manifest;
+ * optionally also checks the embedded signature and the zip entry order.
+ */
+import { KeyObject } from 'node:crypto';
+import { type ParticleImageV1 } from '../manifest/particleImageV1';
+export interface CheckResult {
+    name: string;
+    ok: boolean;
+    errors: string[];
+}
+export interface ValidateReport {
+    ok: boolean;
+    checks: CheckResult[];
+}
+export interface ValidateOptions {
+    publicKey?: string | Buffer | KeyObject;
+    /** entry names in stored order (from listImageZip) to verify manifest-first. */
+    zipEntryNames?: string[];
+    /** require payload_sha256 on program ops. Default true; false for a no-hash dir inspection. */
+    requireHashes?: boolean;
+}
+export declare function validateManifest(m: ParticleImageV1, opts?: ValidateOptions): ValidateReport;
+/** Resolve a PEM string/buffer to a KeyObject (helper for the CLI). */
+export declare function loadPublicKey(pem: string | Buffer): KeyObject;

package/dist/validate/index.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateManifest = validateManifest;
+exports.loadPublicKey = loadPublicKey;
+/**
+ * Shared validator — used by composer CI, the cloud server, and the CLI so the
+ * checks live in one place. Operates on a parsed particle_image_v1 manifest;
+ * optionally also checks the embedded signature and the zip entry order.
+ */
+const node_crypto_1 = require("node:crypto");
+const sign_1 = require("../signing/sign");
+const particleImageV1_1 = require("../manifest/particleImageV1");
+function check(name, fn) {
+    let errors;
+    try {
+        errors = fn();
+    }
+    catch (e) {
+        errors = [e.message];
+    }
+    return { name, ok: errors.length === 0, errors };
+}
+function programOps(p) {
+    return p.ops.filter((o) => o.op === 'program');
+}
+function validateManifest(m, opts = {}) {
+    const checks = [];
+    const bySlot = (slot) => m.partitions.filter((p) => p.slot === slot);
+    checks.push(check('manifest-first', () => {
+        if (!opts.zipEntryNames)
+            return [];
+        return opts.zipEntryNames[0] === particleImageV1_1.MANIFEST_ENTRY_NAME
+            ? []
+            : [`first entry is '${opts.zipEntryNames[0]}', expected '${particleImageV1_1.MANIFEST_ENTRY_NAME}'`];
+    }));
+    checks.push(check('signature', () => {
+        if (!opts.publicKey)
+            return [];
+        if (m.signing.profile === 'none')
+            return [];
+        return (0, sign_1.verifyManifest)(m, opts.publicKey) ? [] : ['manifest signature does not verify against the supplied key'];
+    }));
+    checks.push(check('groups-present', () => {
+        if (m.format.kind !== 'factory')
+            return [];
+        const required = ['BOOT', 'FIRMWARE', 'A', 'B', 'NVM'];
+        const have = new Set(m.partitions.map((p) => p.group));
+        const missing = required.filter((g) => !have.has(g));
+        return missing.length ? [`factory image missing groups: ${missing.join(', ')}`] : [];
+    }));
+    checks.push(check('slot-symmetry', () => {
+        const errs = [];
+        const a = bySlot('a');
+        const b = bySlot('b');
+        const bByBase = new Map(b.map((p) => [p.label.replace(/_b$/, ''), p]));
+        for (const pa of a) {
+            const base = pa.label.replace(/_a$/, '');
+            const pb = bByBase.get(base);
+            if (!pb) {
+                errs.push(`slot A partition '${pa.label}' has no slot B peer`);
+                continue;
+            }
+            if (pa.size !== undefined && pb.size !== undefined && pa.size !== pb.size) {
+                errs.push(`'${pa.label}'/'${pb.label}' size mismatch (${pa.size} vs ${pb.size})`);
+            }
+            if (pa.type_guid && pb.type_guid && pa.type_guid === pb.type_guid) {
+                errs.push(`'${pa.label}'/'${pb.label}' share a type GUID (${pa.type_guid}); A/B slots must differ`);
+            }
+        }
+        return errs;
+    }));
+    checks.push(check('sizes-fit', () => {
+        const errs = [];
+        for (const p of m.partitions) {
+            if (!p.num_partition_sectors || !p.size)
+                continue;
+            const cap = p.num_partition_sectors * m.sector_size;
+            for (const op of programOps(p)) {
+                if (op.uncompressed_size && op.uncompressed_size > cap) {
+                    errs.push(`'${p.label}': image ${op.uncompressed_size}B exceeds partition ${cap}B`);
+                }
+            }
+        }
+        return errs;
+    }));
+    checks.push(check('program-hashes', () => {
+        const errs = [];
+        const requireHashes = opts.requireHashes !== false;
+        for (const p of m.partitions) {
+            for (const op of programOps(p)) {
+                if (!op.source && !op.chunks)
+                    errs.push(`'${p.label}': program op has neither source nor chunks`);
+                if (requireHashes && op.source && !op.payload_sha256) {
+                    errs.push(`'${p.label}': program op missing payload_sha256`);
+                }
+            }
+        }
+        return errs;
+    }));
+    checks.push(check('emittable', () => {
+        const errs = [];
+        const groups = new Set(m.partitions.map((p) => p.group));
+        const need = {
+            factory: ['BOOT', 'FIRMWARE', 'A', 'B'],
+            'ota-image': ['A'],
+            'ota-boot': ['BOOT', 'FIRMWARE', 'A'],
+        };
+        for (const kind of m.format.emittable) {
+            const missing = (need[kind] ?? []).filter((g) => !groups.has(g));
+            if (missing.length)
+                errs.push(`declared emittable '${kind}' but missing groups: ${missing.join(', ')}`);
+        }
+        return errs;
+    }));
+    return { ok: checks.every((c) => c.ok), checks };
+}
+/** Resolve a PEM string/buffer to a KeyObject (helper for the CLI). */
+function loadPublicKey(pem) {
+    return (0, node_crypto_1.createPublicKey)(pem);
+}

package/dist/xml/rawprogram.d.ts

@@ -0,0 +1,34 @@
+export type RawEntryKind = 'program' | 'erase' | 'read';
+/** A numeric LBA/size, or a verbatim expression string (e.g. "NUM_DISK_SECTORS-5."). */
+export type SectorValue = number | string;
+export interface RawEntry {
+    kind: RawEntryKind;
+    label: string;
+    physicalPartitionNumber: number;
+    startSector: SectorValue;
+    numPartitionSectors: SectorValue;
+    sectorSizeInBytes: number;
+    filename: string;
+    fileSectorOffset?: number;
+    sizeKB?: number;
+    partofsingleimage?: boolean;
+    readbackverify?: boolean;
+    sparse?: boolean;
+    startByteHex?: string;
+}
+export interface PatchEntry {
+    label?: string;
+    physicalPartitionNumber: number;
+    startSector: SectorValue;
+    byteOffset: number;
+    sizeInBytes: number;
+    value: string;
+    filename: string;
+    sectorSizeInBytes: number;
+    what?: string;
+}
+export declare function parseRawProgram(xml: string): RawEntry[];
+export declare function parsePatch(xml: string): PatchEntry[];
+/** Emit a rawprogram XML matching the Qualcomm attribute layout. */
+export declare function buildRawProgram(entries: RawEntry[]): string;
+export declare function buildPatch(entries: PatchEntry[]): string;

package/dist/xml/rawprogram.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRawProgram = parseRawProgram;
+exports.parsePatch = parsePatch;
+exports.buildRawProgram = buildRawProgram;
+exports.buildPatch = buildPatch;
+/**
+ * Qualcomm rawprogram / patch XML reader + writer.
+ *
+ * The grammar is attribute-only elements under a <data> (rawprogram) or
+ * <patches> (patch) root. `start_sector` / `num_partition_sectors` may be
+ * literal LBAs OR expressions like "NUM_DISK_SECTORS-5." — kept verbatim as
+ * strings so they round-trip losslessly. Reference (not a dependency):
+ * linux-msm/qdl (BSD) and bkerler/edl (GPL) for edge cases.
+ */
+const fast_xml_parser_1 = require("fast-xml-parser");
+const RAW_KINDS = ['program', 'erase', 'read'];
+function toArray(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+/** Parse a string attribute into number if it is a pure number, else keep verbatim. */
+function sectorVal(s) {
+    if (s === undefined || s === '')
+        return 0;
+    // pure integer or float (no letters/operators) -> number; else expression string
+    if (/^-?\d+(\.\d+)?\.?$/.test(s) && !s.endsWith('.'))
+        return Number(s);
+    if (/^-?\d+$/.test(s))
+        return Number(s);
+    return s;
+}
+function num(s) {
+    if (s === undefined || s === '')
+        return undefined;
+    const n = Number(s);
+    return Number.isNaN(n) ? undefined : n;
+}
+function bool(s) {
+    if (s === undefined)
+        return undefined;
+    return s === 'true' || s === 'TRUE' || s === '1';
+}
+function mkParser() {
+    return new fast_xml_parser_1.XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: '',
+        parseAttributeValue: false, // keep all attributes as raw strings; we coerce explicitly
+        allowBooleanAttributes: true,
+        trimValues: true,
+    });
+}
+function parseRawProgram(xml) {
+    const doc = mkParser().parse(xml);
+    const data = doc.data ?? {};
+    const out = [];
+    for (const kind of RAW_KINDS) {
+        for (const a of toArray(data[kind])) {
+            out.push({
+                kind,
+                label: a.label ?? '',
+                physicalPartitionNumber: num(a.physical_partition_number) ?? 0,
+                startSector: sectorVal(a.start_sector),
+                numPartitionSectors: sectorVal(a.num_partition_sectors),
+                sectorSizeInBytes: num(a.SECTOR_SIZE_IN_BYTES) ?? 4096,
+                filename: a.filename ?? '',
+                fileSectorOffset: num(a.file_sector_offset),
+                sizeKB: num(a.size_in_KB),
+                partofsingleimage: bool(a.partofsingleimage),
+                readbackverify: bool(a.readbackverify),
+                sparse: bool(a.sparse),
+                startByteHex: a.start_byte_hex,
+            });
+        }
+    }
+    return out;
+}
+function parsePatch(xml) {
+    const doc = mkParser().parse(xml);
+    const patches = doc.patches ?? {};
+    return toArray(patches.patch).map((a) => ({
+        label: a.label,
+        physicalPartitionNumber: num(a.physical_partition_number) ?? 0,
+        startSector: sectorVal(a.start_sector),
+        byteOffset: num(a.byte_offset) ?? 0,
+        sizeInBytes: num(a.size_in_bytes) ?? 0,
+        value: a.value ?? '',
+        filename: a.filename ?? '',
+        sectorSizeInBytes: num(a.SECTOR_SIZE_IN_BYTES) ?? 4096,
+        what: a.what,
+    }));
+}
+function attr(name, v) {
+    if (v === undefined)
+        return '';
+    return ` ${name}="${v}"`;
+}
+/** Emit a rawprogram XML matching the Qualcomm attribute layout. */
+function buildRawProgram(entries) {
+    const lines = ['<?xml version="1.0" ?>', '<data>'];
+    lines.push('  <!--NOTE: This is an ** Autogenerated file **-->');
+    lines.push('  <!--NOTE: Sector size is 4096bytes-->');
+    for (const e of entries) {
+        let s = `  <${e.kind}`;
+        s += attr('start_sector', e.startSector);
+        if (e.sizeKB !== undefined)
+            s += attr('size_in_KB', e.sizeKB);
+        s += attr('physical_partition_number', e.physicalPartitionNumber);
+        if (e.partofsingleimage !== undefined)
+            s += attr('partofsingleimage', e.partofsingleimage);
+        if (e.fileSectorOffset !== undefined)
+            s += attr('file_sector_offset', e.fileSectorOffset);
+        s += attr('num_partition_sectors', e.numPartitionSectors);
+        if (e.readbackverify !== undefined)
+            s += attr('readbackverify', e.readbackverify);
+        s += attr('filename', e.filename);
+        if (e.sparse !== undefined)
+            s += attr('sparse', e.sparse);
+        if (e.startByteHex !== undefined)
+            s += attr('start_byte_hex', e.startByteHex);
+        s += attr('SECTOR_SIZE_IN_BYTES', e.sectorSizeInBytes);
+        s += attr('label', e.label);
+        s += '/>';
+        lines.push(s);
+    }
+    lines.push('</data>');
+    return lines.join('\n') + '\n';
+}
+function buildPatch(entries) {
+    const lines = ['<?xml version="1.0" ?>', '<patches>'];
+    lines.push('  <!--NOTE: This is an ** Autogenerated file **-->');
+    for (const e of entries) {
+        let s = '  <patch';
+        s += attr('start_sector', e.startSector);
+        s += attr('byte_offset', e.byteOffset);
+        s += attr('physical_partition_number', e.physicalPartitionNumber);
+        s += attr('size_in_bytes', e.sizeInBytes);
+        s += attr('value', e.value);
+        s += attr('filename', e.filename);
+        s += attr('SECTOR_SIZE_IN_BYTES', e.sectorSizeInBytes);
+        if (e.what !== undefined)
+            s += attr('what', e.what);
+        s += '/>';
+        lines.push(s);
+    }
+    lines.push('</patches>');
+    return lines.join('\n') + '\n';
+}

package/dist/zip/index.d.ts

@@ -0,0 +1,18 @@
+import { type ParticleImageV1 } from '../manifest/particleImageV1';
+export interface PayloadEntry {
+    /** entry name inside the zip (matches a partition op `source`) */
+    name: string;
+    /** already-prepared (compressed/sparse) bytes, or a source file path */
+    buffer?: Buffer;
+    path?: string;
+}
+/** Write a manifest-first zip. Entries are written in the given order. */
+export declare function writeImageZip(outPath: string, manifest: ParticleImageV1, payloads: PayloadEntry[]): Promise<void>;
+export interface ZipEntryInfo {
+    name: string;
+    uncompressedSize: number;
+}
+/** List entries in stored (central-directory) order. */
+export declare function listImageZip(zipPath: string): Promise<ZipEntryInfo[]>;
+/** Read + parse the first entry as the particle_image_v1 manifest. */
+export declare function readManifestFromZip(zipPath: string): Promise<ParticleImageV1>;

package/dist/zip/index.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeImageZip = writeImageZip;
+exports.listImageZip = listImageZip;
+exports.readManifestFromZip = readManifestFromZip;
+/**
+ * Manifest-first image ZIP. `particle-image.json` is always the FIRST entry,
+ * followed by payload entries in flash order — so a sequential reader can verify
+ * the manifest before any payload, and decode each partition as it streams. The
+ * central directory still allows random-access extraction of a single entry.
+ */
+const node_fs_1 = require("node:fs");
+const yazl_1 = __importDefault(require("yazl"));
+const yauzl_1 = __importDefault(require("yauzl"));
+const particleImageV1_1 = require("../manifest/particleImageV1");
+/** Write a manifest-first zip. Entries are written in the given order. */
+function writeImageZip(outPath, manifest, payloads) {
+    return new Promise((resolve, reject) => {
+        const zip = new yazl_1.default.ZipFile();
+        const out = (0, node_fs_1.createWriteStream)(outPath);
+        out.on('close', resolve);
+        out.on('error', reject);
+        zip.outputStream.on('error', reject);
+        zip.outputStream.pipe(out);
+        // manifest FIRST; store uncompressed (it is small and we want it byte-stable)
+        const manifestBuf = Buffer.from(JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+        zip.addBuffer(manifestBuf, particleImageV1_1.MANIFEST_ENTRY_NAME, { compress: false });
+        for (const p of payloads) {
+            if (p.buffer)
+                zip.addBuffer(p.buffer, p.name, { compress: false });
+            else if (p.path)
+                zip.addFile(p.path, p.name, { compress: false });
+            else
+                throw new Error(`writeImageZip: entry ${p.name} has no buffer or path`);
+        }
+        zip.end();
+    });
+}
+/** List entries in stored (central-directory) order. */
+function listImageZip(zipPath) {
+    return new Promise((resolve, reject) => {
+        const entries = [];
+        yauzl_1.default.open(zipPath, { lazyEntries: true }, (err, zf) => {
+            if (err || !zf)
+                return reject(err ?? new Error('open failed'));
+            zf.on('entry', (e) => {
+                entries.push({ name: e.fileName, uncompressedSize: e.uncompressedSize });
+                zf.readEntry();
+            });
+            zf.on('end', () => resolve(entries));
+            zf.on('error', reject);
+            zf.readEntry();
+        });
+    });
+}
+/** Read + parse the first entry as the particle_image_v1 manifest. */
+function readManifestFromZip(zipPath) {
+    return new Promise((resolve, reject) => {
+        yauzl_1.default.open(zipPath, { lazyEntries: true }, (err, zf) => {
+            if (err || !zf)
+                return reject(err ?? new Error('open failed'));
+            let handled = false;
+            zf.on('entry', (e) => {
+                if (handled)
+                    return;
+                handled = true;
+                if (e.fileName !== particleImageV1_1.MANIFEST_ENTRY_NAME) {
+                    return reject(new Error(`first zip entry is '${e.fileName}', expected '${particleImageV1_1.MANIFEST_ENTRY_NAME}'`));
+                }
+                zf.openReadStream(e, (er, rs) => {
+                    if (er || !rs)
+                        return reject(er ?? new Error('read failed'));
+                    const chunks = [];
+                    rs.on('data', (c) => chunks.push(c));
+                    rs.on('end', () => {
+                        try {
+                            resolve((0, particleImageV1_1.parseParticleImageV1)(Buffer.concat(chunks).toString('utf8')));
+                        }
+                        catch (e2) {
+                            reject(e2);
+                        }
+                    });
+                    rs.on('error', reject);
+                });
+            });
+            zf.on('error', reject);
+            zf.readEntry();
+        });
+    });
+}