harnery 0.35.0 → 0.36.0

package/src/core/events/v3/support-storage/pack-contract.ts

@@ -0,0 +1,337 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { canonicalJsonV3 } from "../canonical.ts";
+
+export const EVENT_V3_SUPPORT_PACK_FORMAT = "harnery-event-v3-support-pack" as const;
+export const EVENT_V3_SUPPORT_PACK_VERSION = 1 as const;
+
+export const EVENT_V3_SUPPORT_FAMILIES = [
+  "diagnostic",
+  "session-tee",
+  "authority-ready",
+  "authority-committed",
+  "authority-residue",
+] as const;
+
+export type EventV3SupportFamily = (typeof EVENT_V3_SUPPORT_FAMILIES)[number];
+export type EventV3SupportVerificationMode = "archive-logical-authority" | "active-frozen-files";
+
+export interface EventV3SupportPackRecord {
+  path: string;
+  bytes: number;
+  digest: `sha256:${string}`;
+  content_base64: string;
+}
+
+export interface EventV3SupportPackManifest {
+  format: typeof EVENT_V3_SUPPORT_PACK_FORMAT;
+  format_version: typeof EVENT_V3_SUPPORT_PACK_VERSION;
+  pack_id: `vsp_${string}`;
+  authority: {
+    root_id: string;
+    genesis_id: string;
+    verification_mode: EventV3SupportVerificationMode;
+    source_authority_digest?: `sha256:${string}`;
+    source_files_digest: `sha256:${string}`;
+  };
+  scope: {
+    families: EventV3SupportFamily[];
+    minimum_recorded_at: string | null;
+    maximum_recorded_at: string | null;
+  };
+  entries: {
+    count: number;
+    uncompressed_bytes: number;
+    logical_entries_digest: `sha256:${string}`;
+    by_family: Record<EventV3SupportFamily, number>;
+    by_diagnostic_category: Record<string, number>;
+    by_diagnostic_reason: Record<string, number>;
+  };
+  payload: {
+    algorithm: "gzip";
+    path: string;
+    bytes: number;
+    digest: `sha256:${string}`;
+  };
+  minimum_harnery_version: string;
+  created_at: string;
+}
+
+export interface EventV3LogicalAuthorityEntry {
+  path: string;
+  bytes: number;
+  digest: `sha256:${string}`;
+}
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const PACK_ID = /^vsp_[0-9a-f]{32}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export function normalizeEventV3SupportPath(value: string): string {
+  if (
+    value.length === 0 ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    value.startsWith("/") ||
+    /^[A-Za-z]:/.test(value)
+  ) {
+    throw new Error("event_v3_support_path_is_unsafe");
+  }
+  const normalized = posix.normalize(value);
+  if (normalized !== value || value === "." || value.split("/").includes("..")) {
+    throw new Error("event_v3_support_path_is_noncanonical");
+  }
+  if (value === "support-packs" || value.startsWith("support-packs/")) {
+    throw new Error("event_v3_support_path_uses_reserved_subtree");
+  }
+  return value;
+}
+
+export function logicalEntriesDigestV3(
+  entries: readonly EventV3LogicalAuthorityEntry[],
+): `sha256:${string}` {
+  const sorted = [...entries].sort((left, right) => left.path.localeCompare(right.path));
+  return `sha256:${createHash("sha256").update(canonicalJsonV3(sorted)).digest("hex")}`;
+}
+
+export function validateEventV3SupportPackRecord(value: unknown): EventV3SupportPackRecord {
+  const record = object(value, "event_v3_support_record_invalid");
+  exactKeys(record, ["path", "bytes", "digest", "content_base64"]);
+  const path = normalizeEventV3SupportPath(string(record.path));
+  const bytes = nonnegativeInteger(record.bytes);
+  const digest = sha256(record.digest);
+  const content = string(record.content_base64);
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) {
+    throw new Error("event_v3_support_record_base64_invalid");
+  }
+  return { path, bytes, digest, content_base64: content };
+}
+
+export function validateEventV3SupportPackManifest(value: unknown): EventV3SupportPackManifest {
+  const manifest = object(value, "event_v3_support_manifest_invalid");
+  exactKeys(manifest, [
+    "format",
+    "format_version",
+    "pack_id",
+    "authority",
+    "scope",
+    "entries",
+    "payload",
+    "minimum_harnery_version",
+    "created_at",
+  ]);
+  if (manifest.format !== EVENT_V3_SUPPORT_PACK_FORMAT || manifest.format_version !== 1) {
+    throw new Error("event_v3_support_manifest_version_unsupported");
+  }
+  const packId = string(manifest.pack_id);
+  if (!PACK_ID.test(packId)) throw new Error("event_v3_support_pack_id_invalid");
+
+  const authority = object(manifest.authority, "event_v3_support_authority_invalid");
+  const authorityKeys = ["root_id", "genesis_id", "verification_mode", "source_files_digest"];
+  if (authority.source_authority_digest !== undefined)
+    authorityKeys.push("source_authority_digest");
+  exactKeys(authority, authorityKeys);
+  const verificationMode = string(authority.verification_mode);
+  if (
+    verificationMode !== "archive-logical-authority" &&
+    verificationMode !== "active-frozen-files"
+  ) {
+    throw new Error("event_v3_support_verification_mode_invalid");
+  }
+  const sourceAuthorityDigest = optionalSha256(authority.source_authority_digest);
+  if (verificationMode === "archive-logical-authority" && !sourceAuthorityDigest) {
+    throw new Error("event_v3_support_archive_digest_required");
+  }
+  if (verificationMode === "active-frozen-files" && sourceAuthorityDigest) {
+    throw new Error("event_v3_support_active_authority_digest_forbidden");
+  }
+
+  const scope = object(manifest.scope, "event_v3_support_scope_invalid");
+  exactKeys(scope, ["families", "minimum_recorded_at", "maximum_recorded_at"]);
+  if (!Array.isArray(scope.families) || scope.families.length === 0) {
+    throw new Error("event_v3_support_scope_families_invalid");
+  }
+  const families = [...new Set(scope.families.map(family))].sort();
+  if (families.length !== scope.families.length) {
+    throw new Error("event_v3_support_scope_family_duplicate");
+  }
+  const minimumRecordedAt = nullableTimestamp(scope.minimum_recorded_at);
+  const maximumRecordedAt = nullableTimestamp(scope.maximum_recorded_at);
+  if ((minimumRecordedAt === null) !== (maximumRecordedAt === null)) {
+    throw new Error("event_v3_support_scope_time_range_incomplete");
+  }
+  if (minimumRecordedAt && maximumRecordedAt && minimumRecordedAt > maximumRecordedAt) {
+    throw new Error("event_v3_support_scope_time_range_invalid");
+  }
+
+  const entries = object(manifest.entries, "event_v3_support_entries_invalid");
+  exactKeys(entries, [
+    "count",
+    "uncompressed_bytes",
+    "logical_entries_digest",
+    "by_family",
+    "by_diagnostic_category",
+    "by_diagnostic_reason",
+  ]);
+  const count = nonnegativeInteger(entries.count);
+  if (count === 0) throw new Error("event_v3_support_pack_empty");
+  const byFamily = familyRollup(entries.by_family);
+  if (Object.values(byFamily).reduce((sum, current) => sum + current, 0) !== count) {
+    throw new Error("event_v3_support_family_rollup_mismatch");
+  }
+  for (const key of EVENT_V3_SUPPORT_FAMILIES) {
+    if (byFamily[key] > 0 && !families.includes(key)) {
+      throw new Error("event_v3_support_scope_rollup_mismatch");
+    }
+  }
+
+  const payload = object(manifest.payload, "event_v3_support_payload_invalid");
+  exactKeys(payload, ["algorithm", "path", "bytes", "digest"]);
+  if (payload.algorithm !== "gzip") throw new Error("event_v3_support_algorithm_unsupported");
+  const payloadPath = string(payload.path);
+  if (payloadPath !== `${packId}.ndjson.gz`) {
+    throw new Error("event_v3_support_payload_path_mismatch");
+  }
+  const minimumVersion = string(manifest.minimum_harnery_version);
+  if (!VERSION.test(minimumVersion)) throw new Error("event_v3_support_minimum_version_invalid");
+
+  return {
+    format: EVENT_V3_SUPPORT_PACK_FORMAT,
+    format_version: 1,
+    pack_id: packId as `vsp_${string}`,
+    authority: {
+      root_id: nonemptyString(authority.root_id),
+      genesis_id: nonemptyString(authority.genesis_id),
+      verification_mode: verificationMode,
+      ...(sourceAuthorityDigest ? { source_authority_digest: sourceAuthorityDigest } : {}),
+      source_files_digest: sha256(authority.source_files_digest),
+    },
+    scope: {
+      families,
+      minimum_recorded_at: minimumRecordedAt,
+      maximum_recorded_at: maximumRecordedAt,
+    },
+    entries: {
+      count,
+      uncompressed_bytes: nonnegativeInteger(entries.uncompressed_bytes),
+      logical_entries_digest: sha256(entries.logical_entries_digest),
+      by_family: byFamily,
+      by_diagnostic_category: stringRollup(entries.by_diagnostic_category),
+      by_diagnostic_reason: stringRollup(entries.by_diagnostic_reason),
+    },
+    payload: {
+      algorithm: "gzip",
+      path: payloadPath,
+      bytes: nonnegativeInteger(payload.bytes),
+      digest: sha256(payload.digest),
+    },
+    minimum_harnery_version: minimumVersion,
+    created_at: timestamp(manifest.created_at),
+  };
+}
+
+export function assertEventV3SupportPackAuthority(
+  manifest: EventV3SupportPackManifest,
+  expected: {
+    root_id: string;
+    genesis_id: string;
+    verification_mode?: EventV3SupportVerificationMode;
+  },
+): void {
+  if (manifest.authority.root_id !== expected.root_id) {
+    throw new Error("event_v3_support_pack_wrong_root_authority");
+  }
+  if (manifest.authority.genesis_id !== expected.genesis_id) {
+    throw new Error("event_v3_support_pack_wrong_genesis_authority");
+  }
+  if (
+    expected.verification_mode !== undefined &&
+    manifest.authority.verification_mode !== expected.verification_mode
+  ) {
+    throw new Error("event_v3_support_pack_wrong_verification_mode");
+  }
+}
+
+function object(value: unknown, code: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(code);
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(value: Record<string, unknown>, expected: string[]): void {
+  if (Object.keys(value).sort().join("\0") !== [...expected].sort().join("\0")) {
+    throw new Error("event_v3_support_schema_unknown_field");
+  }
+}
+
+function string(value: unknown): string {
+  if (typeof value !== "string") throw new Error("event_v3_support_string_invalid");
+  return value;
+}
+
+function nonemptyString(value: unknown): string {
+  const result = string(value);
+  if (result.length === 0 || result.length > 256) throw new Error("event_v3_support_id_invalid");
+  return result;
+}
+
+function nonnegativeInteger(value: unknown): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error("event_v3_support_integer_invalid");
+  }
+  return value as number;
+}
+
+function sha256(value: unknown): `sha256:${string}` {
+  const result = string(value);
+  if (!DIGEST.test(result)) throw new Error("event_v3_support_digest_invalid");
+  return result as `sha256:${string}`;
+}
+
+function optionalSha256(value: unknown): `sha256:${string}` | undefined {
+  return value === undefined ? undefined : sha256(value);
+}
+
+function family(value: unknown): EventV3SupportFamily {
+  const result = string(value);
+  if (!(EVENT_V3_SUPPORT_FAMILIES as readonly string[]).includes(result)) {
+    throw new Error("event_v3_support_family_unknown");
+  }
+  return result as EventV3SupportFamily;
+}
+
+function timestamp(value: unknown): string {
+  const result = string(value);
+  if (
+    !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(result) ||
+    !Number.isFinite(Date.parse(result))
+  ) {
+    throw new Error("event_v3_support_timestamp_invalid");
+  }
+  return result;
+}
+
+function nullableTimestamp(value: unknown): string | null {
+  return value === null ? null : timestamp(value);
+}
+
+function familyRollup(value: unknown): Record<EventV3SupportFamily, number> {
+  const rollup = object(value, "event_v3_support_family_rollup_invalid");
+  exactKeys(rollup, [...EVENT_V3_SUPPORT_FAMILIES]);
+  return Object.fromEntries(
+    EVENT_V3_SUPPORT_FAMILIES.map((key) => [key, nonnegativeInteger(rollup[key])]),
+  ) as Record<EventV3SupportFamily, number>;
+}
+
+function stringRollup(value: unknown): Record<string, number> {
+  const rollup = object(value, "event_v3_support_rollup_invalid");
+  const result: Record<string, number> = {};
+  for (const [key, current] of Object.entries(rollup).sort(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
+    if (!/^[a-z0-9][a-z0-9_.-]{0,127}$/.test(key)) {
+      throw new Error("event_v3_support_rollup_key_invalid");
+    }
+    result[key] = nonnegativeInteger(current);
+  }
+  return result;
+}

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

@@ -0,0 +1,346 @@
+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 {
+  type EventV3LogicalAuthorityEntry,
+  type EventV3SupportPackManifest,
+  type EventV3SupportPackRecord,
+  logicalEntriesDigestV3,
+  validateEventV3SupportPackManifest,
+  validateEventV3SupportPackRecord,
+} from "./pack-contract.ts";
+
+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;
+}
+
+const DEFAULT_LIMITS: Required<Omit<EventV3SupportPackLimits, "fault">> = {
+  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: string,
+  limits: EventV3SupportPackLimits = {},
+): Promise<EventV3SupportPackManifest> {
+  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")) as unknown;
+    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: string,
+  limits: EventV3SupportPackLimits = {},
+): AsyncGenerator<DecodedEventV3SupportPackRecord> {
+  const manifest = await readEventV3SupportPackManifest(manifestPath, limits);
+  yield* streamEventV3SupportPackRecordsForManifest(manifestPath, manifest, limits);
+}
+
+async function* streamEventV3SupportPackRecordsForManifest(
+  manifestPath: string,
+  manifest: EventV3SupportPackManifest,
+  limits: EventV3SupportPackLimits,
+): AsyncGenerator<DecodedEventV3SupportPackRecord> {
+  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: string | undefined;
+    const entries: EventV3LogicalAuthorityEntry[] = [];
+    const seen = new Set<string>();
+
+    for await (const current of gunzip) {
+      const chunk = current as Buffer;
+      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) as unknown);
+        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: string,
+  limits: EventV3SupportPackLimits = {},
+): Promise<ValidatedEventV3SupportPack> {
+  const manifest = await readEventV3SupportPackManifest(manifestPath, limits);
+  const records: DecodedEventV3SupportPackRecord[] = [];
+  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: string,
+  limits: EventV3SupportPackLimits = {},
+): Promise<VerifiedEventV3SupportPack> {
+  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: string,
+  destination: string,
+  limits: EventV3SupportPackLimits = {},
+): Promise<{ files: number; bytes: number; destination: string }> {
+  const target = resolve(destination);
+  try {
+    await lstat(target);
+    throw new Error("event_v3_support_unpack_destination_exists");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).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: string,
+  handle: Awaited<ReturnType<typeof open>>,
+): Promise<`sha256:${string}`> {
+  const hash = createHash("sha256");
+  const stream = createReadStream(path, { fd: handle.fd, autoClose: false, start: 0 });
+  for await (const current of stream) hash.update(current as Buffer);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+async function realDirectory(path: string): Promise<string> {
+  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: string,
+  handle: Awaited<ReturnType<typeof open>>,
+  payloadBytes: number,
+  maximumDecompressedBytes: number,
+): Promise<void> {
+  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 as Buffer).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: string,
+  containmentRoot: string | undefined,
+  kind: "manifest" | "payload",
+) {
+  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: string, candidate: string): void {
+  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");
+}