gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/closure-format.ts

@@ -0,0 +1,350 @@
+/** Pure parser for the collector's existing sealed closure format. Numeric compiler enums are pinned to TypeScript 5.9.3. */
+import { createHash } from 'node:crypto';
+import { strictData } from './data';
+import { portablePath } from './protocol';
+import { canonicalJson, deepFreeze, digest, exactObject, semanticHash } from '../workflow/lib/canonicalData';
+const policy = 'gate-custom-cjs@1' as const;
+const hash = (bytes: Buffer | string) => createHash('sha256').update(bytes).digest('hex');
+export interface ClosureFile {
+  path: string;
+  kind: "module" | "json" | "data" | "config" | "metadata";
+  digest: string;
+  emittedDigest: string | null;
+}
+export interface ClosureEdge {
+  importer: string;
+  specifier: string;
+  target: string;
+  kind: "runtime" | "config";
+}
+export interface ClosurePackage {
+  lockLocation: string;
+  name: string;
+  version: string;
+  integrity: string;
+  source: { kind: "registry" | "tarball"; identity: string };
+  metadataDigest: string;
+  resolution: Record<string, unknown>;
+  payload: { path: string; digest: string }[];
+  payloadDigest: string;
+}
+export interface HostAdapter {
+  kind: "isolated-cjs" | "hardhat-2.26.3-ts-node-10.9.2";
+  preload: { path: string; digest: string } | null;
+  packages: { name: string; version: string; metadataDigest: string }[];
+}
+export interface CustomInputClosure {
+  version: 1;
+  policy: typeof policy;
+  roots: string[];
+  files: ClosureFile[];
+  edges: ClosureEdge[];
+  packages: ClosurePackage[];
+  compiler: {
+    version: string;
+    options: Record<string, unknown>;
+    config: string | null;
+  };
+  hostAdapter: HostAdapter;
+  resolver: {
+    policy: "node-default-cjs";
+    version: string;
+    flags: string[];
+    environment: "empty";
+  };
+  closureHash: string;
+}
+export const closureRuntimeOptions = {
+  target: 9,
+  module: 1,
+  esModuleInterop: true,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  sourceMap: false,
+  inlineSourceMap: false,
+  importHelpers: false,
+  removeComments: false,
+  newLine: 1,
+};
+export function parseCustomInputClosure(raw: unknown): CustomInputClosure {
+  const e = exactObject(
+    strictData(raw),
+    [
+      "version",
+      "policy",
+      "roots",
+      "files",
+      "edges",
+      "packages",
+      "compiler",
+      "hostAdapter",
+      "resolver",
+      "closureHash",
+    ],
+    "custom input closure"
+  );
+  const { closureHash, ...body } = e;
+  if (
+    e.version !== 1 ||
+    e.policy !== policy ||
+    digest(closureHash, "closure") !== semanticHash(body)
+  )
+    throw new Error("Custom closure identity mismatch");
+  if (
+    !Array.isArray(e.roots) ||
+    !e.roots.length ||
+    !Array.isArray(e.files) ||
+    !Array.isArray(e.edges) ||
+    !Array.isArray(e.packages)
+  )
+    throw new Error("Missing custom closure entries");
+  const kinds = new Map<string, ClosureFile["kind"]>();
+  for (const raw of e.files) {
+    const f = exactObject(
+      raw,
+      ["path", "kind", "digest", "emittedDigest"],
+      "closure file"
+    );
+    portablePath(f.path, "closure file");
+    digest(f.digest, "file");
+    if (
+      kinds.has(f.path as string) ||
+      typeof f.kind !== "string" ||
+      !["module", "json", "data", "config", "metadata"].includes(f.kind)
+    )
+      throw new Error("Invalid closure file");
+    kinds.set(f.path as string, f.kind as ClosureFile["kind"]);
+    if (f.kind === "module") digest(f.emittedDigest, "emitted module");
+    else if (f.emittedDigest !== null)
+      throw new Error("Invalid nonmodule emission");
+  }
+  if (
+    new Set(e.roots).size !== e.roots.length ||
+    e.roots.some((r) => typeof r !== "string" || kinds.get(r) !== "module")
+  )
+    throw new Error("Missing closure root");
+  // Config JSON can also be imported at runtime, which promotes its file kind to json.
+  const configFile = (name: string) =>
+    name.endsWith(".json") &&
+    ["config", "json"].includes(kinds.get(name) ?? "");
+  const edgeKeys = new Set<string>();
+  for (const raw of e.edges) {
+    const edge = exactObject(
+      raw,
+      ["importer", "specifier", "target", "kind"],
+      "closure edge"
+    );
+    if (
+      typeof edge.importer !== "string" ||
+      typeof edge.target !== "string" ||
+      typeof edge.specifier !== "string" ||
+      !edge.specifier ||
+      (edge.kind !== "runtime" && edge.kind !== "config")
+    )
+      throw new Error("Invalid closure edge");
+    const key = canonicalJson([edge.importer, edge.specifier, edge.kind]);
+    if (edgeKeys.has(key)) throw new Error("Duplicate closure edge");
+    edgeKeys.add(key);
+    if (
+      edge.kind === "runtime"
+        ? kinds.get(edge.importer) !== "module" ||
+          !["module", "json"].includes(kinds.get(edge.target) ?? "")
+        : !configFile(edge.importer) || !configFile(edge.target)
+    )
+      throw new Error("Invalid closure edge file relationship");
+  }
+  const files = e.files as ClosureFile[];
+  const packages = new Map<string, ClosurePackage>();
+  for (const raw of e.packages) {
+    const p = exactObject(
+      raw,
+      [
+        "lockLocation",
+        "name",
+        "version",
+        "integrity",
+        "source",
+        "metadataDigest",
+        "resolution",
+        "payload",
+        "payloadDigest",
+      ],
+      "closure package"
+    );
+    portablePath(p.lockLocation, "lock location");
+    digest(p.metadataDigest, "metadata");
+    digest(p.payloadDigest, "payload");
+    const s = exactObject(p.source, ["kind", "identity"], "package source");
+    if (s.kind !== "registry" && s.kind !== "tarball")
+      throw new Error("Invalid package source");
+    digest(s.identity, "source");
+    if (
+      typeof p.name !== "string" ||
+      typeof p.version !== "string" ||
+      typeof p.integrity !== "string" ||
+      !/^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/.test(p.integrity) ||
+      Buffer.from(p.integrity.split("-")[1], "base64").length !==
+        Number(p.integrity.slice(3).split("-")[0]) / 8 ||
+      !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(p.version) ||
+      !Array.isArray(p.payload) ||
+      semanticHash(p.payload) !== p.payloadDigest
+    )
+      throw new Error("Invalid package closure");
+    if (
+      !p.resolution ||
+      typeof p.resolution !== "object" ||
+      Array.isArray(p.resolution) ||
+      Object.keys(p.resolution).some(
+        (k) => !["type", "main", "exports", "imports"].includes(k)
+      )
+    )
+      throw new Error("Invalid package resolution metadata");
+    if (s.kind === "tarball" && s.identity !== hash(p.integrity))
+      throw new Error("Invalid tarball content identity");
+    const payloadNames = new Set<string>();
+    for (const raw of p.payload) {
+      const f = exactObject(raw, ["path", "digest"], "payload file");
+      const name = portablePath(f.path, "payload path");
+      digest(f.digest, "payload file");
+      if (payloadNames.has(name)) throw new Error("Duplicate payload path");
+      payloadNames.add(name);
+    }
+    const location = p.lockLocation as string;
+    if (
+      packages.has(location) ||
+      location
+        .split("/node_modules/")
+        .at(-1)!
+        .replace(/^node_modules\//, "") !== p.name ||
+      !location.split("/").includes("node_modules")
+    )
+      throw new Error("Invalid package lock location");
+    if (
+      !files.some(
+        (file) =>
+          file.path === `${location}/package.json` &&
+          file.digest === p.metadataDigest
+      ) ||
+      !(p.payload as ClosurePackage["payload"]).some(
+        (file) =>
+          file.path === "package.json" && file.digest === p.metadataDigest
+      )
+    )
+      throw new Error("Package metadata missing from payload/closure");
+    packages.set(location, p as unknown as ClosurePackage);
+  }
+  for (const file of files) {
+    const parts = file.path.split("/"),
+      index = parts.lastIndexOf("node_modules");
+    if (index < 0) continue;
+    const location = parts
+      .slice(0, index + (parts[index + 1]?.startsWith("@") ? 3 : 2))
+      .join("/");
+    const identity = packages.get(location);
+    if (
+      !identity?.payload.some(
+        (entry) =>
+          entry.path === file.path.slice(location.length + 1) &&
+          entry.digest === file.digest
+      )
+    )
+      throw new Error("Package file missing from locked payload");
+  }
+  const compiler = exactObject(
+    e.compiler,
+    ["version", "options", "config"],
+    "closure compiler"
+  );
+  if (
+    compiler.version !== "5.9.3" ||
+    (compiler.config !== null &&
+      (typeof compiler.config !== "string" || !configFile(compiler.config)))
+  )
+    throw new Error("Unsupported closure compiler/adapter");
+  const options = exactObject(
+    compiler.options,
+    [
+      ...Object.keys(closureRuntimeOptions),
+      ...(compiler.options &&
+      typeof compiler.options === "object" &&
+      Object.hasOwn(compiler.options, "useDefineForClassFields")
+        ? ["useDefineForClassFields"]
+        : []),
+    ],
+    "effective compiler options"
+  );
+  for (const [key, value] of Object.entries(closureRuntimeOptions)) {
+    if (!["target", "esModuleInterop"].includes(key) && options[key] !== value)
+      throw new Error("Unsupported effective compiler option");
+  }
+  if (
+    typeof options.esModuleInterop !== "boolean" ||
+    typeof options.target !== "number" ||
+    ![0,1,2,3,4,5,6,7,8,9,10,11,99,100].includes(options.target) ||
+    [0,100].includes(options.target) ||
+    (Object.hasOwn(options, "useDefineForClassFields") &&
+      typeof options.useDefineForClassFields !== "boolean")
+  )
+    throw new Error("Invalid effective compiler options");
+  const adapter = exactObject(
+    e.hostAdapter,
+    ["kind", "preload", "packages"],
+    "host adapter"
+  );
+  if (
+    (adapter.kind !== "isolated-cjs" &&
+      adapter.kind !== "hardhat-2.26.3-ts-node-10.9.2") ||
+    !Array.isArray(adapter.packages)
+  )
+    throw new Error("Unsupported host adapter");
+  if (
+    adapter.kind === "isolated-cjs" &&
+    (adapter.preload !== null || adapter.packages.length)
+  )
+    throw new Error("Invalid isolated loader");
+  if (adapter.preload !== null) {
+    const p = exactObject(adapter.preload, ["path", "digest"], "preload");
+    portablePath(p.path, "preload");
+    digest(p.digest, "preload");
+  }
+  for (const raw of adapter.packages) {
+    const p = exactObject(
+      raw,
+      ["name", "version", "metadataDigest"],
+      "adapter package"
+    );
+    digest(p.metadataDigest, "adapter metadata");
+  }
+  if (adapter.kind === "hardhat-2.26.3-ts-node-10.9.2") {
+    if (
+      adapter.preload === null ||
+      (adapter.preload as { path: string }).path !==
+        "node_modules/ts-node/register/index.js" ||
+      canonicalJson(
+        (adapter.packages as HostAdapter["packages"]).map((p) => [
+          p.name,
+          p.version,
+        ])
+      ) !==
+        canonicalJson([
+          ["ts-node", "10.9.2"],
+          ["hardhat", "2.26.3"],
+        ])
+    )
+      throw new Error("Invalid pinned preload adapter");
+  }
+  const resolver = exactObject(
+    e.resolver,
+    ["policy", "version", "flags", "environment"],
+    "resolver"
+  );
+  if (
+    resolver.policy !== "node-default-cjs" ||
+    typeof resolver.version !== "string" ||
+    !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(resolver.version) ||
+    resolver.environment !== "empty" ||
+    canonicalJson(resolver.flags) !== canonicalJson(["--preserve-symlinks"])
+  )
+    throw new Error("Unsupported resolver policy");
+  return deepFreeze(e as unknown as CustomInputClosure);
+}

package/runtime/delivery/codec-pin.ts

@@ -0,0 +1,3 @@
+// Reviewed vendor identity. Refresh explicitly after rebuilding from committed canonical sources.
+export const PLAN_CODEC_PROVENANCE_SHA256 = '63bc721e90943e08478a67a72d1bef8ce69a034552f225b90ee2c6e5396785ce';
+export const PLAN_CODEC_SOURCE_COMMIT = '9b175e7906ca6735aeca92b50ce7cf716d980f17';

package/runtime/delivery/codec.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { PLAN_CODEC_PROVENANCE_SHA256, PLAN_CODEC_SOURCE_COMMIT } from './codec-pin';
+import type * as Canonical from '../vendor/plan-codec/index.cjs';
+
+const sha256 = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
+function regularBytes(directory: string, name: string): Buffer {
+  const file = path.join(directory, name);
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error(`Unsafe codec artifact: ${name}`);
+  return fs.readFileSync(file);
+}
+/** The reviewed pin protects provenance as well as the bundle. No checkout or network is used. */
+export function verifyPlanCodec(directory: string): void {
+  if (fs.lstatSync(directory).isSymbolicLink()) throw new Error('Unsafe codec directory');
+  const bytes = regularBytes(directory, 'provenance.json');
+  if (sha256(bytes) !== PLAN_CODEC_PROVENANCE_SHA256) throw new Error('Plan codec provenance digest mismatch');
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  if (manifest.formatVersion !== 1 || manifest.name !== 'gateflow-plan-read-only' || manifest.version !== 1
+    || manifest.schema !== 'gateflow-plan/v2' || manifest.definitionContract !== 'gateflow-plan/definition@1'
+    || manifest.sourceCommit !== PLAN_CODEC_SOURCE_COMMIT) throw new Error('Unsupported plan codec provenance');
+  for (const name of ['index.cjs', 'index.d.cts']) {
+    if (sha256(regularBytes(directory, name)) !== manifest.artifacts[name]) throw new Error(`Plan codec artifact digest mismatch: ${name}`);
+  }
+}
+export function loadPlanCodec(): typeof Canonical {
+  const directory = path.join(__dirname, '..', 'vendor', 'plan-codec');
+  verifyPlanCodec(directory);
+  return require(path.join(directory, 'index.cjs')) as typeof Canonical;
+}
+
+export interface PlanCodecObservation {
+  schema: 'gateflow-plan/v2'; definitionContract: 'gateflow-plan/definition@1'; sourceCommit: string;
+  provenanceHash: string; bundleHash: string; declarationHash: string;
+}
+/** Own the actual loader seam, including a cached bundle's continued file/module association. */
+export function openPlanCodecObservation(): {readonly snapshot: Readonly<PlanCodecObservation>; assertUnchanged():void; seal():Readonly<PlanCodecObservation>; close():void} {
+  const directory=path.join(__dirname,'..','vendor','plan-codec');
+  const loaded=loadPlanCodec(),entry=path.join(directory,'index.cjs');
+  const observe=():Readonly<PlanCodecObservation>=>{
+    verifyPlanCodec(directory);
+    if(require.cache[entry]?.exports!==loaded)throw new Error('Plan codec loaded module drift');
+    return Object.freeze({schema:'gateflow-plan/v2',definitionContract:'gateflow-plan/definition@1',sourceCommit:PLAN_CODEC_SOURCE_COMMIT,
+      provenanceHash:sha256(regularBytes(directory,'provenance.json')),bundleHash:sha256(regularBytes(directory,'index.cjs')),declarationHash:sha256(regularBytes(directory,'index.d.cts'))});
+  };
+  const snapshot=observe();let open=true;
+  const check=()=>{if(!open)throw new Error('Plan codec observation closed');if(JSON.stringify(observe())!==JSON.stringify(snapshot))throw new Error('Plan codec observation drift');};
+  return Object.freeze({snapshot,assertUnchanged(){try{check();}catch(error){open=false;throw error;}},seal(){try{check();return snapshot;}finally{open=false;}},close(){open=false;}});
+}