@taprootio/docs-artifact 1.0.1 → 1.1.1

package/src/node.js

@@ -511,3 +511,5 @@ export async function validateArtifactDirectory(rootDirectory, options = {}) {
   if (context.errors.length > 0) return context.finish(undefined);
   return validateArtifact(manifestResult.value, entries, stableValidationOptions);
 }
+
+export const validateManagedArtifactDirectory = validateArtifactDirectory;

package/src/prebuilt-archive.js

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+
+import { PREBUILT_ARCHIVE_FORMAT, PREBUILT_LIMITS, PREBUILT_MANIFEST_FILE_NAME } from "./prebuilt-constants.js";
+import { serializePrebuiltManifest } from "./prebuilt-manifest-validator.js";
+
+export { DocsArtifactValidationError } from "./errors.js";
+
+const TAR_BLOCK_BYTES = 512;
+const DEFLATE_STORED_BLOCK_BYTES = 65_535;
+const GZIP_HEADER = Uint8Array.from([0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff]);
+const GZIP_TRAILER_BYTES = 8;
+const CRC_TABLE = new Uint32Array(256);
+for (let index = 0; index < CRC_TABLE.length; index += 1) {
+  let value = index;
+  for (let bit = 0; bit < 8; bit += 1) value = (value & 1) === 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+  CRC_TABLE[index] = value >>> 0;
+}
+
+const MAXIMUM_TAR_BYTES = PREBUILT_LIMITS.manifestBytes
+  + PREBUILT_LIMITS.artifactBytes
+  + ((PREBUILT_LIMITS.files + 1) * ((TAR_BLOCK_BYTES * 2) - 1))
+  + (TAR_BLOCK_BYTES * 2);
+
+export class PrebuiltArchiveError extends Error {
+  constructor(code, message, field) {
+    super(message);
+    this.name = "PrebuiltArchiveError";
+    this.code = code;
+    if (field !== undefined) this.field = field;
+  }
+}
+
+function archiveError(code, message, field) {
+  throw new PrebuiltArchiveError(code, message, field);
+}
+
+function writeOctal(header, offset, length, value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    archiveError("archive.numeric_overflow", "A POSIX USTAR numeric field is outside the supported integer range.");
+  }
+  const text = value.toString(8);
+  if (text.length > length - 1) {
+    archiveError("archive.numeric_overflow", "A POSIX USTAR numeric field exceeds its fixed octal envelope.");
+  }
+  header.fill(0x30, offset, offset + length - 1);
+  header.write(text, offset + length - 1 - text.length, text.length, "ascii");
+  header[offset + length - 1] = 0;
+}
+
+function splitUstarPath(entryPath) {
+  if (typeof entryPath !== "string" || !/^[\x20-\x7e]+$/u.test(entryPath)) {
+    archiveError("archive.path_unrepresentable", "Archive paths must be printable ASCII POSIX USTAR text.", entryPath);
+  }
+  if (entryPath.length <= 100) return { name: entryPath, prefix: "" };
+  for (let offset = entryPath.lastIndexOf("/"); offset > 0; offset = entryPath.lastIndexOf("/", offset - 1)) {
+    const prefix = entryPath.slice(0, offset);
+    const name = entryPath.slice(offset + 1);
+    if (prefix.length <= 155 && name.length <= 100) return { name, prefix };
+  }
+  archiveError(
+    "archive.path_unrepresentable",
+    `Archive path '${entryPath}' does not fit the POSIX USTAR name and prefix fields.`,
+    entryPath,
+  );
+}
+
+function ustarHeader(entryPath, byteLength) {
+  const { name, prefix } = splitUstarPath(entryPath);
+  const header = Buffer.alloc(TAR_BLOCK_BYTES);
+  header.write(name, 0, name.length, "ascii");
+  writeOctal(header, 100, 8, 0o644);
+  writeOctal(header, 108, 8, 0);
+  writeOctal(header, 116, 8, 0);
+  writeOctal(header, 124, 12, byteLength);
+  writeOctal(header, 136, 12, 0);
+  header.fill(0x20, 148, 156);
+  header[156] = 0x30;
+  header.write("ustar\0", 257, 6, "ascii");
+  header.write("00", 263, 2, "ascii");
+  writeOctal(header, 329, 8, 0);
+  writeOctal(header, 337, 8, 0);
+  if (prefix) header.write(prefix, 345, prefix.length, "ascii");
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  const checksumText = checksum.toString(8).padStart(6, "0");
+  if (checksumText.length !== 6) {
+    archiveError("archive.checksum_overflow", "A POSIX USTAR header checksum exceeds its fixed octal envelope.");
+  }
+  header.write(checksumText, 148, 6, "ascii");
+  header[154] = 0;
+  header[155] = 0x20;
+  return header;
+}
+
+function roundedTarContentBytes(byteLength) {
+  const remainder = byteLength % TAR_BLOCK_BYTES;
+  return remainder === 0 ? byteLength : byteLength + TAR_BLOCK_BYTES - remainder;
+}
+
+function computeTarLength(entries) {
+  let total = TAR_BLOCK_BYTES * 2;
+  for (const entry of entries) {
+    total += TAR_BLOCK_BYTES + roundedTarContentBytes(entry.content.byteLength);
+    if (!Number.isSafeInteger(total) || total > MAXIMUM_TAR_BYTES) {
+      archiveError("archive.too_large", "The archive exceeds the bounded prebuilt POSIX USTAR envelope.");
+    }
+  }
+  return total;
+}
+
+function gzipLength(tarLength) {
+  const blockCount = Math.ceil(tarLength / DEFLATE_STORED_BLOCK_BYTES);
+  const length = GZIP_HEADER.byteLength + tarLength + (blockCount * 5) + GZIP_TRAILER_BYTES;
+  if (!Number.isSafeInteger(length)) {
+    archiveError("archive.too_large", "The deterministic gzip member exceeds the supported byte range.");
+  }
+  return { blockCount, length };
+}
+
+function storedBlockDataOffset(tarOffset) {
+  const blockIndex = Math.floor(tarOffset / DEFLATE_STORED_BLOCK_BYTES);
+  return GZIP_HEADER.byteLength + tarOffset + (blockIndex * 5) + 5;
+}
+
+function visitTarRange(output, start, byteLength, visitor) {
+  let tarOffset = start;
+  let remaining = byteLength;
+  while (remaining > 0) {
+    const inBlockOffset = tarOffset % DEFLATE_STORED_BLOCK_BYTES;
+    const length = Math.min(remaining, DEFLATE_STORED_BLOCK_BYTES - inBlockOffset);
+    const outputOffset = storedBlockDataOffset(tarOffset);
+    visitor(output.subarray(outputOffset, outputOffset + length));
+    tarOffset += length;
+    remaining -= length;
+  }
+}
+
+function writeTarRange(output, start, bytes) {
+  let sourceOffset = 0;
+  visitTarRange(output, start, bytes.byteLength, (target) => {
+    target.set(bytes.subarray(sourceOffset, sourceOffset + target.byteLength));
+    sourceOffset += target.byteLength;
+  });
+}
+
+function initializeStoredBlocks(output, tarLength, blockCount) {
+  output.set(GZIP_HEADER, 0);
+  for (let blockIndex = 0; blockIndex < blockCount; blockIndex += 1) {
+    const tarOffset = blockIndex * DEFLATE_STORED_BLOCK_BYTES;
+    const length = Math.min(DEFLATE_STORED_BLOCK_BYTES, tarLength - tarOffset);
+    const outputOffset = GZIP_HEADER.byteLength + tarOffset + (blockIndex * 5);
+    output[outputOffset] = blockIndex === blockCount - 1 ? 0x01 : 0x00;
+    output.writeUInt16LE(length, outputOffset + 1);
+    output.writeUInt16LE((~length) & 0xffff, outputOffset + 3);
+  }
+}
+
+function crc32Tar(output, tarLength) {
+  let value = 0xffffffff;
+  visitTarRange(output, 0, tarLength, (bytes) => {
+    for (const byte of bytes) value = CRC_TABLE[(value ^ byte) & 0xff] ^ (value >>> 8);
+  });
+  return (value ^ 0xffffffff) >>> 0;
+}
+
+function sha256TarRange(output, start, byteLength) {
+  const hash = createHash("sha256");
+  visitTarRange(output, start, byteLength, (bytes) => hash.update(bytes));
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function snapshotEntries(snapshot, options) {
+  if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+    archiveError("archive.inventory", "A validated prebuilt artifact snapshot is required.");
+  }
+  const manifestText = serializePrebuiltManifest(snapshot.manifest, options);
+  const manifestBytes = Buffer.from(manifestText, "utf8");
+  const manifest = JSON.parse(manifestText);
+  if (!Array.isArray(snapshot.files) || snapshot.files.length !== manifest.files.length) {
+    archiveError("archive.inventory", "The prebuilt snapshot must contain every declared payload file exactly once.");
+  }
+  const supplied = new Map();
+  for (const entry of snapshot.files) {
+    if (
+      entry === null
+      || typeof entry !== "object"
+      || typeof entry.path !== "string"
+      || !(entry.content instanceof Uint8Array)
+      || supplied.has(entry.path)
+    ) {
+      archiveError("archive.inventory", "The prebuilt snapshot contains an invalid or duplicate payload entry.");
+    }
+    supplied.set(entry.path, entry.content);
+  }
+  const entries = [{ path: PREBUILT_MANIFEST_FILE_NAME, content: manifestBytes }];
+  for (const descriptor of manifest.files) {
+    const content = supplied.get(descriptor.path);
+    if (!content || content.byteLength !== descriptor.bytes) {
+      archiveError(
+        "archive.size_drift",
+        `Payload '${descriptor.path}' does not match its declared byte length.`,
+        descriptor.path,
+      );
+    }
+    splitUstarPath(descriptor.path);
+    entries.push({ path: descriptor.path, content, expectedHash: descriptor.sha256 });
+    supplied.delete(descriptor.path);
+  }
+  if (supplied.size !== 0) {
+    archiveError("archive.inventory", "The prebuilt snapshot contains undeclared payload files.");
+  }
+  return entries;
+}
+
+export function createDeterministicPrebuiltArchive(snapshot, options = {}) {
+  const entries = snapshotEntries(snapshot, options);
+  const tarLength = computeTarLength(entries);
+  const { blockCount, length: outputLength } = gzipLength(tarLength);
+  const output = Buffer.alloc(outputLength);
+  initializeStoredBlocks(output, tarLength, blockCount);
+
+  let tarOffset = 0;
+  for (const entry of entries) {
+    const header = ustarHeader(entry.path, entry.content.byteLength);
+    writeTarRange(output, tarOffset, header);
+    tarOffset += TAR_BLOCK_BYTES;
+    const contentOffset = tarOffset;
+    writeTarRange(output, contentOffset, entry.content);
+    if (entry.expectedHash && sha256TarRange(output, contentOffset, entry.content.byteLength) !== entry.expectedHash) {
+      archiveError("archive.hash_drift", `Payload '${entry.path}' does not match its declared SHA-256.`, entry.path);
+    }
+    tarOffset += roundedTarContentBytes(entry.content.byteLength);
+  }
+  if (tarOffset + (TAR_BLOCK_BYTES * 2) !== tarLength) {
+    archiveError("archive.internal_length", "The deterministic tar length does not match its frozen inventory.");
+  }
+
+  const trailerOffset = outputLength - GZIP_TRAILER_BYTES;
+  output.writeUInt32LE(crc32Tar(output, tarLength), trailerOffset);
+  output.writeUInt32LE(tarLength >>> 0, trailerOffset + 4);
+  const contentHash = `sha256:${createHash("sha256").update(output).digest("hex")}`;
+  return Object.freeze({
+    format: PREBUILT_ARCHIVE_FORMAT,
+    bytes: output,
+    byteLength: output.byteLength,
+    contentHash,
+  });
+}

package/src/prebuilt-artifact-validator.js

@@ -0,0 +1,236 @@
+import { snapshotBinaryInput } from "./binary.js";
+import { DocsArtifactValidationError, ValidationContext } from "./errors.js";
+import { PREBUILT_LIMITS, PREBUILT_TEXT_MEDIA_TYPES } from "./prebuilt-constants.js";
+import { validatePrebuiltManifest } from "./prebuilt-manifest-validator.js";
+import { normalizePrebuiltArtifactPath } from "./prebuilt-path.js";
+
+function inspectStringContent(content, maximumBytes) {
+  let byteLength = 0;
+  for (let offset = 0; offset < content.length;) {
+    const first = content.charCodeAt(offset);
+    if (first >= 0xd800 && first <= 0xdbff) {
+      const second = content.charCodeAt(offset + 1);
+      if (second < 0xdc00 || second > 0xdfff) return { error: "file.invalid_unicode" };
+      byteLength += 4;
+      offset += 2;
+    } else {
+      if (first >= 0xdc00 && first <= 0xdfff) return { error: "file.invalid_unicode" };
+      byteLength += first <= 0x7f ? 1 : first <= 0x7ff ? 2 : 3;
+      offset += 1;
+    }
+    if (byteLength > maximumBytes) return { kind: "string", byteLength };
+  }
+  return { kind: "string", byteLength, content };
+}
+
+function inspectContent(content, remainingArtifactBytes, trustBinarySnapshot) {
+  const maximumBytes = Math.min(PREBUILT_LIMITS.fileBytes, remainingArtifactBytes);
+  if (typeof content === "string") return inspectStringContent(content, maximumBytes);
+  if (trustBinarySnapshot) {
+    if (!(content instanceof Uint8Array)) return undefined;
+    const byteLength = content.byteLength;
+    return byteLength > maximumBytes
+      ? { kind: "too_large", byteLength }
+      : { kind: "bytes", byteLength, bytes: content };
+  }
+  const snapshot = snapshotBinaryInput(content, maximumBytes);
+  if (snapshot.kind === "bytes" || snapshot.kind === "too_large") return snapshot;
+  return undefined;
+}
+
+function materializeContent(content) {
+  if (content.kind === "string") return new TextEncoder().encode(content.content);
+  return content.bytes;
+}
+
+async function sha256(bytes) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${[...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function isUtf8(bytes) {
+  try {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (let offset = 0; offset < bytes.byteLength; offset += 64 * 1024) {
+      decoder.decode(bytes.subarray(offset, Math.min(bytes.byteLength, offset + (64 * 1024))), { stream: true });
+    }
+    decoder.decode();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function validatePrebuiltArtifactContents(manifest, fileEntries, trustBinarySnapshots) {
+  const context = new ValidationContext();
+  const expected = new Map(manifest.files.map((descriptor, index) => [
+    descriptor.path,
+    { descriptor, descriptorPath: `$.files[${index}]` },
+  ]));
+  const seen = new Set();
+  const seenCaseFolded = new Map();
+  const snapshots = new Map();
+  let totalBytes = 0;
+  let entryCount = 0;
+  let stoppedForTotal = false;
+
+  try {
+    if (typeof fileEntries === "string" || fileEntries === null || fileEntries === undefined) {
+      throw new TypeError("File entries must be an object iterable.");
+    }
+    for (const entry of fileEntries) {
+      entryCount += 1;
+      if (entryCount > PREBUILT_LIMITS.files) {
+        context.add(
+          "limit.files",
+          "$files",
+          `Prebuilt artifacts may not contain more than ${PREBUILT_LIMITS.files} payload files.`,
+        );
+        break;
+      }
+      const entryPath = `$files[${entryCount - 1}]`;
+      if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+        context.add("file.invalid_entry", entryPath, "File entries must be objects with path and content.");
+        continue;
+      }
+      const normalized = normalizePrebuiltArtifactPath(entry.path);
+      if (!normalized.ok) {
+        context.add(normalized.code, `${entryPath}.path`, normalized.message);
+        continue;
+      }
+      const folded = normalized.value.toLowerCase();
+      if (seen.has(normalized.value)) {
+        context.add("duplicate.file_entry", `${entryPath}.path`, `File '${normalized.value}' appears more than once.`);
+        continue;
+      }
+      if (seenCaseFolded.has(folded)) {
+        context.add(
+          "duplicate.file_entry_casefold",
+          `${entryPath}.path`,
+          `File '${normalized.value}' collides with '${seenCaseFolded.get(folded)}' after ASCII case-folding.`,
+        );
+        continue;
+      }
+      seen.add(normalized.value);
+      seenCaseFolded.set(folded, normalized.value);
+
+      const expectedFile = expected.get(normalized.value);
+      if (!expectedFile) {
+        context.add(
+          "file.unexpected",
+          `${entryPath}.path`,
+          `File '${normalized.value}' is not declared by the prebuilt manifest.`,
+        );
+      }
+      const content = inspectContent(
+        entry.content,
+        Math.max(0, PREBUILT_LIMITS.artifactBytes - totalBytes),
+        trustBinarySnapshots,
+      );
+      if (!content) {
+        context.add(
+          "file.invalid_content",
+          `${entryPath}.content`,
+          "File content must be a string, Uint8Array, or ArrayBuffer.",
+        );
+        continue;
+      }
+      if (content.error) {
+        context.add(
+          content.error,
+          `${entryPath}.content`,
+          "String file content must contain only well-formed Unicode scalar values.",
+        );
+        continue;
+      }
+      if (content.byteLength > PREBUILT_LIMITS.artifactBytes - totalBytes) {
+        context.add(
+          "limit.artifact_bytes",
+          "$files",
+          `Prebuilt payload bytes may not exceed ${PREBUILT_LIMITS.artifactBytes}.`,
+        );
+        stoppedForTotal = true;
+        break;
+      }
+      totalBytes += content.byteLength;
+      if (content.byteLength > PREBUILT_LIMITS.fileBytes) {
+        context.add(
+          "file.too_large",
+          `${entryPath}.content`,
+          `File '${normalized.value}' exceeds ${PREBUILT_LIMITS.fileBytes} bytes.`,
+        );
+        continue;
+      }
+      if (content.kind === "too_large") {
+        context.add(
+          "file.too_large",
+          `${entryPath}.content`,
+          `File '${normalized.value}' exceeds its bounded read allocation.`,
+        );
+        continue;
+      }
+      if (expectedFile && content.byteLength !== expectedFile.descriptor.bytes) {
+        context.add(
+          "file.size_drift",
+          `${expectedFile.descriptorPath}.bytes`,
+          `File '${normalized.value}' has ${content.byteLength} bytes; manifest declares ${expectedFile.descriptor.bytes}.`,
+        );
+      }
+      const bytes = materializeContent(content);
+      snapshots.set(normalized.value, bytes);
+    }
+  } catch {
+    context.add("file.invalid_iterable", "$files", "Could not enumerate prebuilt files safely.");
+  }
+
+  if (!stoppedForTotal) {
+    for (const [filePath, expectedFile] of expected) {
+      const bytes = snapshots.get(filePath);
+      if (!bytes) {
+        if (!seen.has(filePath)) {
+          context.add("file.missing", `${expectedFile.descriptorPath}.path`, `Declared file '${filePath}' is missing.`);
+        }
+        continue;
+      }
+      if (bytes.byteLength !== expectedFile.descriptor.bytes) continue;
+      const actualHash = await sha256(bytes);
+      if (actualHash !== expectedFile.descriptor.sha256) {
+        context.add(
+          "file.hash_drift",
+          `${expectedFile.descriptorPath}.sha256`,
+          `File '${filePath}' does not match its declared SHA-256.`,
+        );
+      }
+      if (PREBUILT_TEXT_MEDIA_TYPES.includes(expectedFile.descriptor.mediaType) && !isUtf8(bytes)) {
+        context.add(
+          "file.invalid_utf8",
+          `${expectedFile.descriptorPath}.mediaType`,
+          `File '${filePath}' must be valid UTF-8 for media type '${expectedFile.descriptor.mediaType}'.`,
+        );
+      }
+    }
+  }
+
+  const files = manifest.files
+    .filter((descriptor) => snapshots.has(descriptor.path))
+    .map((descriptor) => ({ path: descriptor.path, content: snapshots.get(descriptor.path) }));
+  return context.finish({ manifest, files, fileCount: snapshots.size, totalBytes });
+}
+
+export async function validatePrebuiltArtifact(manifestInput, fileEntries, options = {}) {
+  const manifestResult = validatePrebuiltManifest(manifestInput, options);
+  if (!manifestResult.ok) return manifestResult;
+  return validatePrebuiltArtifactContents(manifestResult.value, fileEntries, false);
+}
+
+// Internal Node boundary: the manifest and buffers were already snapshotted from
+// stable file handles and are not reachable by the public caller.
+export async function validatePrebuiltArtifactFromTrustedSnapshots(validatedManifest, fileEntries) {
+  return validatePrebuiltArtifactContents(validatedManifest, fileEntries, true);
+}
+
+export async function assertValidPrebuiltArtifact(manifestInput, fileEntries, options = {}) {
+  const result = await validatePrebuiltArtifact(manifestInput, fileEntries, options);
+  if (!result.ok) throw new DocsArtifactValidationError(result.errors);
+  return result.value;
+}

package/src/prebuilt-conformance.js

@@ -0,0 +1,151 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { FILE_OPEN_RACE_HOOK } from "./node-internal.js";
+import { validatePrebuiltArtifact } from "./prebuilt-artifact-validator.js";
+import { PREBUILT_LIMITS } from "./prebuilt-constants.js";
+import { serializePrebuiltManifest } from "./prebuilt-manifest-validator.js";
+import { validatePrebuiltArtifactDirectory } from "./prebuilt-node.js";
+
+const FIXTURES_ROOT = new URL("../fixtures/", import.meta.url);
+
+function targetAt(root, segments) {
+  let target = root;
+  for (let index = 0; index < segments.length - 1; index += 1) target = target[segments[index]];
+  return { target, key: segments.at(-1) };
+}
+
+function applyMutations(manifest, mutations = []) {
+  for (const mutation of mutations) {
+    const { target, key } = targetAt(manifest, mutation.path);
+    if (mutation.operation === "repeat-array") {
+      const source = target[key][mutation.sourceIndex];
+      target[key] = Array.from({ length: mutation.count }, () => structuredClone(source));
+      continue;
+    }
+    const value = mutation.repeat === undefined
+      ? structuredClone(mutation.value)
+      : `${mutation.repeat.repeat(mutation.count)}${mutation.suffix ?? ""}`;
+    if (mutation.operation === "append") target[key].push(value);
+    else if (mutation.operation === "remove") target.splice(key, 1);
+    else if (mutation.operation === "replace") target[key] = value;
+    else throw new Error(`Unsupported prebuilt conformance mutation '${mutation.operation}'.`);
+  }
+}
+
+async function baseFiles(manifest, baseManifest, omitted = []) {
+  const directory = baseManifest.slice(0, baseManifest.lastIndexOf("/") + 1);
+  const files = [];
+  for (const descriptor of manifest.files) {
+    if (omitted.includes(descriptor.path)) continue;
+    files.push({
+      path: descriptor.path,
+      content: await readFile(new URL(`${directory}${descriptor.path}`, FIXTURES_ROOT)),
+    });
+  }
+  return files;
+}
+
+async function specifiedFiles(specifications = []) {
+  const result = [];
+  for (const specification of specifications) {
+    let content;
+    if (specification.source) content = await readFile(new URL(specification.source, FIXTURES_ROOT));
+    else if (specification.base64 !== undefined) content = Buffer.from(specification.base64, "base64");
+    else content = Buffer.from(specification.utf8 ?? "", "utf8");
+    result.push({ path: specification.path, content });
+  }
+  return result;
+}
+
+async function expectedArchive(specification) {
+  if (!specification) return undefined;
+  return {
+    bytes: await readFile(new URL(specification.path, FIXTURES_ROOT)),
+    byteLength: specification.byteLength,
+    sha256: specification.sha256,
+  };
+}
+
+export async function loadPrebuiltConformanceCases() {
+  const index = JSON.parse(await readFile(new URL("prebuilt/conformance.json", FIXTURES_ROOT), "utf8"));
+  if (index.schemaVersion !== 1 || !Array.isArray(index.cases)) {
+    throw new Error("Unsupported prebuilt conformance fixture index.");
+  }
+  const cases = [];
+  for (const fixture of index.cases) {
+    let manifest;
+    let manifestValue;
+    if (fixture.baseManifest) {
+      manifestValue = JSON.parse(await readFile(new URL(fixture.baseManifest, FIXTURES_ROOT), "utf8"));
+      applyMutations(manifestValue, fixture.mutations);
+      manifest = Buffer.from(JSON.stringify(manifestValue));
+    } else {
+      manifest = await readFile(new URL(fixture.manifest, FIXTURES_ROOT));
+    }
+    const files = [
+      ...(fixture.includeBaseFiles ? await baseFiles(manifestValue, fixture.baseManifest, fixture.omitBaseFiles) : []),
+      ...await specifiedFiles(fixture.files),
+    ];
+    if (fixture.manifestPaddingBytes) {
+      manifest = Buffer.concat([
+        manifest,
+        Buffer.alloc(Math.min(fixture.manifestPaddingBytes, PREBUILT_LIMITS.manifestBytes + 1), 0x20),
+      ]);
+    }
+    cases.push({
+      name: fixture.name,
+      valid: fixture.valid,
+      expectedCodes: fixture.expectedCodes,
+      manifest,
+      files,
+      nodeScenario: fixture.nodeScenario === undefined ? undefined : structuredClone(fixture.nodeScenario),
+      expectedArchive: await expectedArchive(fixture.archive),
+    });
+  }
+  return cases;
+}
+
+async function materializeDirectory(root, manifest, files) {
+  await writeFile(path.join(root, "taproot-docs-prebuilt-manifest.json"), manifest);
+  for (const file of files) {
+    const target = path.join(root, ...file.path.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, file.content);
+  }
+}
+
+export async function validatePrebuiltConformanceCase(fixture) {
+  if (fixture.nodeScenario === undefined) {
+    return validatePrebuiltArtifact(fixture.manifest, fixture.files);
+  }
+  if (fixture.nodeScenario.type !== "replace-file-with-directory-before-open") {
+    throw new Error(`Unsupported prebuilt Node conformance scenario '${fixture.nodeScenario.type}'.`);
+  }
+  const semanticResult = await validatePrebuiltArtifact(fixture.manifest, fixture.files);
+  if (!semanticResult.ok) return semanticResult;
+  if (!semanticResult.value.files.some((file) => file.path === fixture.nodeScenario.path)) {
+    throw new Error("The prebuilt Node conformance scenario must target a declared payload file.");
+  }
+
+  const root = await mkdtemp(path.join(tmpdir(), "taproot-docs-prebuilt-conformance-"));
+  try {
+    await materializeDirectory(
+      root,
+      serializePrebuiltManifest(semanticResult.value.manifest),
+      semanticResult.value.files,
+    );
+    let replaced = false;
+    const options = {
+      [FILE_OPEN_RACE_HOOK]: async (displayPath, absolutePath) => {
+        if (replaced || displayPath !== fixture.nodeScenario.path) return;
+        replaced = true;
+        await rm(absolutePath);
+        await mkdir(absolutePath);
+      },
+    };
+    return await validatePrebuiltArtifactDirectory(root, options);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}

package/src/prebuilt-constants.js

@@ -0,0 +1,55 @@
+export const PREBUILT_MANIFEST_FILE_NAME = "taproot-docs-prebuilt-manifest.json";
+export const PREBUILT_SCHEMA_VERSION = 1;
+export const PREBUILT_MODE = "prebuilt";
+export const PREBUILT_ARCHIVE_FORMAT = "taproot-docs-prebuilt-tar-gzip-v1";
+export const PREBUILT_FILES_CAPABILITY = "taproot.docs.prebuilt.files.v1";
+export const PREBUILT_NOT_FOUND_FILE = "404.html";
+
+export const PREBUILT_SUPPORTED_CAPABILITIES = Object.freeze([
+  PREBUILT_FILES_CAPABILITY,
+]);
+
+export const PREBUILT_LIMITS = Object.freeze({
+  manifestBytes: 8 * 1024 * 1024,
+  manifestObjectWork: 250_000,
+  manifestObjectDepth: 64,
+  artifactBytes: 512 * 1024 * 1024,
+  fileBytes: 64 * 1024 * 1024,
+  files: 25_000,
+  resources: 25_000,
+  redirects: 10_000,
+  artifactPathBytes: 255,
+  directoryDepth: 64,
+  directoryEntries: 40_000,
+  supportedCapabilities: 100,
+  resourceKey: 200,
+  title: 300,
+  routeBytes: 2_000,
+});
+
+export const PREBUILT_MEDIA_TYPES = Object.freeze([
+  "application/json; charset=utf-8",
+  "application/manifest+json; charset=utf-8",
+  "application/octet-stream",
+  "application/wasm",
+  "application/xml; charset=utf-8",
+  "font/otf",
+  "font/ttf",
+  "font/woff",
+  "font/woff2",
+  "image/avif",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/svg+xml",
+  "image/vnd.microsoft.icon",
+  "image/webp",
+  "text/css; charset=utf-8",
+  "text/html; charset=utf-8",
+  "text/javascript; charset=utf-8",
+  "text/plain; charset=utf-8",
+]);
+
+export const PREBUILT_TEXT_MEDIA_TYPES = Object.freeze(
+  PREBUILT_MEDIA_TYPES.filter((mediaType) => mediaType.includes("charset=utf-8") || mediaType === "image/svg+xml"),
+);