gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/custom-format.ts

@@ -0,0 +1,464 @@
+/** Pure structural parsers shared by planning and independent plan export. */
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { strictData } from './data';
+import { portablePath } from './protocol';
+import { PUBLIC_TARGET_FIELDS } from './target-fields';
+import { parseBusinessReference } from './references';
+import { parseCustomInputClosure, type CustomInputClosure } from './closure-format';
+const { FunctionFragment }: Pick<typeof import('ethers'), 'FunctionFragment'> = require('ethers/abi');
+const { isAddress }: Pick<typeof import('ethers'), 'isAddress'> = require('ethers/address');
+import { deploymentInstanceId, validateDeploySaveAs } from '../workflow/lib/operationNames';
+import { canonicalData, deepFreeze, exactObject, nonempty, semanticHash } from '../workflow/lib/canonicalData';
+import type { WorkflowStep } from '../workflow/lib/parameters';
+const bytesHash = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex');
+const PUBLIC_TARGET = PUBLIC_TARGET_FIELDS;
+function record(
+  raw: unknown,
+  allowed: string[],
+  required: string[],
+  label: string
+): Record<string, unknown> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error(`${label} must be an object`);
+  const v = raw as Record<string, unknown>;
+  if (
+    Object.keys(v).some((k) => !allowed.includes(k)) ||
+    required.some((k) => !Object.hasOwn(v, k))
+  )
+    throw new Error(`${label} has unsupported or missing fields`);
+  return v;
+}
+function reference(value: unknown): boolean {
+  return parseBusinessReference(value) !== null;
+}
+function refs(value: unknown): void {
+  if (reference(value)) return;
+  if (value && typeof value === "object") Object.values(value).forEach(refs);
+}
+function string(v: unknown, label: string): void {
+  nonempty(v, label);
+}
+function array(v: unknown, label: string): void {
+  if (!Array.isArray(v) && !reference(v))
+    throw new Error(`${label} must be an array or reference`);
+}
+function quantity(v: unknown): void {
+  if (reference(v)) return;
+  if (
+    !(typeof v === "number" && Number.isSafeInteger(v) && v >= 0) &&
+    !(typeof v === "string" && /^(0x[\da-fA-F]+|\d+)$/.test(v))
+  )
+    throw new Error("Invalid nonnegative value");
+  if (BigInt(v as string | number) >= 2n ** 256n)
+    throw new Error("Value exceeds uint256");
+}
+function address(v: unknown, label: string): void {
+  if (
+    !reference(v) &&
+    (typeof v !== "string" || !isAddress(v) || /^0x0{40}$/i.test(v))
+  )
+    throw new Error(`Invalid ${label} address`);
+}
+function method(v: unknown): void {
+  string(v, "method");
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(v as string)) return;
+  try {
+    if (FunctionFragment.from(v as string).format("sighash") !== v)
+      throw new Error();
+  } catch {
+    throw new Error("Invalid canonical method signature");
+  }
+}
+function upgradeCall(v: unknown): void {
+  const c = record(v, ["method", "fn", "args"], [], "upgrade call");
+  if (Object.hasOwn(c, "method") === Object.hasOwn(c, "fn"))
+    throw new Error("upgrade call requires one method");
+  method(c.method ?? c.fn);
+  if (c.args !== undefined) array(c.args, "upgrade args");
+}
+function proxyIdentifier(v: unknown): void {
+  if (reference(v)) return;
+  string(v, "proxy");
+  if (/^0x/i.test(v as string)) address(v, "proxy");
+}
+function proxy(v: unknown, deploying: boolean): void {
+  if (!deploying && (typeof v === "string" || reference(v))) {
+    proxyIdentifier(v);
+    return;
+  }
+  const p = record(
+    v,
+    [
+      "kind",
+      "initializer",
+      "unsafeAllow",
+      "constructorArgs",
+      ...(deploying ? [] : ["address", "name", "contract"]),
+    ],
+    [],
+    "proxy"
+  );
+  if (p.kind !== undefined && p.kind !== "uups")
+    throw new Error("Only UUPS proxy supported");
+  if (p.initializer !== undefined && p.initializer !== false)
+    string(p.initializer, "initializer");
+  if (p.constructorArgs !== undefined)
+    array(p.constructorArgs, "constructorArgs");
+  if (
+    p.unsafeAllow !== undefined &&
+    (!Array.isArray(p.unsafeAllow) ||
+      p.unsafeAllow.some((x) => typeof x !== "string" || !x))
+  )
+    throw new Error("Invalid unsafeAllow");
+  if (p.address !== undefined) address(p.address, "proxy");
+  for (const key of ["name", "contract"])
+    if (p[key] !== undefined) {
+      string(p[key], key);
+      proxyIdentifier(p[key]);
+    }
+  if (
+    !deploying &&
+    !["address", "name", "contract"].some((k) => p[k] !== undefined)
+  )
+    throw new Error("Upgrade proxy requires address/name/contract");
+}
+export function parseNativeOperation(raw: unknown): WorkflowStep {
+  const data = strictData(raw, "operation");
+  const base = record(
+    data,
+    [
+      "id",
+      "kind",
+      "contract",
+      "abi",
+      "address",
+      "deployment",
+      "saveAs",
+      "calls",
+      "strategy",
+      "args",
+      "create2",
+      "proxy",
+      "upgradeableStrategy",
+      "firstUpgrade",
+      "constructorArgs",
+      "call",
+      "proxyKind",
+    ],
+    ["id", "kind", "contract"],
+    "operation"
+  );
+  string(base.id, "operation id");
+  if ((base.id as string).length > 200)
+    throw new Error("operation id exceeds 200 characters");
+  string(base.contract, "contract");
+  const kind = base.kind;
+  if (!["deploy", "upgrade", "call", "view", "check"].includes(String(kind)))
+    throw new Error("Unknown or nested custom operation kind");
+  const keys = [
+    "id",
+    "kind",
+    "contract",
+    ...(kind === "deploy"
+      ? [
+          "saveAs",
+          "strategy",
+          "args",
+          "create2",
+          "proxy",
+          "upgradeableStrategy",
+          "firstUpgrade",
+        ]
+      : kind === "upgrade"
+      ? ["saveAs", "address", "proxy", "proxyKind", "constructorArgs", "call"]
+      : ["abi", "address", "deployment", "saveAs", "calls"]),
+  ];
+  record(base, keys, ["id", "kind", "contract"], "operation");
+  refs(base);
+  for (const key of ["abi", "deployment", "saveAs"])
+    if (base[key] !== undefined) string(base[key], key);
+  if (base.address !== undefined) address(base.address, "operation");
+  if (kind === "deploy") {
+    string(base.saveAs, "saveAs");
+    if ((base.saveAs as string).includes(":"))
+      throw new Error("Invalid saveAs");
+    if (base.strategy !== "create2")
+      throw new Error("Deploy requires CREATE2 strategy");
+    const c = record(
+      base.create2,
+      [
+        "salt",
+        "factory",
+        "create2ForwardValue",
+        "callForwardValue",
+        "expectedAddress",
+        "leadingZeroBytes",
+      ],
+      ["salt"],
+      "create2"
+    );
+    if (
+      !reference(c.salt) &&
+      (typeof c.salt !== "string" || !/^0x[\da-fA-F]{64}$/.test(c.salt))
+    )
+      throw new Error("Invalid CREATE2 bytes32 salt");
+    for (const key of ["factory", "expectedAddress"])
+      if (c[key] !== undefined) address(c[key], key);
+    for (const key of ["create2ForwardValue", "callForwardValue"])
+      if (c[key] !== undefined) {
+        quantity(c[key]);
+      }
+    if (
+      c.leadingZeroBytes !== undefined &&
+      !reference(c.leadingZeroBytes) &&
+      (!Number.isInteger(c.leadingZeroBytes) ||
+        Number(c.leadingZeroBytes) < 0 ||
+        Number(c.leadingZeroBytes) > 20)
+    )
+      throw new Error("Invalid leadingZeroBytes");
+    if (base.args !== undefined) array(base.args, "constructor args");
+    if (base.proxy !== undefined) {
+      proxy(base.proxy, true);
+      if (
+        (base.proxy as Record<string, unknown>).initializer !== false ||
+        base.upgradeableStrategy !== "uups-placeholder-proxy"
+      )
+        throw new Error(
+          "UUPS deployment requires placeholder strategy and initializer false"
+        );
+      const first = record(
+        base.firstUpgrade,
+        ["contract", "constructorArgs", "unsafeAllow", "call"],
+        ["contract"],
+        "firstUpgrade"
+      );
+      string(first.contract, "firstUpgrade contract");
+      if (
+        base.contract !== first.contract &&
+        ![
+          "ERC1967Proxy",
+          "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy",
+        ].includes(base.contract as string)
+      )
+        throw new Error("firstUpgrade contract mismatch");
+      if (first.constructorArgs !== undefined)
+        array(first.constructorArgs, "firstUpgrade constructorArgs");
+      if (
+        first.unsafeAllow !== undefined &&
+        (!Array.isArray(first.unsafeAllow) ||
+          first.unsafeAllow.some((x) => typeof x !== "string" || !x))
+      )
+        throw new Error("Invalid unsafeAllow");
+      if (first.call !== undefined) upgradeCall(first.call);
+    } else if (
+      base.firstUpgrade !== undefined ||
+      base.upgradeableStrategy !== undefined
+    )
+      throw new Error("firstUpgrade requires proxy");
+  } else if (kind === "upgrade") {
+    if (base.saveAs !== undefined) deploymentInstanceId(base.saveAs as string);
+    if (base.proxy !== undefined) proxy(base.proxy, false);
+    else if (base.address === undefined)
+      throw new Error("Upgrade requires proxy");
+    if (base.proxyKind !== undefined && base.proxyKind !== "uups")
+      throw new Error("Only UUPS upgrade supported");
+    if (base.constructorArgs !== undefined)
+      array(base.constructorArgs, "constructorArgs");
+    if (base.call !== undefined) upgradeCall(base.call);
+  } else {
+    if (!Array.isArray(base.calls) || !base.calls.length)
+      throw new Error("Operation requires nonempty calls");
+    for (const call of base.calls) {
+      const c = record(
+        call,
+        kind === "check"
+          ? ["method", "args", "expect"]
+          : kind === "call"
+          ? ["method", "args", "value"]
+          : ["method", "args"],
+        kind === "check" ? ["method", "expect"] : ["method"],
+        "call"
+      );
+      method(c.method);
+      if (c.args !== undefined) array(c.args, "call args");
+      if (c.value !== undefined) quantity(c.value);
+    }
+  }
+  return deepFreeze(base as WorkflowStep);
+}
+export function parseCustomOperations(raw: unknown): WorkflowStep[] {
+  raw = strictData(raw, "custom operations");
+  const v = exactObject(
+    raw,
+    ["version", "operations"],
+    "custom planning result"
+  );
+  if (v.version !== 1 || !Array.isArray(v.operations) || !v.operations.length)
+    throw new Error("Custom planning requires version 1 nonempty operations");
+  const operations = v.operations.map(parseNativeOperation);
+  if (new Set(operations.map((o) => o.id)).size !== operations.length)
+    throw new Error("Duplicate custom operation ID");
+  validateDeploySaveAs(operations);
+  return deepFreeze(operations);
+}
+export interface CustomObservation {
+  kind: "json" | "bytes" | "resolve";
+  key: string;
+  value: unknown;
+  digest: string;
+  bytesDigest: string | null;
+  inputPath: string | null;
+}
+export interface CustomEvidence {
+  version: 1;
+  sourceStepId: string;
+  module: { path: string; digest: string };
+  input: unknown;
+  declarations: {
+    files: string[];
+    params: string[];
+    state: string[];
+    target: string[];
+  };
+  operations: WorkflowStep[];
+  observations: CustomObservation[];
+  closure: CustomInputClosure;
+  evidenceHash: string;
+}
+export function parseDeclarations(raw: unknown): CustomEvidence["declarations"] {
+  const decl = exactObject(
+    raw,
+    ["files", "params", "state", "target"],
+    "custom declarations"
+  );
+  for (const [key, values] of Object.entries(decl)) {
+    if (
+      !Array.isArray(values) ||
+      values.some((v) => typeof v !== "string" || !v || v.trim() !== v) ||
+      new Set(values).size !== values.length
+    )
+      throw new Error(`Invalid ${key} declarations`);
+  }
+  const declarations = decl as unknown as CustomEvidence["declarations"];
+  if (declarations.target.some((k) => !PUBLIC_TARGET.has(k)))
+    throw new Error("Only public target fields may be declared");
+  return deepFreeze(declarations);
+}
+/** Structural preflight only; actual module/ABI/runtime validation remains owned by collectors. */
+export function parseCustomStep(raw: unknown): WorkflowStep {
+  const s = strictData(raw) as WorkflowStep;
+  record(s, ['id', 'kind', 'script', 'input', 'reads'], ['id', 'kind', 'script', 'reads'], 'custom step');
+  if (s.kind !== 'custom') throw new Error('Expected custom step');
+  nonempty(s.id, 'source step');
+  if (s.id.length > 200) throw new Error('source step id exceeds 200 characters');
+  portablePath(s.script, 'custom script');
+  const declarations = parseDeclarations(s.reads);
+  for (const file of declarations.files) portablePath(file, 'custom input');
+  return deepFreeze({ ...s, reads: declarations });
+}
+export function parseCustomEvidence(raw: unknown): CustomEvidence {
+  raw = strictData(raw, "custom evidence");
+  const e = exactObject(
+    raw,
+    [
+      "version",
+      "sourceStepId",
+      "module",
+      "input",
+      "declarations",
+      "operations",
+      "observations",
+      "closure",
+      "evidenceHash",
+    ],
+    "custom evidence"
+  );
+  const { evidenceHash, ...body } = e;
+  if (e.version !== 1 || evidenceHash !== semanticHash(body))
+    throw new Error("Custom evidence identity mismatch");
+  parseCustomOperations({ version: 1, operations: e.operations });
+  nonempty(e.sourceStepId, "custom source step");
+  const declarations = parseDeclarations(e.declarations);
+  const module = exactObject(e.module, ["path", "digest"], "module identity");
+  const modulePath = nonempty(module.path, "module path");
+  if (
+    path.isAbsolute(modulePath) ||
+    modulePath
+      .split(/[\\/]/)
+      .some((part) => !part || part === "." || part === "..")
+  )
+    throw new Error("Invalid confined module path");
+  if (
+    typeof module.digest !== "string" ||
+    !/^[a-f0-9]{64}$/.test(module.digest)
+  )
+    throw new Error("Invalid module identity");
+  const closure = parseCustomInputClosure(e.closure);
+  if (
+    !closure.roots.includes(modulePath) ||
+    !closure.files.some(
+      (file) =>
+        file.path === modulePath &&
+        file.kind === "module" &&
+        file.digest === module.digest
+    )
+  )
+    throw new Error("Custom module missing from closure");
+  if (!Array.isArray(e.observations)) throw new Error("Invalid observations");
+  for (const raw of e.observations) {
+    const o = exactObject(
+      raw,
+      ["kind", "key", "value", "digest", "bytesDigest", "inputPath"],
+      "custom observation"
+    );
+    if (
+      !["json", "bytes", "resolve"].includes(String(o.kind)) ||
+      o.digest !== semanticHash(o.value)
+    )
+      throw new Error("Custom observation mismatch");
+    const key = nonempty(o.key, "observation key");
+    if (o.kind === "resolve") {
+      if (o.inputPath !== null)
+        throw new Error("Invalid resolved observation path");
+      const dot = key.indexOf("."),
+        scope = key.slice(0, dot),
+        field = key.slice(dot + 1);
+      const allowed =
+        scope === "param"
+          ? declarations.params
+          : scope === "state"
+          ? declarations.state
+          : scope === "target"
+          ? declarations.target
+          : [];
+      if (!allowed.includes(field))
+        throw new Error("Observation is outside declared scope");
+    } else {
+      if (
+        typeof o.inputPath !== "string" ||
+        !closure.files.some(
+          (file) => file.path === o.inputPath && file.digest === o.bytesDigest
+        )
+      )
+        throw new Error("Observed data missing from closure");
+      if (!declarations.files.includes(key))
+        throw new Error("Observation is outside declared file scope");
+      if (
+        o.kind === "bytes" &&
+        (typeof o.value !== "string" ||
+          !/^0x(?:[0-9a-f]{2})*$/.test(o.value) ||
+          bytesHash(Buffer.from(o.value.slice(2), "hex")) !== o.bytesDigest)
+      )
+        throw new Error("Invalid captured bytes observation");
+    }
+    if (
+      o.kind === "resolve"
+        ? o.bytesDigest !== null
+        : typeof o.bytesDigest !== "string" ||
+          !/^[a-f0-9]{64}$/.test(o.bytesDigest)
+    )
+      throw new Error("Invalid observed bytes digest");
+  }
+  return deepFreeze(canonicalData(e) as unknown as CustomEvidence);
+}

package/runtime/delivery/custom.ts

@@ -0,0 +1,219 @@
+import { parseCustomStep, parseCustomOperations, parseDeclarations, type CustomEvidence, type CustomObservation } from "./custom-format";
+export { parseCustomEvidence, parseCustomStep, parseCustomOperations, parseNativeOperation, type CustomEvidence, type CustomObservation } from "./custom-format";
+import { ownPath, strictData } from "./data";
+import { parseInputDocument } from './input-files';
+/** Bounded module/data/package closure; aggregate release freeze is a separate layer. */
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  CustomModuleClosure,
+  customBusinessRoot,
+  type CustomInputClosure,
+} from "./custom-closure";
+import {
+  deepFreeze,
+  nonempty,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+import type { WorkflowStep } from "../workflow/lib/parameters";
+
+/** Trusted collector session seam. Structurally compatible fake sessions cannot qualify collection. */
+export interface CustomPlanningInputSession {
+  readonly version: 1;
+  evaluate(step: WorkflowStep): Promise<CustomEvidence>;
+}
+const bytesHash = (bytes: Buffer) =>
+  createHash("sha256").update(bytes).digest("hex");
+function readPath(source: unknown, key: string): unknown {
+  return deepFreeze(
+    strictData(ownPath(source, key.split("."), "custom input"))
+  );
+}
+const sessionAuthority = new WeakMap<
+  object,
+  {
+    root: string;
+    businessRoot: string;
+    evaluate(step: WorkflowStep): Promise<CustomEvidence>;
+    seal(): CustomInputClosure;
+    closeReads(): void;
+  }
+>();
+export function ownedCustomSession(
+  session: CustomPlanningInputSession,
+  root: string,
+  businessRoot: string
+) {
+  const owned = sessionAuthority.get(session);
+  if (
+    !owned ||
+    owned.root !== fs.realpathSync(root) ||
+    owned.businessRoot !== customBusinessRoot(root, businessRoot)
+  )
+    throw new Error(
+      "Custom planning requires collector-owned session authority"
+    );
+  return owned;
+}
+interface CustomSessionInputs {
+  root: string;
+  businessRoot: string;
+  params: Record<string, unknown>;
+  state: Record<string, unknown> | (() => Record<string, unknown>);
+  target: Record<string, unknown>;
+}
+export class CustomPlanningSession implements CustomPlanningInputSession {
+  #closure: CustomModuleClosure;
+  #lifecycle = {closed:false};
+  readonly version = 1 as const;
+  constructor(input: CustomSessionInputs) {
+    const businessRoot = customBusinessRoot(input.root, input.businessRoot);
+    this.#input = { ...input, businessRoot };
+    this.#closure = new CustomModuleClosure(input.root);
+    sessionAuthority.set(
+      this,
+      Object.freeze({
+        root: fs.realpathSync(input.root),
+        businessRoot,
+        evaluate: (step: WorkflowStep) => this.#evaluate(step),
+        seal: () => this.#closure.seal(),
+        closeReads: () => {this.#lifecycle.closed=true;this.#closure.closeReads();},
+      })
+    );
+  }
+  readonly #input: CustomSessionInputs;
+  /** Target-specific ports share the same collector, captured bytes and session union. */
+  forTarget(input: Omit<CustomSessionInputs, "root">): CustomPlanningSession {
+    if(this.#lifecycle.closed)throw new Error("Custom input session is closed");
+    const session = new CustomPlanningSession({
+      ...input,
+      root: this.#input.root,
+    });
+    session.#closure = this.#closure;
+    session.#lifecycle=this.#lifecycle;
+    return session;
+  }
+  sealClosure(): CustomInputClosure {
+    return this.#closure.seal();
+  }
+  evaluate(step: WorkflowStep): Promise<CustomEvidence> {
+    return this.#evaluate(step);
+  }
+  async #evaluate(step: WorkflowStep): Promise<CustomEvidence> {
+    if(this.#lifecycle.closed)throw new Error("Custom input session is closed");
+    const s = parseCustomStep(step);
+    const declarations = parseDeclarations(s.reads);
+    const observations: CustomObservation[] = [];
+    const observe = (
+      kind: CustomObservation["kind"],
+      key: string,
+      value: unknown,
+      bytesDigest: string | null = null,
+      inputPath: string | null = null
+    ) => {
+      const immutable = deepFreeze(strictData(value));
+      observations.push({
+        kind,
+        key,
+        value: immutable,
+        digest: semanticHash(immutable),
+        bytesDigest,
+        inputPath,
+      });
+      return immutable;
+    };
+    let open = true;
+    const assertOpen = () => {
+      if (!open) throw new Error("Custom input session is closed");
+    };
+    const read = (name: string) => {
+      assertOpen();
+      if (!declarations.files.includes(name))
+        throw new Error("Undeclared file read");
+      return this.#closure.readData(this.#input.businessRoot, name);
+    };
+    const ports = Object.freeze({
+      readJson: async (name: string) => {
+        const { bytes, path: inputPath } = read(name);
+        return observe(
+          "json",
+          name,
+          parseInputDocument(bytes, 'json'),
+          bytesHash(bytes),
+          inputPath
+        );
+      },
+      readBytes: async (name: string) => {
+        const { bytes, path: inputPath } = read(name);
+        return observe(
+          "bytes",
+          name,
+          "0x" + bytes.toString("hex"),
+          bytesHash(bytes),
+          inputPath
+        );
+      },
+      resolve: (key: string) => {
+        assertOpen();
+        const dot = key.indexOf("."),
+          scope = key.slice(0, dot),
+          field = key.slice(dot + 1);
+        const list =
+          scope === "param"
+            ? declarations.params
+            : scope === "state"
+            ? declarations.state
+            : scope === "target"
+            ? declarations.target
+            : [];
+        if (!list.includes(field))
+          throw new Error("Undeclared input resolution");
+        const source =
+          scope === "param"
+            ? this.#input.params
+            : scope === "target"
+            ? this.#input.target
+            : typeof this.#input.state === "function"
+            ? this.#input.state()
+            : this.#input.state;
+        return observe("resolve", key, readPath(source, field));
+      },
+    });
+    const loaded = this.#closure.load(nonempty(s.script, "script"));
+    const moduleIdentity = loaded.identity;
+    let operations: WorkflowStep[];
+    try {
+      const mod = loaded.module;
+      if (
+        !mod ||
+        ["default", "main", "run"].some((k) => Object.hasOwn(mod, k)) ||
+        typeof mod.planOperations !== "function"
+      )
+        throw new Error(
+          "Custom planning must export planOperations; legacy exports are rejected"
+        );
+      operations = parseCustomOperations(
+        this.#closure.normalize(
+          await mod.planOperations(
+            ports,
+            deepFreeze(strictData(s.input ?? null))
+          )
+        )
+      );
+      this.#closure.assertUnchanged();
+    } finally {
+      open = false;
+    }
+    const body = {
+      version: 1 as const,
+      sourceStepId: s.id,
+      module: moduleIdentity,
+      input: s.input ?? null,
+      declarations,
+      operations,
+      observations,
+      closure: this.#closure.seal(),
+    };
+    return deepFreeze({ ...body, evidenceHash: semanticHash(body) });
+  }
+}