spawnfile 0.1.13 → 0.1.14

package/dist/target/evidenceExportArchive.js

@@ -0,0 +1,302 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+const BLOCK = 512;
+const MAX_BYTES = 67_108_864;
+const MAX_ENTRIES = 10_000;
+const MAX_DEPTH = 32;
+const MAX_PATH_BYTES = 255;
+const MAX_STORED_BYTES = 256;
+const ZERO = 0;
+const USTAR_MAGIC = Buffer.from("ustar\0", "ascii");
+const USTAR_VERSION = Buffer.from("00", "ascii");
+const fail = (reason = "") => { throw new Error(`Evidence-volume export failed${reason ? ` (${reason})` : ""}`); };
+const isZero = (value) => value.every((byte) => byte === 0);
+const utf8 = (value) => {
+    const parsed = Buffer.from(value).toString("utf8");
+    if (!Buffer.from(parsed, "utf8").equals(Buffer.from(value)))
+        return fail();
+    return parsed;
+};
+const isEqual = (left, right) => {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    for (let index = 0; index < left.byteLength; index += 1)
+        if (left[index] !== right[index])
+            return false;
+    return true;
+};
+const pad = (value) => Math.ceil(value / BLOCK) * BLOCK;
+const text = (value, start, length) => {
+    const field = value.subarray(start, start + length);
+    const nul = field.indexOf(0);
+    if (nul < 0)
+        return utf8(field);
+    for (let index = nul + 1; index < field.length; index += 1) {
+        if (field[index] !== 0)
+            return fail();
+    }
+    return utf8(field.subarray(0, nul));
+};
+const parseOctal = (value, start, length) => {
+    const field = value.subarray(start, start + length);
+    if (field[length - 1] !== ZERO)
+        return fail();
+    for (let index = 0; index < length - 1; index += 1) {
+        const byte = field[index];
+        if (byte < 48 || byte > 55)
+            return fail();
+    }
+    const parsed = Number.parseInt(utf8(field.subarray(0, length - 1)), 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        return fail();
+    return parsed;
+};
+const parseChecksum = (value) => {
+    const field = value.subarray(148, 156);
+    if (field[6] !== ZERO || field[7] !== 0x20)
+        return fail();
+    for (let index = 0; index < 6; index += 1) {
+        const byte = field[index];
+        if (byte < 48 || byte > 55)
+            return fail();
+    }
+    const parsed = Number.parseInt(utf8(field.subarray(0, 6)), 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 0o777777)
+        return fail();
+    return parsed;
+};
+const writeOctal = (value, width) => {
+    const raw = value.toString(8);
+    if (!Number.isSafeInteger(value) || value < 0 || raw.length > width - 1)
+        return fail();
+    return Buffer.from(`${raw.padStart(width - 1, "0")}\0`, "ascii");
+};
+const writeChecksum = (header) => {
+    let checksum = 0;
+    header.fill(0x20, 148, 156);
+    for (let index = 0; index < BLOCK; index += 1)
+        checksum += header[index];
+    if (checksum > 0o777777)
+        return fail();
+    const field = `${checksum.toString(8).padStart(6, "0")}\0 `;
+    header.set(Buffer.from(field, "ascii"), 148);
+};
+const hasFileAncestorOrDescendantConflict = (files, key, directoryMode) => {
+    for (const file of files) {
+        if (file === key)
+            return true;
+        if (key.startsWith(`${file}/`))
+            return true;
+        if (!directoryMode && file.startsWith(`${key}/`))
+            return true;
+    }
+    return false;
+};
+const hasDirectoryConflict = (directories, key) => {
+    for (const directory of directories)
+        if (directory === key)
+            return true;
+    return false;
+};
+const splitStored = (stored) => {
+    const storedBytes = Buffer.from(stored, "utf8");
+    if (storedBytes.byteLength <= 100)
+        return Object.freeze({ prefix: "", name: stored });
+    if (storedBytes.byteLength > MAX_STORED_BYTES)
+        return fail();
+    let split = -1;
+    for (let index = storedBytes.lastIndexOf(0x2f); index > 0; index = storedBytes.lastIndexOf(0x2f, index - 1)) {
+        const prefixLength = index;
+        const nameLength = storedBytes.byteLength - index - 1;
+        if (prefixLength <= 155 && nameLength <= 100 && nameLength > 0) {
+            split = index;
+            break;
+        }
+    }
+    if (split < 0)
+        return fail();
+    return Object.freeze({
+        name: storedBytes.subarray(split + 1).toString("utf8"),
+        prefix: storedBytes.subarray(0, split).toString("utf8")
+    });
+};
+const entryPath = (header) => {
+    const name = text(header, 0, 100);
+    const prefix = text(header, 345, 155);
+    const stored = prefix ? `${prefix}/${name}` : name;
+    const canonical = splitStored(stored);
+    if (canonical.name !== name || canonical.prefix !== prefix)
+        return fail();
+    if (!name)
+        return fail();
+    if (prefix === "" && Buffer.byteLength(stored, "utf8") > 100)
+        return fail();
+    if (prefix !== "" && (Buffer.byteLength(stored, "utf8") <= 100 || Buffer.byteLength(prefix, "utf8") > 155 || Buffer.byteLength(name, "utf8") > 100))
+        return fail();
+    if (stored.startsWith("/") || stored.includes("\\") || stored.includes("\0"))
+        return fail();
+    if (stored.includes("//"))
+        return fail();
+    const typeByte = header[156];
+    const type = typeByte === 48 ? "file" : typeByte === 53 ? "directory" : null;
+    if (!type)
+        return fail();
+    let path;
+    if (type === "directory") {
+        if (!stored.endsWith("/"))
+            return fail();
+        path = stored.slice(0, -1);
+        if (path === "" || path.endsWith("/"))
+            return fail();
+    }
+    else {
+        if (stored.endsWith("/"))
+            return fail();
+        path = stored;
+    }
+    if (path === "" || Buffer.byteLength(path, "utf8") > MAX_PATH_BYTES)
+        return fail();
+    const parts = path.split("/");
+    if (parts.length > MAX_DEPTH || parts.some((part) => part === "" || part === "." || part === ".."))
+        return fail();
+    for (const part of parts) {
+        for (let index = 0; index < part.length; index += 1) {
+            const code = part.charCodeAt(index);
+            if (code < 0x20 || code === 0x7f)
+                return fail();
+        }
+        if (part.includes("\\") || part.includes("\0"))
+            return fail();
+    }
+    return Object.freeze({ path, stored, type });
+};
+const rebuildHeader = (entry) => {
+    const out = Buffer.alloc(BLOCK);
+    const split = splitStored(entry.stored);
+    out.set(Buffer.from(split.name, "utf8"), 0);
+    out.set(writeOctal(entry.type === "directory" ? 0o755 : 0o644, 8), 100);
+    out.set(writeOctal(0, 8), 108);
+    out.set(writeOctal(0, 8), 116);
+    out.set(writeOctal(entry.size, 12), 124);
+    out.set(writeOctal(0, 12), 136);
+    out[156] = entry.type === "directory" ? 53 : 48;
+    out.set(USTAR_MAGIC, 257);
+    out.set(USTAR_VERSION, 263);
+    if (split.prefix)
+        out.set(Buffer.from(split.prefix, "utf8"), 345);
+    out.set(writeOctal(0, 8), 329);
+    out.set(writeOctal(0, 8), 337);
+    writeChecksum(out);
+    return out;
+};
+const rebuildArchive = (entries) => {
+    const output = [];
+    const sorted = [...entries].sort((left, right) => {
+        const pathOrder = Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8"));
+        return pathOrder !== 0 ? pathOrder : 0;
+    });
+    for (const entry of sorted) {
+        output.push(rebuildHeader(entry));
+        if (entry.size > 0) {
+            const data = Buffer.alloc(pad(entry.size));
+            data.set(Buffer.from(entry.bytes));
+            output.push(data);
+        }
+    }
+    output.push(Buffer.alloc(BLOCK), Buffer.alloc(BLOCK));
+    return Buffer.concat(output);
+};
+/** Parses evidence archives as strict canonical USTAR. */
+export const canonicalEvidenceArchive = (raw) => {
+    if (!(raw instanceof Uint8Array) || raw.byteLength < BLOCK * 2 || raw.byteLength > MAX_BYTES || raw.byteLength % BLOCK !== 0)
+        return fail();
+    const files = new Set();
+    const directories = new Set();
+    const entries = [];
+    let offset = 0;
+    let itemCount = 0;
+    while (offset < raw.byteLength) {
+        const header = raw.subarray(offset, offset + BLOCK);
+        if (header.byteLength !== BLOCK)
+            return fail();
+        offset += BLOCK;
+        if (isZero(header)) {
+            if (itemCount === 0 || offset + BLOCK > raw.byteLength)
+                return fail();
+            if (!isZero(raw.subarray(offset, offset + BLOCK)))
+                return fail();
+            offset += BLOCK;
+            if (offset !== raw.byteLength)
+                return fail();
+            const inventory = entries.filter((entry) => entry.type === "file")
+                .sort((left, right) => Buffer.compare(Buffer.from(left.path), Buffer.from(right.path)))
+                .map((entry) => Object.freeze({
+                bytes: entry.size,
+                path: entry.path,
+                sha256: `sha256:${createHash("sha256").update(entry.bytes).digest("hex")}`
+            }));
+            return Object.freeze({ bytes: rebuildArchive(entries), files: Object.freeze(inventory), itemCount });
+        }
+        if (!isEqual(header.subarray(257, 263), USTAR_MAGIC))
+            return fail();
+        if (header[263] !== 48 || header[264] !== 48)
+            return fail();
+        if (!isZero(header.subarray(157, 257)))
+            return fail();
+        const claimedChecksum = parseChecksum(header);
+        let actualChecksum = 0;
+        for (let index = 0; index < BLOCK; index += 1) {
+            actualChecksum += index >= 148 && index < 156 ? 0x20 : header[index];
+        }
+        if (actualChecksum !== claimedChecksum)
+            return fail();
+        const mode = parseOctal(header, 100, 8);
+        const uid = parseOctal(header, 108, 8);
+        const gid = parseOctal(header, 116, 8);
+        const size = parseOctal(header, 124, 12);
+        const mtime = parseOctal(header, 136, 12);
+        if (uid !== 0 || gid !== 0 || mtime !== 0)
+            return fail();
+        const metadata = entryPath(header);
+        if (metadata.type === "directory") {
+            if (hasDirectoryConflict(directories, metadata.path))
+                return fail();
+            if (hasFileAncestorOrDescendantConflict(files, metadata.path, true))
+                return fail();
+            if (mode !== 0o755 || size !== 0)
+                return fail();
+        }
+        else {
+            if (hasFileAncestorOrDescendantConflict(files, metadata.path, false))
+                return fail();
+            if (hasDirectoryConflict(directories, metadata.path))
+                return fail();
+            if (mode !== 0o644 || size > MAX_BYTES)
+                return fail();
+        }
+        if (text(header, 265, 32) !== "" || text(header, 297, 32) !== "")
+            return fail();
+        if (parseOctal(header, 329, 8) !== 0 || parseOctal(header, 337, 8) !== 0)
+            return fail();
+        if (!isZero(header.subarray(500, 512)))
+            return fail();
+        if (metadata.type === "file")
+            files.add(metadata.path);
+        else
+            directories.add(metadata.path);
+        if (itemCount >= MAX_ENTRIES)
+            return fail();
+        itemCount += 1;
+        const dataEnd = offset + size;
+        if (dataEnd > raw.byteLength)
+            return fail();
+        const paddedEnd = offset + pad(size);
+        if (paddedEnd > raw.byteLength)
+            return fail();
+        if (!isZero(raw.subarray(dataEnd, paddedEnd)))
+            return fail();
+        entries.push(Object.freeze({ bytes: raw.subarray(offset, dataEnd), path: metadata.path, size, stored: metadata.stored, type: metadata.type }));
+        offset = paddedEnd;
+    }
+    return fail();
+};

package/dist/target/evidenceExportContract.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const TARGET_EXPORT_INDEX_VERSION: "spawnfile.target-resource.export-index.v1";
+export declare const targetResourceExportIndexSchema: z.ZodObject<{
+    evidence_digest: z.ZodString;
+    export_handle: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        bytes: z.ZodNumber;
+        path: z.ZodUnion<[z.ZodString, z.ZodLiteral<".spawnfile/world-service-activated.v1">]>;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    item_count: z.ZodNumber;
+    labels: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+    run_id: z.ZodString;
+    source: z.ZodObject<{
+        evidence_volume_handle: z.ZodString;
+        state: z.ZodLiteral<"preserved">;
+    }, z.core.$strict>;
+    state: z.ZodEnum<{
+        exported: "exported";
+        incomplete: "incomplete";
+    }>;
+    version: z.ZodLiteral<"spawnfile.target-resource.export-index.v1">;
+}, z.core.$strict>;
+export type TargetResourceExportIndex = z.infer<typeof targetResourceExportIndexSchema>;

package/dist/target/evidenceExportContract.js

@@ -0,0 +1,40 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+export const TARGET_EXPORT_INDEX_VERSION = "spawnfile.target-resource.export-index.v1";
+const digest = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
+const handle = z.string().regex(/^opaque_[a-z0-9]{16,64}$/u);
+const label = z.object({
+    key: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u),
+    value: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u)
+}).strict();
+const activationMarker = ".spawnfile/world-service-activated.v1";
+const path = z.string().max(255).regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/u)
+    .or(z.literal(activationMarker))
+    .refine((value) => !value.includes("//")
+    && !value.split("/").some((part) => part === "." || part === ".."));
+const runId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u)
+    .refine((value) => Buffer.byteLength(value, "utf8") <= 128);
+export const targetResourceExportIndexSchema = z.object({
+    evidence_digest: digest,
+    export_handle: handle,
+    files: z.array(z.object({
+        bytes: z.number().int().min(0).max(67_108_864), path, sha256: digest
+    }).strict()).max(10_000),
+    item_count: z.number().int().min(0).max(10_000),
+    labels: z.array(label).max(16),
+    run_id: runId,
+    source: z.object({ evidence_volume_handle: handle, state: z.literal("preserved") }).strict(),
+    state: z.enum(["exported", "incomplete"]),
+    version: z.literal(TARGET_EXPORT_INDEX_VERSION)
+}).strict().superRefine((value, context) => {
+    const paths = value.files.map((file) => file.path);
+    if (value.item_count !== value.files.length)
+        context.addIssue({
+            code: z.ZodIssueCode.custom, message: "evidence export item count is invalid"
+        });
+    if (new Set(paths).size !== paths.length
+        || paths.some((entry, index) => index > 0 && paths[index - 1] >= entry))
+        context.addIssue({
+            code: z.ZodIssueCode.custom, message: "evidence export file inventory is invalid"
+        });
+});

package/dist/target/evidenceExportOperationsTestKit.d.ts

@@ -0,0 +1,87 @@
+import { type EvidenceExportAdmission, type EvidenceExportAuthorityStoreOptions } from "./evidenceExportStore.js";
+import { type TargetJournalStore } from "./journal.js";
+export declare const root: () => Promise<string>;
+export declare const cleanupTestRoots: () => Promise<void>;
+declare const admission: () => EvidenceExportAdmission;
+export { admission };
+declare const complete: (journal: TargetJournalStore, claim: {
+    operationHandle: string;
+    requestDigest: string;
+}, request: Record<string, unknown>, spec: {
+    labels: Record<string, string>;
+    resultHandle: string;
+}) => Promise<void>;
+export { complete };
+export declare const header: (name: string, data: Uint8Array) => Buffer;
+export interface LifecycleExportFixture {
+    readonly calls: string[][];
+    readonly directory: string;
+    readonly execute: (destination?: string) => Promise<unknown>;
+    readonly executeDistinct: (destination?: string) => Promise<unknown>;
+    readonly executeReplayWithBlockedExecutors: (destination?: string) => Promise<{
+        readonly dockerCalls: number;
+        readonly exportCalls: number;
+        readonly result: unknown;
+    }>;
+    readonly rejectReplayWithWrongHelperRequest: (destination?: string) => Promise<{
+        readonly dockerCalls: number;
+        readonly error: unknown;
+        readonly exportCalls: number;
+    }>;
+    readonly recover: (destination?: string) => Promise<unknown>;
+    readonly recoverDistinct: (destination?: string) => Promise<unknown>;
+    readonly recoverPeer: (destination?: string) => Promise<unknown>;
+    readonly seedStaleExportClaim: () => Promise<void>;
+    readonly setHelperInspectionDrift: (value: boolean) => void;
+    readonly setVolumeInspectionDrift: (value: boolean) => void;
+    readonly getContainerName: () => string | undefined;
+    readonly getExportCalls: () => number;
+    readonly getRemoveCalls: () => number;
+    readonly getRemoveArgs: () => string[][];
+    readonly getExportStorePath: () => string;
+    readonly readJournalRevision: () => Promise<number>;
+}
+export interface LifecycleExportInput {
+    readonly createShouldFail?: boolean;
+    readonly createDestinationStoreOptions?: EvidenceExportAuthorityStoreOptions;
+    readonly foreignInspect?: "projection" | "transport" | false;
+    readonly startShouldFail?: boolean;
+    readonly cleanupShouldFail?: boolean;
+    readonly boundaryFailures?: {
+        readonly beforeBindAdmission?: () => Promise<void> | void;
+        readonly beforeBindDestination?: () => Promise<void> | void;
+        readonly beforeIndexLoad?: () => Promise<void> | void;
+        readonly beforeIndexBind?: () => Promise<void> | void;
+        readonly beforeArchive?: () => Promise<void> | void;
+        readonly beforePublishTempWrite?: () => Promise<void> | void;
+        readonly beforePublishTempOpen?: (temporary: string) => Promise<void> | void;
+        readonly beforePublishTempSync?: () => Promise<void> | void;
+        readonly beforePublishFinalLink?: () => Promise<void> | void;
+        readonly beforePublishDirectorySync?: () => Promise<void> | void;
+        readonly beforeJournalComplete?: () => Promise<void> | void;
+        readonly beforeRequireDestination?: () => Promise<void> | void;
+    };
+    readonly onLoadIndex?: () => Promise<void> | void;
+    readonly payload?: Uint8Array;
+}
+export declare const runLifecycleExport: (input?: LifecycleExportInput) => Promise<LifecycleExportFixture>;
+export declare const helperProjection: (args: string[], volumeName: string, imageLabels: Record<string, string>, mutate?: (value: {
+    Config: {
+        Entrypoint: unknown;
+        Cmd: unknown;
+        Env: unknown;
+        ExposedPorts: unknown;
+        Healthcheck: unknown;
+        Image: unknown;
+        Labels: Record<string, string>;
+        User: unknown;
+        Volumes: unknown;
+    };
+    HostConfig: Record<string, unknown>;
+    Mounts: Array<{
+        Type: string;
+        Name: string;
+        Destination: string;
+        RW: boolean;
+    }>;
+}) => void) => string;