harnery 0.34.1 → 0.36.0

package/dist/core/events/v3/support-storage/pack-reader.d.ts

@@ -0,0 +1,34 @@
+import { type EventV3SupportPackManifest, type EventV3SupportPackRecord } from "./pack-contract.js";
+export interface EventV3SupportPackLimits {
+    max_manifest_bytes?: number;
+    max_payload_bytes?: number;
+    max_decompressed_bytes?: number;
+    max_record_line_bytes?: number;
+    max_entries?: number;
+    fault?: (boundary: "after_payload_digest", path: string) => void;
+}
+export interface DecodedEventV3SupportPackRecord extends Omit<EventV3SupportPackRecord, "content_base64"> {
+    content: Buffer;
+}
+export interface ValidatedEventV3SupportPack {
+    manifest: EventV3SupportPackManifest;
+    records: DecodedEventV3SupportPackRecord[];
+}
+export interface VerifiedEventV3SupportPack {
+    manifest: EventV3SupportPackManifest;
+    entries: number;
+    uncompressed_bytes: number;
+}
+export declare function readEventV3SupportPackManifest(manifestPath: string, limits?: EventV3SupportPackLimits): Promise<EventV3SupportPackManifest>;
+/** Validate one pack and stream logical records to the caller one source file at a time. */
+export declare function streamEventV3SupportPackRecords(manifestPath: string, limits?: EventV3SupportPackLimits): AsyncGenerator<DecodedEventV3SupportPackRecord>;
+export declare function validateEventV3SupportPack(manifestPath: string, limits?: EventV3SupportPackLimits): Promise<ValidatedEventV3SupportPack>;
+/** Verify the complete pack while retaining only one decoded source record at a time. */
+export declare function verifyEventV3SupportPack(manifestPath: string, limits?: EventV3SupportPackLimits): Promise<VerifiedEventV3SupportPack>;
+/** Unpack only into a destination that does not yet exist; never overlay an authority. */
+export declare function unpackEventV3SupportPack(manifestPath: string, destination: string, limits?: EventV3SupportPackLimits): Promise<{
+    files: number;
+    bytes: number;
+    destination: string;
+}>;
+//# sourceMappingURL=pack-reader.d.ts.map

package/dist/core/events/v3/support-storage/pack-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-reader.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/pack-reader.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAI9B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AAED,MAAM,WAAW,+BACf,SAAQ,IAAI,CAAC,wBAAwB,EAAE,gBAAgB,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,0BAA0B,CAAC;IACrC,OAAO,EAAE,+BAA+B,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAUD,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,wBAA6B,GACpC,OAAO,CAAC,0BAA0B,CAAC,CAarC;AAED,4FAA4F;AAC5F,wBAAuB,+BAA+B,CACpD,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,wBAA6B,GACpC,cAAc,CAAC,+BAA+B,CAAC,CAGjD;AA2GD,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,wBAA6B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAWtC;AAED,yFAAyF;AACzF,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,wBAA6B,GACpC,OAAO,CAAC,0BAA0B,CAAC,CAarC;AAED,0FAA0F;AAC1F,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,wBAA6B,GACpC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BhE"}

package/dist/core/events/v3/support-storage/pack-reader.js

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream } from "node:fs";
+import { lstat, mkdir, open, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { createGunzip, createInflateRaw } from "node:zlib";
+import { logicalEntriesDigestV3, validateEventV3SupportPackManifest, validateEventV3SupportPackRecord, } from "./pack-contract.js";
+const DEFAULT_LIMITS = {
+    max_manifest_bytes: 1024 * 1024,
+    max_payload_bytes: 8 * 1024 * 1024 * 1024,
+    max_decompressed_bytes: 16 * 1024 * 1024 * 1024,
+    max_record_line_bytes: 128 * 1024 * 1024,
+    max_entries: 2_000_000,
+};
+export async function readEventV3SupportPackManifest(manifestPath, limits = {}) {
+    const bounded = { ...DEFAULT_LIMITS, ...limits };
+    const path = resolve(manifestPath);
+    const handle = await openStableRegularFile(path, undefined, "manifest");
+    try {
+        const stat = await handle.stat();
+        if (stat.size > bounded.max_manifest_bytes)
+            throw new Error("event_v3_support_manifest_too_large");
+        const value = JSON.parse(await handle.readFile("utf8"));
+        return validateEventV3SupportPackManifest(value);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Validate one pack and stream logical records to the caller one source file at a time. */
+export async function* streamEventV3SupportPackRecords(manifestPath, limits = {}) {
+    const manifest = await readEventV3SupportPackManifest(manifestPath, limits);
+    yield* streamEventV3SupportPackRecordsForManifest(manifestPath, manifest, limits);
+}
+async function* streamEventV3SupportPackRecordsForManifest(manifestPath, manifest, limits) {
+    const bounded = { ...DEFAULT_LIMITS, ...limits };
+    const manifestDirectory = await realDirectory(dirname(resolve(manifestPath)));
+    const payloadPath = resolve(manifestDirectory, manifest.payload.path);
+    const payloadHandle = await openStableRegularFile(payloadPath, manifestDirectory, "payload");
+    try {
+        const payloadStat = await payloadHandle.stat();
+        if (payloadStat.size !== manifest.payload.bytes)
+            throw new Error("event_v3_support_payload_length_mismatch");
+        if (payloadStat.size > bounded.max_payload_bytes)
+            throw new Error("event_v3_support_payload_too_large");
+        if ((await hashHandle(payloadPath, payloadHandle)) !== manifest.payload.digest) {
+            throw new Error("event_v3_support_payload_digest_mismatch");
+        }
+        limits.fault?.("after_payload_digest", payloadPath);
+        await assertCanonicalSingleGzipMember(payloadPath, payloadHandle, payloadStat.size, bounded.max_decompressed_bytes);
+        const gunzip = createGunzip();
+        const source = createReadStream(payloadPath, {
+            fd: payloadHandle.fd,
+            autoClose: false,
+            start: 0,
+        });
+        source.pipe(gunzip);
+        const decoder = new StringDecoder("utf8");
+        let pending = "";
+        let decompressedBytes = 0;
+        let entryCount = 0;
+        let uncompressedBytes = 0;
+        let priorPath;
+        const entries = [];
+        const seen = new Set();
+        for await (const current of gunzip) {
+            const chunk = current;
+            decompressedBytes += chunk.length;
+            if (decompressedBytes > bounded.max_decompressed_bytes) {
+                throw new Error("event_v3_support_decompression_bound_exceeded");
+            }
+            pending += decoder.write(chunk);
+            if (Buffer.byteLength(pending) > bounded.max_record_line_bytes && !pending.includes("\n")) {
+                throw new Error("event_v3_support_record_bound_exceeded");
+            }
+            let newline = pending.indexOf("\n");
+            while (newline >= 0) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                if (line.length === 0)
+                    throw new Error("event_v3_support_trailing_data");
+                if (Buffer.byteLength(line) > bounded.max_record_line_bytes) {
+                    throw new Error("event_v3_support_record_bound_exceeded");
+                }
+                const record = validateEventV3SupportPackRecord(JSON.parse(line));
+                entryCount += 1;
+                if (entryCount > bounded.max_entries)
+                    throw new Error("event_v3_support_entry_bound_exceeded");
+                if (seen.has(record.path))
+                    throw new Error("event_v3_support_duplicate_path");
+                if (priorPath !== undefined && priorPath.localeCompare(record.path) >= 0) {
+                    throw new Error("event_v3_support_record_order_invalid");
+                }
+                seen.add(record.path);
+                priorPath = record.path;
+                const content = Buffer.from(record.content_base64, "base64");
+                if (content.toString("base64") !== record.content_base64) {
+                    throw new Error("event_v3_support_record_base64_noncanonical");
+                }
+                if (content.length !== record.bytes)
+                    throw new Error("event_v3_support_record_length_mismatch");
+                if (`sha256:${createHash("sha256").update(content).digest("hex")}` !== record.digest) {
+                    throw new Error("event_v3_support_record_digest_mismatch");
+                }
+                uncompressedBytes += content.length;
+                entries.push({ path: record.path, bytes: record.bytes, digest: record.digest });
+                yield { path: record.path, bytes: record.bytes, digest: record.digest, content };
+                newline = pending.indexOf("\n");
+            }
+        }
+        pending += decoder.end();
+        if (pending.length !== 0)
+            throw new Error("event_v3_support_payload_truncated_or_trailing");
+        if (entryCount !== manifest.entries.count ||
+            uncompressedBytes !== manifest.entries.uncompressed_bytes) {
+            throw new Error("event_v3_support_manifest_entry_mismatch");
+        }
+        const digest = logicalEntriesDigestV3(entries);
+        if (digest !== manifest.entries.logical_entries_digest ||
+            digest !== manifest.authority.source_files_digest) {
+            throw new Error("event_v3_support_logical_digest_mismatch");
+        }
+    }
+    finally {
+        await payloadHandle.close();
+    }
+}
+export async function validateEventV3SupportPack(manifestPath, limits = {}) {
+    const manifest = await readEventV3SupportPackManifest(manifestPath, limits);
+    const records = [];
+    for await (const record of streamEventV3SupportPackRecordsForManifest(manifestPath, manifest, limits)) {
+        records.push(record);
+    }
+    return { manifest, records };
+}
+/** Verify the complete pack while retaining only one decoded source record at a time. */
+export async function verifyEventV3SupportPack(manifestPath, limits = {}) {
+    const manifest = await readEventV3SupportPackManifest(manifestPath, limits);
+    let entries = 0;
+    let bytes = 0;
+    for await (const record of streamEventV3SupportPackRecordsForManifest(manifestPath, manifest, limits)) {
+        entries += 1;
+        bytes += record.bytes;
+    }
+    return { manifest, entries, uncompressed_bytes: bytes };
+}
+/** Unpack only into a destination that does not yet exist; never overlay an authority. */
+export async function unpackEventV3SupportPack(manifestPath, destination, limits = {}) {
+    const target = resolve(destination);
+    try {
+        await lstat(target);
+        throw new Error("event_v3_support_unpack_destination_exists");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await mkdir(target, { recursive: false, mode: 0o700 });
+    let files = 0;
+    let bytes = 0;
+    try {
+        for await (const record of streamEventV3SupportPackRecords(manifestPath, limits)) {
+            const path = resolve(target, ...record.path.split("/"));
+            if (relative(target, path).startsWith(".."))
+                throw new Error("event_v3_support_unpack_path_escape");
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            await writeFile(path, record.content, { flag: "wx", mode: 0o600 });
+            files += 1;
+            bytes += record.bytes;
+        }
+        return { files, bytes, destination: target };
+    }
+    catch (error) {
+        await rm(target, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function hashHandle(path, handle) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path, { fd: handle.fd, autoClose: false, start: 0 });
+    for await (const current of stream)
+        hash.update(current);
+    return `sha256:${hash.digest("hex")}`;
+}
+async function realDirectory(path) {
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("event_v3_support_pack_root_invalid");
+    return realpath(path);
+}
+async function assertCanonicalSingleGzipMember(path, handle, payloadBytes, maximumDecompressedBytes) {
+    if (payloadBytes < 18)
+        throw new Error("event_v3_support_gzip_truncated");
+    const header = Buffer.alloc(10);
+    const read = await handle.read(header, 0, header.length, 0);
+    if (read.bytesRead !== 10 ||
+        header[0] !== 0x1f ||
+        header[1] !== 0x8b ||
+        header[2] !== 0x08 ||
+        header[3] !== 0x00 ||
+        !header.subarray(4, 8).equals(Buffer.alloc(4))) {
+        throw new Error("event_v3_support_gzip_header_noncanonical");
+    }
+    const inflate = createInflateRaw();
+    createReadStream(path, { fd: handle.fd, autoClose: false, start: 10 }).pipe(inflate);
+    let decompressed = 0;
+    for await (const current of inflate) {
+        decompressed += current.length;
+        if (decompressed > maximumDecompressedBytes) {
+            inflate.destroy();
+            throw new Error("event_v3_support_decompression_bound_exceeded");
+        }
+    }
+    if (10 + inflate.bytesWritten + 8 !== payloadBytes) {
+        throw new Error("event_v3_support_gzip_trailing_data");
+    }
+}
+async function openStableRegularFile(path, containmentRoot, kind) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink()) {
+        throw new Error(`event_v3_support_${kind}_not_regular`);
+    }
+    const beforeReal = await realpath(path);
+    if (containmentRoot)
+        assertContained(containmentRoot, beforeReal);
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = await handle.stat();
+        const after = await lstat(path);
+        const afterReal = await realpath(path);
+        if (!opened.isFile() ||
+            !after.isFile() ||
+            after.isSymbolicLink() ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino ||
+            opened.dev !== after.dev ||
+            opened.ino !== after.ino ||
+            beforeReal !== afterReal) {
+            throw new Error(`event_v3_support_${kind}_changed_during_open`);
+        }
+        if (containmentRoot)
+            assertContained(containmentRoot, afterReal);
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+function assertContained(root, candidate) {
+    const path = relative(root, candidate);
+    if (path === "" ||
+        (path !== ".." &&
+            !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+            !isAbsolute(path)))
+        return;
+    throw new Error("event_v3_support_payload_outside_pack");
+}

package/dist/core/events/v3/support-storage/pack-writer.d.ts

@@ -0,0 +1,30 @@
+import { type EventV3SupportFamily, type EventV3SupportPackManifest, type EventV3SupportVerificationMode } from "./pack-contract.js";
+export interface EventV3SupportPackSource {
+    relative_path: string;
+    family: EventV3SupportFamily;
+    recorded_at?: string;
+    diagnostic_category?: string;
+    diagnostic_reason?: string;
+    expected_bytes?: number;
+    expected_digest?: `sha256:${string}`;
+}
+export interface WriteEventV3SupportPackInput {
+    authority_root: string;
+    output_directory: string;
+    root_id: string;
+    genesis_id: string;
+    verification_mode: EventV3SupportVerificationMode;
+    source_authority_digest?: `sha256:${string}`;
+    sources: EventV3SupportPackSource[];
+    minimum_harnery_version: string;
+    created_at: string;
+    fault?: (boundary: "after_source_identity_before_open", path: string) => void;
+}
+export interface WrittenEventV3SupportPack {
+    manifest: EventV3SupportPackManifest;
+    manifest_path: string;
+    payload_path: string;
+}
+/** Write a deterministic gzip-NDJSON support pack without buffering source files or the pack. */
+export declare function writeEventV3SupportPack(input: WriteEventV3SupportPackInput): Promise<WrittenEventV3SupportPack>;
+//# sourceMappingURL=pack-writer.d.ts.map

package/dist/core/events/v3/support-storage/pack-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-writer.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/pack-writer.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,EAIpC,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,UAAU,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,8BAA8B,CAAC;IAClD,uBAAuB,CAAC,EAAE,UAAU,MAAM,EAAE,CAAC;IAC7C,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,mCAAmC,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/E;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD,iGAAiG;AACjG,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CA2GpC"}

package/dist/core/events/v3/support-storage/pack-writer.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { canonicalJsonV3 } from "../canonical.js";
+import { EVENT_V3_SUPPORT_FAMILIES, logicalEntriesDigestV3, normalizeEventV3SupportPath, validateEventV3SupportPackManifest, } from "./pack-contract.js";
+/** Write a deterministic gzip-NDJSON support pack without buffering source files or the pack. */
+export async function writeEventV3SupportPack(input) {
+    if (input.sources.length === 0)
+        throw new Error("event_v3_support_pack_empty");
+    const authorityRoot = resolve(input.authority_root);
+    const authorityReal = await realDirectory(authorityRoot, "event_v3_support_authority_invalid");
+    const inspected = [];
+    for (const source of [...input.sources].sort((left, right) => left.relative_path.localeCompare(right.relative_path))) {
+        const relativePath = normalizeEventV3SupportPath(source.relative_path);
+        if (inspected.at(-1)?.path === relativePath)
+            throw new Error("event_v3_support_duplicate_path");
+        const absolutePath = resolve(authorityRoot, ...relativePath.split("/"));
+        const details = await inspectRegularFile(absolutePath, authorityReal, input.fault);
+        if ((source.expected_bytes !== undefined && source.expected_bytes !== details.bytes) ||
+            (source.expected_digest !== undefined && source.expected_digest !== details.digest)) {
+            throw new Error("event_v3_support_source_planned_mismatch");
+        }
+        inspected.push({
+            ...source,
+            relative_path: relativePath,
+            path: relativePath,
+            absolute_path: absolutePath,
+            ...details,
+        });
+    }
+    const logicalEntries = inspected.map(({ path, bytes, digest }) => ({ path, bytes, digest }));
+    const logicalDigest = logicalEntriesDigestV3(logicalEntries);
+    const packId = `vsp_${createHash("sha256")
+        .update(canonicalJsonV3({
+        root_id: input.root_id,
+        genesis_id: input.genesis_id,
+        verification_mode: input.verification_mode,
+        entries: logicalEntries,
+    }))
+        .digest("hex")
+        .slice(0, 32)}`;
+    const outputDirectory = resolve(input.output_directory);
+    await mkdir(outputDirectory, { recursive: true, mode: 0o700 });
+    await chmod(outputDirectory, 0o700);
+    const payloadName = `${packId}.ndjson.gz`;
+    const payloadPath = join(outputDirectory, payloadName);
+    const manifestPath = join(outputDirectory, `${packId}.manifest.json`);
+    const payloadPartial = `${payloadPath}.partial`;
+    const manifestPartial = `${manifestPath}.partial`;
+    await rejectExisting([payloadPath, manifestPath, payloadPartial, manifestPartial]);
+    try {
+        await streamPayload(inspected, payloadPartial, authorityReal);
+        await chmod(payloadPartial, 0o600);
+        await rename(payloadPartial, payloadPath);
+        const payload = await inspectRegularFile(payloadPath);
+        const manifest = validateEventV3SupportPackManifest({
+            format: "harnery-event-v3-support-pack",
+            format_version: 1,
+            pack_id: packId,
+            authority: {
+                root_id: input.root_id,
+                genesis_id: input.genesis_id,
+                verification_mode: input.verification_mode,
+                ...(input.source_authority_digest
+                    ? { source_authority_digest: input.source_authority_digest }
+                    : {}),
+                source_files_digest: logicalDigest,
+            },
+            scope: scopeFor(inspected),
+            entries: {
+                count: inspected.length,
+                uncompressed_bytes: inspected.reduce((sum, entry) => sum + entry.bytes, 0),
+                logical_entries_digest: logicalDigest,
+                by_family: rollupFamilies(inspected),
+                by_diagnostic_category: rollupStrings(inspected, "diagnostic_category"),
+                by_diagnostic_reason: rollupStrings(inspected, "diagnostic_reason"),
+            },
+            payload: {
+                algorithm: "gzip",
+                path: payloadName,
+                bytes: payload.bytes,
+                digest: payload.digest,
+            },
+            minimum_harnery_version: input.minimum_harnery_version,
+            created_at: input.created_at,
+        });
+        const handle = await open(manifestPartial, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        try {
+            await handle.writeFile(`${canonicalJsonV3(manifest)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(manifestPartial, manifestPath);
+        return { manifest, manifest_path: manifestPath, payload_path: payloadPath };
+    }
+    catch (error) {
+        await rm(payloadPartial, { force: true });
+        await rm(manifestPartial, { force: true });
+        await rm(payloadPath, { force: true });
+        await rm(manifestPath, { force: true });
+        throw error;
+    }
+}
+async function streamPayload(entries, destination, authorityReal) {
+    const gzip = createGzip({ level: 9 });
+    const output = createWriteStream(destination, { flags: "wx", mode: 0o600 });
+    const completed = pipeline(gzip, output);
+    try {
+        for (const entry of entries) {
+            await writeChunk(gzip, `{"path":${JSON.stringify(entry.path)},"bytes":${entry.bytes},"digest":${JSON.stringify(entry.digest)},"content_base64":"`);
+            const handle = await openStableRegularFile(entry.absolute_path, authorityReal);
+            try {
+                const hash = createHash("sha256");
+                let bytes = 0;
+                let carry = Buffer.alloc(0);
+                const stream = createReadStream(entry.absolute_path, {
+                    fd: handle.fd,
+                    autoClose: false,
+                    start: 0,
+                    highWaterMark: 64 * 1024,
+                });
+                for await (const current of stream) {
+                    const chunk = current;
+                    bytes += chunk.length;
+                    hash.update(chunk);
+                    const combined = carry.length === 0 ? chunk : Buffer.concat([carry, chunk]);
+                    const complete = combined.length - (combined.length % 3);
+                    if (complete > 0)
+                        await writeChunk(gzip, combined.subarray(0, complete).toString("base64"));
+                    carry = combined.subarray(complete);
+                }
+                if (carry.length > 0)
+                    await writeChunk(gzip, carry.toString("base64"));
+                const digest = `sha256:${hash.digest("hex")}`;
+                if (bytes !== entry.bytes || digest !== entry.digest) {
+                    throw new Error("event_v3_support_source_changed_during_pack");
+                }
+            }
+            finally {
+                await handle.close();
+            }
+            await writeChunk(gzip, `"}\n`);
+        }
+        gzip.end();
+        await completed;
+    }
+    catch (error) {
+        gzip.destroy(error);
+        await completed.catch(() => undefined);
+        throw error;
+    }
+}
+async function inspectRegularFile(path, containmentRoot, fault) {
+    const handle = await openStableRegularFile(path, containmentRoot, fault);
+    try {
+        const hash = createHash("sha256");
+        let bytes = 0;
+        const stream = createReadStream(path, { fd: handle.fd, autoClose: false, start: 0 });
+        for await (const current of stream) {
+            const chunk = current;
+            bytes += chunk.length;
+            hash.update(chunk);
+        }
+        return { bytes, digest: `sha256:${hash.digest("hex")}` };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function openStableRegularFile(path, containmentRoot, fault) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink()) {
+        throw new Error("event_v3_support_source_not_regular");
+    }
+    const beforeReal = await realpath(path);
+    if (containmentRoot)
+        assertContained(containmentRoot, beforeReal);
+    fault?.("after_source_identity_before_open", path);
+    const handle = await open(path, constants.O_RDONLY | noFollow());
+    try {
+        const opened = await handle.stat();
+        const after = await lstat(path);
+        const afterReal = await realpath(path);
+        if (!opened.isFile() ||
+            !after.isFile() ||
+            after.isSymbolicLink() ||
+            !sameIdentity(before, opened) ||
+            !sameIdentity(opened, after) ||
+            beforeReal !== afterReal) {
+            throw new Error("event_v3_support_source_changed_during_open");
+        }
+        if (containmentRoot)
+            assertContained(containmentRoot, afterReal);
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function realDirectory(path, code) {
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(code);
+    return realpath(path);
+}
+function assertContained(root, candidate) {
+    const path = relative(root, candidate);
+    if (path === "" ||
+        (path !== ".." &&
+            !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+            !isAbsolute(path)))
+        return;
+    throw new Error("event_v3_support_source_outside_authority");
+}
+function noFollow() {
+    return constants.O_NOFOLLOW ?? 0;
+}
+async function rejectExisting(paths) {
+    for (const path of paths) {
+        try {
+            await lstat(path);
+            throw new Error(`event_v3_support_output_exists:${basename(path)}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+async function writeChunk(stream, value) {
+    if (!stream.write(value, "utf8"))
+        await once(stream, "drain");
+}
+function scopeFor(entries) {
+    const timestamps = entries
+        .flatMap((entry) => (entry.recorded_at ? [entry.recorded_at] : []))
+        .sort();
+    return {
+        families: [...new Set(entries.map(({ family }) => family))].sort(),
+        minimum_recorded_at: timestamps[0] ?? null,
+        maximum_recorded_at: timestamps.at(-1) ?? null,
+    };
+}
+function rollupFamilies(entries) {
+    const result = Object.fromEntries(EVENT_V3_SUPPORT_FAMILIES.map((family) => [family, 0]));
+    for (const entry of entries)
+        result[entry.family] += 1;
+    return result;
+}
+function rollupStrings(entries, key) {
+    const result = {};
+    for (const entry of entries) {
+        const value = entry[key];
+        if (value)
+            result[value] = (result[value] ?? 0) + 1;
+    }
+    return Object.fromEntries(Object.entries(result).sort(([left], [right]) => left.localeCompare(right)));
+}

package/dist/core/events/v3/support-storage/recovery.d.ts

@@ -0,0 +1,15 @@
+export interface VerifyEventV3RecoveryBoundArchiveInput {
+    authority_root: string;
+    expected_authority_digest: `sha256:${string}`;
+    expected_archive_directory?: string;
+    archive_directory?: string;
+    recovery_receipt_id: string;
+}
+/** Fail closed unless a recovery receipt still binds one complete logical authority. */
+export declare function verifyEventV3RecoveryBoundArchive(input: VerifyEventV3RecoveryBoundArchiveInput): Promise<{
+    recovery_receipt_id: string;
+    authority_digest: `sha256:${string}`;
+    logical_files: number;
+    packed_entries: number;
+}>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/core/events/v3/support-storage/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/recovery.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,sCAAsC;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB,EAAE,UAAU,MAAM,EAAE,CAAC;IAC9C,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,wFAAwF;AACxF,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,sCAAsC,GAC5C,OAAO,CAAC;IACT,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,UAAU,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC,CAqBD"}

package/dist/core/events/v3/support-storage/recovery.js

@@ -0,0 +1,22 @@
+import { digestEventV3LogicalAuthority, iterateEventV3LogicalAuthority, } from "./logical-authority.js";
+/** Fail closed unless a recovery receipt still binds one complete logical authority. */
+export async function verifyEventV3RecoveryBoundArchive(input) {
+    if (input.expected_archive_directory !== undefined &&
+        input.archive_directory !== input.expected_archive_directory) {
+        throw new Error("event_v3_support_recovery_archive_binding_mismatch");
+    }
+    const view = await iterateEventV3LogicalAuthority(input.authority_root);
+    if (view.quarantined_packs.length > 0) {
+        throw new Error("event_v3_support_recovery_pack_quarantined");
+    }
+    const digest = await digestEventV3LogicalAuthority(input.authority_root);
+    if (digest !== input.expected_authority_digest) {
+        throw new Error("event_v3_support_recovery_authority_digest_mismatch");
+    }
+    return {
+        recovery_receipt_id: input.recovery_receipt_id,
+        authority_digest: digest,
+        logical_files: view.entries.length,
+        packed_entries: view.packed_entries,
+    };
+}