@bjoernrochel/sevro 0.1.0-rc.1

package/src/preparation.ts

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAX_ARTIFACT_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+
+export interface PreparationArtifact {
+  id: string;
+  relativePath: string;
+  sha256: string;
+  contentBase64?: string;
+  sourceRef?: string;
+  gitExclude?: boolean;
+  executable?: boolean;
+}
+
+export interface InlineArtifact {
+  id: string;
+  relativePath: string;
+  sha256: string;
+  bytes: Uint8Array;
+  gitExclude?: boolean;
+  executable?: boolean;
+}
+
+export interface PreparationSources {
+  root: string;
+  refs: Record<string, string>;
+}
+
+export function fixtureParts(relativePath: string): string[] {
+  if (
+    !relativePath ||
+    isAbsolute(relativePath) ||
+    relativePath.includes("\\") ||
+    /:/.test(relativePath)
+  )
+    throw new Error(`invalid fixture path: ${relativePath}`);
+  const parts = relativePath.split("/");
+  if (parts.some((part) => !part || part === "." || part === ".."))
+    throw new Error(`invalid fixture path: ${relativePath}`);
+  return parts;
+}
+
+/** Refuse fixture or setup-created links before mounting trusted artifact bytes. */
+export async function safePreparationTarget(
+  workspace: string,
+  relativePath: string,
+): Promise<string> {
+  const parts = fixtureParts(relativePath);
+  let parent = workspace;
+  for (const part of parts.slice(0, -1)) {
+    parent = join(parent, part);
+    try {
+      const entry = await lstat(parent);
+      if (!entry.isDirectory() || entry.isSymbolicLink())
+        throw new Error("preparation artifact traverses a non-directory");
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+        throw error;
+      await mkdir(parent, { mode: 0o700 });
+    }
+  }
+  const target = join(workspace, ...parts);
+  try {
+    await lstat(target);
+    throw new Error("preparation artifact path already exists");
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+      throw error;
+  }
+  return target;
+}
+
+function validatePaths(paths: string[]): void {
+  const normalized = paths.map((path) =>
+    fixtureParts(path).join("/").toLowerCase(),
+  );
+  for (let index = 0; index < normalized.length; index++) {
+    for (let other = 0; other < index; other++) {
+      if (
+        normalized[index] === normalized[other] ||
+        normalized[index]!.startsWith(`${normalized[other]}/`) ||
+        normalized[other]!.startsWith(`${normalized[index]}/`)
+      )
+        throw new Error("fixture paths collide");
+    }
+  }
+}
+
+/** Decode declared inline artifacts before creating a candidate workspace. */
+export function prepareInlineArtifacts(
+  declarations: PreparationArtifact[],
+  fixturePaths: string[],
+): InlineArtifact[] {
+  validatePaths([
+    ...fixturePaths,
+    ...declarations.map((item) => item.relativePath),
+  ]);
+  const ids = new Set<string>();
+  let totalBytes = 0;
+  return declarations.map((item) => {
+    if (!item.id || ids.has(item.id))
+      throw new Error("preparation artifact IDs must be unique and nonempty");
+    ids.add(item.id);
+    if (item.gitExclude !== undefined && typeof item.gitExclude !== "boolean")
+      throw new Error("preparation artifact gitExclude must be boolean");
+    if (item.executable !== undefined && typeof item.executable !== "boolean")
+      throw new Error("preparation artifact executable must be boolean");
+    if (item.gitExclude && /[\u0000-\u001f\u007f]/.test(item.relativePath))
+      throw new Error("Git-excluded artifact path contains control characters");
+    if (item.sourceRef !== undefined || typeof item.contentBase64 !== "string")
+      throw new Error("preparation source references are not supported");
+    const encoded = item.contentBase64;
+    if (
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        encoded,
+      )
+    )
+      throw new Error("preparation artifact content is not canonical base64");
+    const bytes = Buffer.from(encoded, "base64");
+    if (bytes.toString("base64") !== encoded)
+      throw new Error("preparation artifact content is not canonical base64");
+    totalBytes += bytes.byteLength;
+    if (bytes.byteLength > MAX_ARTIFACT_BYTES || totalBytes > MAX_TOTAL_BYTES)
+      throw new Error("preparation artifacts exceed the size limit");
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (actual !== item.sha256)
+      throw new Error("preparation artifact digest does not match content");
+    return {
+      id: item.id,
+      relativePath: item.relativePath,
+      sha256: item.sha256,
+      bytes,
+      ...(item.gitExclude === undefined ? {} : { gitExclude: item.gitExclude }),
+      ...(item.executable === undefined ? {} : { executable: item.executable }),
+    };
+  });
+}
+
+/** Resolve opaque source IDs only through an explicitly declared case source map. */
+export async function prepareArtifacts(
+  declarations: PreparationArtifact[],
+  fixturePaths: string[],
+  sources?: PreparationSources,
+): Promise<InlineArtifact[]> {
+  if (!declarations.some((item) => item.sourceRef !== undefined))
+    return prepareInlineArtifacts(declarations, fixturePaths);
+  if (!sources || !isAbsolute(sources.root))
+    throw new Error("preparation source root is required and must be absolute");
+  const root = await realpath(sources.root).catch(() => {
+    throw new Error("preparation source root is unreadable");
+  });
+  const resolved: PreparationArtifact[] = [];
+  let sourceBytes = 0;
+  for (const item of declarations) {
+    if (item.sourceRef === undefined) {
+      resolved.push(item);
+      continue;
+    }
+    if (item.contentBase64 !== undefined)
+      throw new Error("preparation artifact has two content sources");
+    if (!Object.hasOwn(sources.refs, item.sourceRef))
+      throw new Error("preparation source reference is not declared");
+    const url = sources.refs[item.sourceRef];
+    if (typeof url !== "string" || !url.startsWith("file:///"))
+      throw new Error("preparation source reference must be a file URL");
+    let path: string;
+    try {
+      path = await realpath(fileURLToPath(url));
+    } catch {
+      throw new Error("preparation source is unreadable");
+    }
+    const child = relative(root, path);
+    if (
+      !child ||
+      child === ".." ||
+      child.startsWith(`..${sep}`) ||
+      isAbsolute(child)
+    )
+      throw new Error("preparation source escapes its declared root");
+    let size: number;
+    try {
+      size = (await stat(path)).size;
+    } catch {
+      throw new Error("preparation source is unreadable");
+    }
+    if (size > MAX_ARTIFACT_BYTES || sourceBytes + size > MAX_TOTAL_BYTES)
+      throw new Error("preparation artifacts exceed the size limit");
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(path);
+    } catch {
+      throw new Error("preparation source is unreadable");
+    }
+    sourceBytes += bytes.byteLength;
+    if (bytes.byteLength > MAX_ARTIFACT_BYTES || sourceBytes > MAX_TOTAL_BYTES)
+      throw new Error("preparation artifacts exceed the size limit");
+    resolved.push({
+      id: item.id,
+      relativePath: item.relativePath,
+      sha256: item.sha256,
+      contentBase64: bytes.toString("base64"),
+      ...(item.gitExclude === undefined ? {} : { gitExclude: item.gitExclude }),
+      ...(item.executable === undefined ? {} : { executable: item.executable }),
+    });
+  }
+  return prepareInlineArtifacts(resolved, fixturePaths);
+}

package/src/provenance.ts

@@ -0,0 +1,244 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, readlink, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import packageJson from "../package.json";
+import { hashJson } from "./identity";
+
+const MAX_DIRTY_BYTES = 32 * 1024 * 1024;
+const MAX_BUILD_BYTES = 64 * 1024 * 1024;
+const MAX_BUILD_FILES = 4096;
+
+function sha256(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Digest the packaged runtime and public contract files in path order. */
+export async function packageBuildDigest(
+  root = join(import.meta.dir, ".."),
+): Promise<string> {
+  const canonicalRoot = await realpath(root);
+  const files: { path: string; sha256: string }[] = [];
+  let totalBytes = 0;
+  async function collect(path: string): Promise<void> {
+    const absolute = join(canonicalRoot, path);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink())
+      throw new Error("package build contains a symbolic link");
+    if (info.isDirectory()) {
+      for (const entry of (await readdir(absolute)).sort())
+        await collect(join(path, entry));
+      return;
+    }
+    if (!info.isFile()) throw new Error("package build contains a non-file");
+    const bytes = await readFile(absolute);
+    totalBytes += bytes.byteLength;
+    if (files.length >= MAX_BUILD_FILES || totalBytes > MAX_BUILD_BYTES)
+      throw new Error("package build exceeds the size limit");
+    files.push({ path: path.split(sep).join("/"), sha256: sha256(bytes) });
+  }
+  for (const path of [
+    "package.json",
+    "README.md",
+    "docs",
+    "examples",
+    "schemas",
+    "src",
+  ])
+    await collect(path);
+  files.sort((left, right) =>
+    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
+  );
+  return hashJson({ format: "sevro.build.v1", files });
+}
+
+export async function projectIdentityDigest(
+  root: string,
+  provenance: { revision: string | null; dirtyPatchDigest: string | null },
+  excludedRoots: string[] = [],
+): Promise<string> {
+  if (provenance.revision)
+    return hashJson({
+      format: "sevro.project.v1",
+      revision: provenance.revision,
+      dirtyPatchDigest: provenance.dirtyPatchDigest,
+    });
+  const projectRoot = resolve(root);
+  const excluded = new Set(
+    excludedRoots.map((path) => relative(projectRoot, resolve(path))),
+  );
+  const files: { path: string; sha256: string; executable: boolean }[] = [];
+  let totalBytes = 0;
+  async function collect(path: string): Promise<void> {
+    if (path === ".git" || excluded.has(path)) return;
+    const absolute = join(projectRoot, path);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink())
+      throw new Error("project snapshot contains a symbolic link");
+    if (info.isDirectory()) {
+      for (const entry of (await readdir(absolute)).sort())
+        await collect(path === "" ? entry : join(path, entry));
+      return;
+    }
+    if (!info.isFile()) throw new Error("project snapshot contains a non-file");
+    const bytes = await readFile(absolute);
+    totalBytes += bytes.byteLength;
+    if (files.length >= MAX_BUILD_FILES || totalBytes > MAX_BUILD_BYTES)
+      throw new Error("project snapshot exceeds the size limit");
+    files.push({
+      path: path.split(sep).join("/"),
+      sha256: sha256(bytes),
+      executable: Boolean(info.mode & 0o111),
+    });
+  }
+  await collect("");
+  files.sort((left, right) =>
+    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
+  );
+  return hashJson({ format: "sevro.project.v1", files });
+}
+
+function git(root: string, ...arguments_: string[]): Buffer {
+  const result = Bun.spawnSync(["git", "-C", root, ...arguments_], {
+    env: { PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C" },
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) throw new Error("Git identity is unavailable");
+  if (result.stdout.byteLength > MAX_DIRTY_BYTES)
+    throw new Error("Git identity exceeds the size limit");
+  return Buffer.from(result.stdout);
+}
+
+async function dirtyPatchDigest(gitRoot: string): Promise<string | null> {
+  const trackedPatch = git(gitRoot, "diff", "--binary", "HEAD", "--");
+  const untrackedPaths = git(
+    gitRoot,
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+  )
+    .toString("utf8")
+    .split("\0")
+    .filter(Boolean)
+    .sort();
+  let dirtyBytes = trackedPatch.byteLength;
+  const untracked: { path: string; sha256: string }[] = [];
+  for (const path of untrackedPaths) {
+    const absolute = resolve(gitRoot, path);
+    const relativePath = relative(gitRoot, absolute);
+    if (
+      isAbsolute(relativePath) ||
+      relativePath === ".." ||
+      relativePath.startsWith(`..${sep}`)
+    )
+      throw new Error("Git checkout has an unsafe untracked path");
+    const info = await lstat(absolute);
+    const bytes = info.isSymbolicLink()
+      ? Buffer.from(await readlink(absolute), "utf8")
+      : info.isFile()
+        ? await readFile(absolute)
+        : null;
+    if (!bytes)
+      throw new Error("Git checkout has an unsupported untracked entry");
+    dirtyBytes += bytes.byteLength;
+    if (dirtyBytes > MAX_DIRTY_BYTES)
+      throw new Error("Git identity exceeds the size limit");
+    untracked.push({ path, sha256: sha256(bytes) });
+  }
+  return trackedPatch.byteLength || untracked.length
+    ? hashJson({ trackedPatch: sha256(trackedPatch), untracked })
+    : null;
+}
+
+/** Local development identity; packaged use never calls Git. */
+export async function checkoutProvenance(root: string, buildDigest: string) {
+  const canonicalRoot = await realpath(root);
+  const gitRoot = await realpath(
+    git(canonicalRoot, "rev-parse", "--show-toplevel").toString().trim(),
+  );
+  if (gitRoot !== canonicalRoot)
+    throw new Error(
+      "local Sevro checkout root does not match its Git repository",
+    );
+  const revision = git(canonicalRoot, "rev-parse", "HEAD").toString().trim();
+  if (!/^[a-f0-9]{40,64}$/.test(revision))
+    throw new Error("local Sevro checkout revision is invalid");
+  return {
+    source: "checkout" as const,
+    root: pathToFileURL(canonicalRoot).href,
+    revision,
+    dirtyPatchDigest: await dirtyPatchDigest(canonicalRoot),
+    buildDigest,
+  };
+}
+
+async function enclosingGitRoot(root: string): Promise<string | null> {
+  let path = root;
+  while (true) {
+    try {
+      await lstat(join(path, ".git"));
+      return path;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const parent = dirname(path);
+    if (parent === path) return null;
+    path = parent;
+  }
+}
+
+export async function projectProvenance(root: string) {
+  const canonicalRoot = await realpath(root);
+  const gitEntryRoot = await enclosingGitRoot(canonicalRoot);
+  if (!gitEntryRoot)
+    return {
+      root: pathToFileURL(canonicalRoot).href,
+      revision: null,
+      dirtyPatchDigest: null,
+    };
+  const gitRoot = await realpath(
+    git(canonicalRoot, "rev-parse", "--show-toplevel").toString().trim(),
+  );
+  if (gitRoot !== gitEntryRoot)
+    throw new Error("project Git root does not match its repository entry");
+  let revision: string;
+  try {
+    revision = git(gitRoot, "rev-parse", "HEAD").toString().trim();
+  } catch {
+    git(gitRoot, "status", "--porcelain");
+    return {
+      root: pathToFileURL(canonicalRoot).href,
+      revision: null,
+      dirtyPatchDigest: null,
+    };
+  }
+  if (!/^[a-f0-9]{40,64}$/.test(revision))
+    throw new Error("project Git revision is invalid");
+  return {
+    root: pathToFileURL(canonicalRoot).href,
+    revision,
+    dirtyPatchDigest: await dirtyPatchDigest(gitRoot),
+  };
+}
+
+export async function runnerProvenance(
+  buildDigest: string,
+  checkoutRoot?: string,
+) {
+  if (checkoutRoot) {
+    const actualRoot = await realpath(join(import.meta.dir, ".."));
+    if ((await realpath(checkoutRoot)) !== actualRoot)
+      throw new Error(
+        "local Sevro checkout root does not match the running package",
+      );
+    return checkoutProvenance(actualRoot, buildDigest);
+  }
+  return {
+    source: "package" as const,
+    packageName: packageJson.name,
+    version: packageJson.version,
+    buildDigest,
+  };
+}