owlrunkit 0.13.0

package/scripts/runkit-contract/receipt-lineage.mjs

@@ -0,0 +1,332 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { isDirectExecution } from "./core-contract.mjs";
+
+const SHA256_PATTERN = /^[a-f0-9]{64}$/i;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+
+  return value;
+}
+
+function issue(code, message, extra = {}) {
+  return { code, ...extra, message };
+}
+
+function malformedResult(issues) {
+  return {
+    valid: false,
+    malformed: true,
+    active: null,
+    superseded: [],
+    issues,
+  };
+}
+
+function normalizedSha256(value) {
+  return typeof value === "string" && SHA256_PATTERN.test(value)
+    ? value.toLowerCase()
+    : null;
+}
+
+export function receiptSha256(receipt) {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalize(receipt)))
+    .digest("hex");
+}
+
+function validateEntryShapes(entries) {
+  if (!Array.isArray(entries)) {
+    return [issue("entries_not_array", "Receipt lineage input must be an entries array.")];
+  }
+
+  const issues = [];
+  for (const [index, entry] of entries.entries()) {
+    if (!isRecord(entry)) {
+      issues.push(issue(
+        "entry_not_object",
+        "Each receipt lineage entry must be an object.",
+        { index },
+      ));
+      continue;
+    }
+
+    if (!normalizedSha256(entry.receiptSha256)) {
+      issues.push(issue(
+        "malformed_receipt_sha256",
+        "receiptSha256 must be a 64-character hexadecimal SHA-256.",
+        { index },
+      ));
+    }
+    if (!isRecord(entry.receipt)) {
+      issues.push(issue(
+        "receipt_not_object",
+        "Each receipt lineage entry must contain a receipt object.",
+        { index },
+      ));
+    } else if (
+      typeof entry.receipt.status !== "string"
+      || entry.receipt.status.trim().length === 0
+    ) {
+      issues.push(issue(
+        "malformed_receipt_status",
+        "Each receipt object must contain a non-empty status string.",
+        { index },
+      ));
+    }
+    if (
+      "parentReceiptSha256" in entry
+      && entry.parentReceiptSha256 !== undefined
+      && !normalizedSha256(entry.parentReceiptSha256)
+    ) {
+      issues.push(issue(
+        "malformed_parent_receipt_sha256",
+        "parentReceiptSha256 must be a 64-character hexadecimal SHA-256 when present.",
+        { index },
+      ));
+    }
+    if (
+      isRecord(entry.receipt)
+      && "supersedesReceiptSha256" in entry.receipt
+      && entry.receipt.supersedesReceiptSha256 !== undefined
+      && !normalizedSha256(entry.receipt.supersedesReceiptSha256)
+    ) {
+      issues.push(issue(
+        "malformed_supersedes_receipt_sha256",
+        "supersedesReceiptSha256 must be a 64-character hexadecimal SHA-256 when present.",
+        { index },
+      ));
+    }
+  }
+  return issues;
+}
+
+export function validateReceiptLineage(entries) {
+  const shapeIssues = validateEntryShapes(entries);
+  if (shapeIssues.length > 0) return malformedResult(shapeIssues);
+
+  const childrenByParent = new Map();
+  const issues = [];
+  const entriesByHash = new Map();
+  const indexByHash = new Map();
+
+  for (const [index, entry] of entries.entries()) {
+    const receiptHash = normalizedSha256(entry.receiptSha256);
+    if (entriesByHash.has(receiptHash)) {
+      issues.push(issue(
+        "duplicate_receipt_sha256",
+        "Each receipt SHA-256 must be globally unique in the lineage.",
+        { receiptSha256: receiptHash },
+      ));
+      continue;
+    }
+    entriesByHash.set(receiptHash, entry);
+    indexByHash.set(receiptHash, index);
+  }
+
+  for (const entry of entries) {
+    const receiptHash = normalizedSha256(entry.receiptSha256);
+    if (receiptSha256(entry.receipt) !== receiptHash) {
+      issues.push(issue(
+        "receipt_hash_mismatch",
+        "The declared receipt SHA-256 does not match the receipt content.",
+        { receiptSha256: receiptHash },
+      ));
+    }
+  }
+
+  for (const [index, entry] of entries.entries()) {
+    if (!entry.parentReceiptSha256) continue;
+
+    const receiptHash = normalizedSha256(entry.receiptSha256);
+    const parentHash = normalizedSha256(entry.parentReceiptSha256);
+    const children = childrenByParent.get(parentHash) ?? [];
+    children.push(receiptHash);
+    childrenByParent.set(parentHash, children);
+
+    const parent = entriesByHash.get(parentHash);
+    if (!parent) {
+      issues.push(issue(
+        "parent_not_found",
+        "The replacement references a receipt SHA-256 that is not present.",
+        { receiptSha256: receiptHash, parentReceiptSha256: parentHash },
+      ));
+    } else if (parent.receipt.status !== "invalidated_by_concurrent_write") {
+      const declaredSupersedes = normalizedSha256(entry.receipt.supersedesReceiptSha256);
+      if (declaredSupersedes !== parentHash) {
+        issues.push(issue(
+          declaredSupersedes === null
+            ? "parent_not_invalidated_by_concurrent_write"
+            : "supersedes_receipt_sha256_mismatch",
+          declaredSupersedes === null
+            ? "A passed parent requires an explicit repair supersedes binding."
+            : "The replacement receipt supersedes hash must match its lineage parent.",
+          {
+            receiptSha256: receiptHash,
+            parentReceiptSha256: parentHash,
+            supersedesReceiptSha256: declaredSupersedes,
+          },
+        ));
+      } else if (
+        parent.receipt.status !== "passed"
+        || entry.receipt.status !== "passed"
+        || typeof parent.receipt.sourceFingerprint !== "string"
+        || typeof entry.receipt.sourceFingerprint !== "string"
+        || parent.receipt.sourceFingerprint === entry.receipt.sourceFingerprint
+      ) {
+        issues.push(issue(
+          "invalid_repair_supersedes_edge",
+          "An explicit repair supersedes edge requires passed receipts bound to different source fingerprints.",
+          { receiptSha256: receiptHash, parentReceiptSha256: parentHash },
+        ));
+      }
+    } else if (
+      entry.receipt.supersedesReceiptSha256 !== undefined
+      && normalizedSha256(entry.receipt.supersedesReceiptSha256) !== parentHash
+    ) {
+      issues.push(issue(
+        "supersedes_receipt_sha256_mismatch",
+        "The replacement receipt supersedes hash must match its lineage parent.",
+        {
+          receiptSha256: receiptHash,
+          parentReceiptSha256: parentHash,
+          supersedesReceiptSha256: normalizedSha256(entry.receipt.supersedesReceiptSha256),
+        },
+      ));
+    }
+
+    const parentIndex = indexByHash.get(parentHash);
+    if (parentIndex !== undefined && parentIndex >= index) {
+      issues.push(issue(
+        "parent_not_prior",
+        "An append-only replacement must reference an earlier receipt entry.",
+        { receiptSha256: receiptHash, parentReceiptSha256: parentHash },
+      ));
+    }
+  }
+
+  for (const [parentReceiptSha256, children] of childrenByParent) {
+    if (children.length > 1) {
+      issues.push(issue(
+        "lineage_branch_detected",
+        "An append-only receipt may have at most one direct replacement.",
+        { parentReceiptSha256, childReceiptSha256Values: children },
+      ));
+    }
+  }
+
+  const visitState = new Map();
+  let cycleDetected = false;
+
+  function visit(receiptHash) {
+    const state = visitState.get(receiptHash);
+    if (state === "visiting") {
+      cycleDetected = true;
+      return;
+    }
+    if (state === "visited") return;
+
+    visitState.set(receiptHash, "visiting");
+    const parentHash = normalizedSha256(
+      entriesByHash.get(receiptHash)?.parentReceiptSha256,
+    );
+    if (parentHash && entriesByHash.has(parentHash)) visit(parentHash);
+    visitState.set(receiptHash, "visited");
+  }
+
+  for (const receiptHash of entriesByHash.keys()) visit(receiptHash);
+
+  if (cycleDetected) {
+    issues.push(issue(
+      "cycle_detected",
+      "Receipt replacement references must form an acyclic lineage.",
+    ));
+  }
+
+  const activeEntries = entries.filter(
+    (entry) => !childrenByParent.has(normalizedSha256(entry.receiptSha256)),
+  );
+  const active = activeEntries.length === 1 ? activeEntries[0] : null;
+  const superseded = entries.filter((entry) =>
+    childrenByParent.has(normalizedSha256(entry.receiptSha256)),
+  );
+
+  if (activeEntries.length > 1) {
+    issues.push(issue(
+      "multiple_active_leaves",
+      "A valid receipt lineage must have exactly one active leaf.",
+      {
+        receiptSha256Values: activeEntries.map((entry) =>
+          normalizedSha256(entry.receiptSha256)),
+      },
+    ));
+  } else if (activeEntries.length === 0 && !cycleDetected) {
+    issues.push(issue(
+      "no_active_leaf",
+      "A valid receipt lineage must have one active leaf.",
+    ));
+  }
+
+  return {
+    valid: active !== null && issues.length === 0,
+    malformed: false,
+    active,
+    superseded,
+    issues,
+  };
+}
+
+function cliFailure(code, message) {
+  return malformedResult([issue(code, message)]);
+}
+
+export async function runCli(args = process.argv.slice(2)) {
+  if (args.length !== 1) {
+    return {
+      exitCode: 3,
+      output: cliFailure(
+        "usage_error",
+        "Usage: receipt-lineage.mjs <receipt-array.json>",
+      ),
+    };
+  }
+
+  let document;
+  try {
+    document = JSON.parse(await readFile(args[0], "utf8"));
+  } catch (error) {
+    return {
+      exitCode: 3,
+      output: cliFailure("input_error", error.message),
+    };
+  }
+
+  const entries = Array.isArray(document) ? document : document?.receipts;
+  const output = validateReceiptLineage(entries);
+  return {
+    exitCode: output.malformed ? 3 : output.valid ? 0 : 2,
+    output,
+  };
+}
+
+if (isDirectExecution(import.meta.url)) {
+  const { exitCode, output } = await runCli();
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  process.exitCode = exitCode;
+}

package/scripts/runkit-contract/registry-adoption-gate.mjs

@@ -0,0 +1,117 @@
+export const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org";
+
+const REQUIRED_INSTALL_FIELDS = Object.freeze([
+  "requestedSpec",
+  "packageName",
+  "version",
+  "shasum",
+  "integrity",
+  "resolved",
+]);
+
+const RELEASE_EVIDENCE_FIELDS = Object.freeze([
+  "authorizationGranted",
+  "integrity",
+  "packageName",
+  "registry",
+  "schemaVersion",
+  "shasum",
+  "status",
+  "tarballUrl",
+  "version",
+]);
+
+function decision(policy, issueCodes) {
+  return {
+    schemaVersion: "OwlCodaRunKitRegistryAdoptionDecisionV1",
+    decision: issueCodes.length === 0 ? "ELIGIBLE" : "INELIGIBLE",
+    issueCodes,
+    packageName: policy.packageName,
+    version: policy.candidateVersion,
+    authorizationGranted: false,
+  };
+}
+
+function expectedTarballUrl(policy) {
+  const tarballName = policy.packageName.split("/").at(-1);
+  return `${OFFICIAL_NPM_REGISTRY}/${policy.packageName}/-/${tarballName}-${policy.candidateVersion}.tgz`;
+}
+
+function validSha512Integrity(value) {
+  if (typeof value !== "string") return false;
+  const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match) return false;
+  const bytes = Buffer.from(match[1], "base64");
+  return bytes.length === 64 && bytes.toString("base64") === match[1];
+}
+
+function validReleaseEvidence(policy, release) {
+  if (
+    policy.registry !== OFFICIAL_NPM_REGISTRY
+    || Object.keys(release).sort().join("\n") !== RELEASE_EVIDENCE_FIELDS.join("\n")
+    || !/^[0-9a-f]{40}$/.test(release.shasum)
+    || !validSha512Integrity(release.integrity)
+    || release.tarballUrl !== expectedTarballUrl(policy)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function evaluateRegistryAdoption({ policy, releaseEvidence, install }) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new TypeError("Registry release policy must be an object.");
+  }
+  if (!install || typeof install !== "object" || Array.isArray(install)) {
+    return decision(policy, ["registry_install_binding_missing"]);
+  }
+  if (install.kind !== "registry") {
+    return decision(policy, ["registry_source_required"]);
+  }
+  if (REQUIRED_INSTALL_FIELDS.some((field) =>
+    typeof install[field] !== "string" || install[field].length === 0)) {
+    return decision(policy, ["registry_install_binding_missing"]);
+  }
+  if (
+    !releaseEvidence
+    || typeof releaseEvidence !== "object"
+    || Array.isArray(releaseEvidence)
+    || releaseEvidence.schemaVersion !== policy.registryEvidenceSchemaVersion
+    || releaseEvidence.status !== "registry_verified"
+    || releaseEvidence.authorizationGranted !== false
+  ) {
+    return decision(policy, ["registry_release_not_verified"]);
+  }
+
+  const release = releaseEvidence;
+  if (!validReleaseEvidence(policy, release)) {
+    return decision(policy, ["registry_release_evidence_invalid"]);
+  }
+  if (
+    release.registry !== policy.registry
+    || release.packageName !== policy.packageName
+    || release.version !== policy.candidateVersion
+  ) {
+    return decision(policy, ["registry_release_evidence_mismatch"]);
+  }
+  const expectedSpec = `${policy.packageName}@${release.version}`;
+  if (install.requestedSpec !== expectedSpec) {
+    return decision(policy, ["registry_exact_version_required"]);
+  }
+  if (install.packageName !== release.packageName) {
+    return decision(policy, ["registry_package_name_mismatch"]);
+  }
+  if (install.version !== release.version) {
+    return decision(policy, ["registry_version_mismatch"]);
+  }
+  if (install.shasum !== release.shasum) {
+    return decision(policy, ["registry_shasum_mismatch"]);
+  }
+  if (install.integrity !== release.integrity) {
+    return decision(policy, ["registry_integrity_mismatch"]);
+  }
+  if (install.resolved !== release.tarballUrl) {
+    return decision(policy, ["registry_tarball_url_mismatch"]);
+  }
+  return decision(policy, []);
+}