@kungfu-tech/buildchain 3.0.5 → 3.0.6-alpha.0

package/packages/core/workflow-call-contract.js

@@ -0,0 +1,308 @@
+import crypto from "node:crypto";
+import { parseWorkflowDocument } from "./workflow-yaml-contract.js";
+
+export const WORKFLOW_CALL_CONTRACT =
+  "kungfu-buildchain-workflow-call-contract/v1";
+export const WORKFLOW_CALL_RECEIPT =
+  "kungfu-buildchain-workflow-call-receipt/v1";
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+
+function exactSha(value) {
+  return /^[0-9a-f]{40}$/.test(String(value || "").toLowerCase());
+}
+
+function coordinate(uses) {
+  const match = String(uses || "").match(
+    /^([^/]+\/[^/]+)\/(\.github\/workflows\/[^@]+)@([^@]+)$/,
+  );
+  return match ? { repository: match[1], path: match[2], ref: match[3] } : null;
+}
+
+function permissionLevel(value) {
+  if (value === "write" || value === "write-all") return 2;
+  if (value === "read" || value === "read-all") return 1;
+  if (value === "none" || value === "{}") return 0;
+  return -1;
+}
+
+function callerPermission(permissions, name) {
+  return permissions[name] || permissions["*"] || "none";
+}
+
+function validatePermissions(caller, callee) {
+  const failures = [];
+  for (const [name, required] of Object.entries(callee)) {
+    if (name === "*") continue;
+    const available = callerPermission(caller, name);
+    if (
+      permissionLevel(required) < 0 ||
+      permissionLevel(available) < permissionLevel(required)
+    ) {
+      failures.push({
+        code: "permission-drift",
+        message: `caller permission ${name}=${available} does not satisfy callee ${required}`,
+      });
+    }
+  }
+  return failures;
+}
+
+function validateInputs(job, reusable) {
+  const failures = [];
+  const declared = new Map(reusable.inputs.map((entry) => [entry.name, entry]));
+  for (const [name, supplied] of Object.entries(job.with)) {
+    const input = declared.get(name);
+    if (!input) {
+      failures.push({
+        code: "undeclared-input",
+        message: `caller supplies undeclared input: ${name}`,
+      });
+      continue;
+    }
+    if (supplied.kind !== "expression" && supplied.kind !== input.type) {
+      failures.push({
+        code: "input-type-drift",
+        message: `caller input ${name} is ${supplied.kind}, callee requires ${input.type}`,
+      });
+    }
+  }
+  for (const input of reusable.inputs.filter((entry) => entry.required)) {
+    if (!(input.name in job.with)) {
+      failures.push({
+        code: "missing-required-input",
+        message: `caller omits required input: ${input.name}`,
+      });
+    }
+  }
+  return failures;
+}
+
+function validateSecrets(job, reusable) {
+  if (job.secrets === "inherit") {
+    return [
+      {
+        code: "secret-inheritance-not-exact",
+        message:
+          "secrets: inherit cannot prove an exact reusable-workflow secret contract",
+      },
+    ];
+  }
+  const failures = [];
+  const declared = new Map(
+    reusable.secrets.map((entry) => [entry.name, entry]),
+  );
+  for (const name of Object.keys(job.secrets)) {
+    if (!declared.has(name)) {
+      failures.push({
+        code: "undeclared-secret",
+        message: `caller supplies undeclared secret: ${name}`,
+      });
+    }
+  }
+  for (const secret of reusable.secrets.filter((entry) => entry.required)) {
+    if (!(secret.name in job.secrets)) {
+      failures.push({
+        code: "missing-required-secret",
+        message: `caller omits required secret: ${secret.name}`,
+      });
+    }
+  }
+  return failures;
+}
+
+function validateEvents(actual, trusted) {
+  const trustedSet = new Set(trusted);
+  return actual
+    .filter((event) => !trustedSet.has(event))
+    .map((event) => ({
+      code: "untrusted-event-drift",
+      message: `caller admits untrusted event class: ${event}`,
+    }));
+}
+
+function interfaceProjection(reusable) {
+  return {
+    inputs: reusable.inputs,
+    secrets: reusable.secrets,
+    outputs: reusable.outputs,
+    permissions: reusable.permissions,
+  };
+}
+
+function validateCoordinate(job, { repository, workflowPath, sha }) {
+  const failures = [];
+  const pinned = coordinate(job?.uses);
+  if (!pinned) {
+    return [
+      {
+        code: "callee-coordinate-invalid",
+        message:
+          "caller uses must name owner/repo/.github/workflows/file.yml@ref",
+      },
+    ];
+  }
+  if (!exactSha(pinned.ref)) {
+    failures.push({
+      code: "floating-callee-ref",
+      message: `callee ref is not an exact commit SHA: ${pinned.ref}`,
+    });
+  }
+  if (pinned.repository !== repository || pinned.path !== workflowPath) {
+    failures.push({
+      code: "callee-coordinate-drift",
+      message: `caller uses ${pinned.repository}/${pinned.path}, expected ${repository}/${workflowPath}`,
+    });
+  }
+  if (pinned.ref.toLowerCase() !== String(sha || "").toLowerCase()) {
+    failures.push({
+      code: "stale-pinned-ref",
+      message: `caller pin ${pinned.ref} does not match checked callee ${sha}`,
+    });
+  }
+  return failures;
+}
+
+export function evaluateWorkflowCallContract({
+  callerText,
+  calleeText,
+  callerRepository,
+  callerWorkflowPath,
+  callerSha,
+  callerTree,
+  callerSourceState = "clean",
+  calleeRepository,
+  calleeWorkflowPath,
+  calleeSha,
+  jobId,
+  trustedEventClasses = [],
+  expectedContractRoot = "",
+} = {}) {
+  const caller = parseWorkflowDocument(callerText);
+  const callee = parseWorkflowDocument(calleeText);
+  const job = caller.callJobs.find((entry) => entry.id === jobId);
+  const failures = [];
+  if (!job)
+    failures.push({
+      code: "call-job-missing",
+      message: `reusable-workflow call job is missing: ${jobId}`,
+    });
+  if (!callee.interface.reusable)
+    failures.push({
+      code: "callee-not-reusable",
+      message: "callee does not declare on.workflow_call",
+    });
+
+  failures.push(
+    ...validateCoordinate(job, {
+      repository: calleeRepository,
+      workflowPath: calleeWorkflowPath,
+      sha: calleeSha,
+    }),
+  );
+  if (!exactSha(calleeSha))
+    failures.push({
+      code: "callee-sha-invalid",
+      message: "callee SHA must be an exact 40-character commit",
+    });
+  if (!exactSha(callerSha) || !exactSha(callerTree))
+    failures.push({
+      code: "caller-source-invalid",
+      message: "caller SHA and tree must be exact 40-character Git object ids",
+    });
+
+  if (job && callee.interface.reusable) {
+    failures.push(...validateInputs(job, callee.interface));
+    failures.push(...validateSecrets(job, callee.interface));
+    failures.push(
+      ...validatePermissions(job.permissions, callee.interface.permissions),
+    );
+  }
+  failures.push(...validateEvents(caller.triggers, trustedEventClasses));
+
+  const contract = {
+    schema: WORKFLOW_CALL_CONTRACT,
+    caller: {
+      repository: callerRepository,
+      workflowPath: callerWorkflowPath,
+      workflowDigest: sha256(String(callerText || "")),
+      jobId,
+      eventClasses: caller.triggers,
+      uses: job?.uses || "",
+      inputs: job?.with || {},
+      secretNames:
+        job?.secrets === "inherit"
+          ? ["*"]
+          : Object.keys(job?.secrets || {}).sort(),
+      permissions: job?.permissions || {},
+    },
+    callee: {
+      repository: calleeRepository,
+      workflowPath: calleeWorkflowPath,
+      sha: String(calleeSha || "").toLowerCase(),
+      workflowDigest: sha256(String(calleeText || "")),
+      interface: interfaceProjection(callee.interface),
+    },
+    trustedEventClasses: [...new Set(trustedEventClasses)].sort(),
+  };
+  const contractRoot = sha256(stableJson(contract));
+  if (expectedContractRoot && expectedContractRoot !== contractRoot) {
+    failures.push({
+      code: "contract-root-mismatch",
+      message: `workflow call contract root ${contractRoot} does not match accepted ${expectedContractRoot}`,
+    });
+  }
+  const receipt = {
+    schema: WORKFLOW_CALL_RECEIPT,
+    contractRoot,
+    caller: {
+      repository: callerRepository,
+      sha: String(callerSha || "").toLowerCase(),
+      tree: String(callerTree || "").toLowerCase(),
+      sourceState: callerSourceState,
+      workflowPath: callerWorkflowPath,
+      workflowDigest: contract.caller.workflowDigest,
+    },
+    callee: {
+      repository: calleeRepository,
+      sha: String(calleeSha || "").toLowerCase(),
+      workflowPath: calleeWorkflowPath,
+      workflowDigest: contract.callee.workflowDigest,
+    },
+    eventClasses: caller.triggers,
+  };
+  return {
+    schema: "kungfu-buildchain-workflow-call-check/v1",
+    ok: failures.length === 0,
+    status: failures.length === 0 ? "passed" : "failed",
+    failures,
+    contract,
+    contractRoot,
+    receipt,
+    receiptRoot: sha256(stableJson(receipt)),
+    receiptReusable: failures.length === 0 && callerSourceState === "clean",
+  };
+}
+
+export function assertWorkflowCallContract(options) {
+  const report = evaluateWorkflowCallContract(options);
+  if (!report.ok) {
+    throw new Error(
+      `Reusable workflow call contract failed:\n${report.failures.map((entry) => `${entry.code}: ${entry.message}`).join("\n")}`,
+    );
+  }
+  return report;
+}

package/packages/core/workflow-yaml-contract.js

@@ -0,0 +1,272 @@
+function indentation(line) {
+  return line.match(/^(\s*)/)?.[1].length || 0;
+}
+
+function stripComment(value) {
+  let quote = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if ((char === '"' || char === "'") && value[index - 1] !== "\\") {
+      quote = quote === char ? "" : quote || char;
+    }
+    if (
+      char === "#" &&
+      !quote &&
+      (index === 0 || /\s/.test(value[index - 1]))
+    ) {
+      return value.slice(0, index).trimEnd();
+    }
+  }
+  return value.trimEnd();
+}
+
+function unquote(value) {
+  const trimmed = stripComment(String(value || "").trim());
+  if (
+    trimmed.length >= 2 &&
+    trimmed[0] === trimmed.at(-1) &&
+    ['"', "'"].includes(trimmed[0])
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function blockValue(lines, entry) {
+  if (!/^[>|][+-]?$/.test(entry.value)) return entry.value;
+  const values = [];
+  for (let index = entry.line + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() && indentation(line) <= entry.indent) break;
+    values.push(line);
+  }
+  const content = values.filter((line) => line.trim());
+  const contentIndent = content.length
+    ? Math.min(...content.map(indentation))
+    : entry.indent + 2;
+  return values
+    .map((line) => line.slice(Math.min(contentIndent, line.length)))
+    .join("\n")
+    .trimEnd();
+}
+
+function directEntries(lines, parentLine) {
+  const parentIndent = indentation(lines[parentLine]);
+  let childIndent = null;
+  for (let index = parentLine + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = indentation(line);
+    if (indent <= parentIndent) break;
+    childIndent = childIndent === null ? indent : Math.min(childIndent, indent);
+  }
+  if (childIndent === null) return [];
+  const entries = [];
+  for (let index = parentLine + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+    const indent = indentation(line);
+    if (trimmed && indent <= parentIndent) break;
+    if (!trimmed || trimmed.startsWith("#") || indent !== childIndent)
+      continue;
+    const match = line.match(/^\s*([A-Za-z0-9_.-]+):(?:\s*(.*))?$/);
+    if (match) {
+      entries.push({
+        key: match[1],
+        value: stripComment(match[2] || ""),
+        line: index,
+        indent,
+      });
+    }
+  }
+  return entries;
+}
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function topLevelEntry(lines, key) {
+  const pattern = new RegExp(
+    `^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(?:\\s*(.*))?$`,
+  );
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(pattern);
+    if (match)
+      return {
+        key,
+        value: stripComment(match[1] || ""),
+        line: index,
+        indent: 0,
+      };
+  }
+  return null;
+}
+
+function childEntry(lines, parent, key) {
+  return (
+    directEntries(lines, parent.line).find((entry) => entry.key === key) || null
+  );
+}
+
+function scalar(value) {
+  const raw = stripComment(String(value || "").trim());
+  if (raw.length >= 2 && raw[0] === raw.at(-1) && ['"', "'"].includes(raw[0])) {
+    return { kind: "string", value: raw.slice(1, -1) };
+  }
+  const text = unquote(raw);
+  if (/^\$\{\{[\s\S]*\}\}$/.test(text))
+    return { kind: "expression", value: text };
+  if (/^(true|false)$/i.test(text))
+    return { kind: "boolean", value: text.toLowerCase() === "true" };
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(text))
+    return { kind: "number", value: Number(text) };
+  if (/^(null|~)$/i.test(text)) return { kind: "null", value: null };
+  return { kind: "string", value: text };
+}
+
+function parsePermissions(lines, entry) {
+  if (!entry) return {};
+  if (entry.value) return { "*": unquote(entry.value) };
+  return Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      unquote(item.value),
+    ]),
+  );
+}
+
+function parseTriggers(lines) {
+  const on = topLevelEntry(lines, "on");
+  if (!on) return [];
+  if (on.value) {
+    const inline = unquote(on.value);
+    if (inline.startsWith("[") && inline.endsWith("]")) {
+      return inline
+        .slice(1, -1)
+        .split(",")
+        .map((value) => unquote(value.trim()))
+        .filter(Boolean)
+        .sort();
+    }
+    return inline ? [inline] : [];
+  }
+  const events = [];
+  for (const event of directEntries(lines, on.line)) {
+    const types = childEntry(lines, event, "types");
+    const rawTypes = types ? unquote(types.value) : "";
+    if (rawTypes.startsWith("[") && rawTypes.endsWith("]")) {
+      for (const type of rawTypes
+        .slice(1, -1)
+        .split(",")
+        .map((value) => unquote(value.trim()))
+        .filter(Boolean)) {
+        events.push(`${event.key}:${type}`);
+      }
+    } else {
+      events.push(event.key);
+    }
+  }
+  return [...new Set(events)].sort();
+}
+
+function definition(lines, entry) {
+  const properties = Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      blockValue(lines, item),
+    ]),
+  );
+  return {
+    name: entry.key,
+    type: unquote(properties.type || "string"),
+    required: scalar(properties.required || "false").value === true,
+    default:
+      properties.default === undefined ? null : scalar(properties.default),
+  };
+}
+
+export function parseReusableWorkflowInterface(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const on = topLevelEntry(lines, "on");
+  const workflowCall = on && childEntry(lines, on, "workflow_call");
+  if (!workflowCall) {
+    return {
+      reusable: false,
+      inputs: [],
+      secrets: [],
+      outputs: [],
+      permissions: parsePermissions(lines, topLevelEntry(lines, "permissions")),
+    };
+  }
+  const inputs = childEntry(lines, workflowCall, "inputs");
+  const secrets = childEntry(lines, workflowCall, "secrets");
+  const outputs = childEntry(lines, workflowCall, "outputs");
+  return {
+    reusable: true,
+    inputs: inputs
+      ? directEntries(lines, inputs.line)
+          .map((entry) => definition(lines, entry))
+          .sort((a, b) => compareCodeUnits(a.name, b.name))
+      : [],
+    secrets: secrets
+      ? directEntries(lines, secrets.line)
+          .map((entry) => definition(lines, entry))
+          .sort((a, b) => compareCodeUnits(a.name, b.name))
+      : [],
+    outputs: outputs
+      ? directEntries(lines, outputs.line)
+          .map((entry) => entry.key)
+          .sort()
+      : [],
+    permissions: parsePermissions(lines, topLevelEntry(lines, "permissions")),
+  };
+}
+
+function parseJobMap(lines, entry) {
+  if (!entry) return {};
+  return Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      scalar(blockValue(lines, item)),
+    ]),
+  );
+}
+
+export function parseWorkflowCallJobs(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const jobs = topLevelEntry(lines, "jobs");
+  if (!jobs) return [];
+  const topPermissions = parsePermissions(
+    lines,
+    topLevelEntry(lines, "permissions"),
+  );
+  return directEntries(lines, jobs.line)
+    .map((job) => {
+      const properties = directEntries(lines, job.line);
+      const property = (name) =>
+        properties.find((entry) => entry.key === name) || null;
+      const secrets = property("secrets");
+      return {
+        id: job.key,
+        uses: unquote(property("uses")?.value || ""),
+        with: parseJobMap(lines, property("with")),
+        secrets:
+          secrets?.value === "inherit"
+            ? "inherit"
+            : parseJobMap(lines, secrets),
+        permissions: property("permissions")
+          ? parsePermissions(lines, property("permissions"))
+          : topPermissions,
+      };
+    })
+    .filter((job) => job.uses);
+}
+
+export function parseWorkflowDocument(text) {
+  return {
+    triggers: parseTriggers(String(text || "").split(/\r?\n/)),
+    interface: parseReusableWorkflowInterface(text),
+    callJobs: parseWorkflowCallJobs(text),
+  };
+}