chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/governed-skill-marketplace-candidate.js

@@ -0,0 +1,330 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { types as utilTypes } from "node:util";
+import {
+  SkillCandidateRegistry,
+  SKILL_CANDIDATE_MAX_ARTIFACT_BYTES,
+  verifySkillCandidateDraft,
+} from "./skill-candidate-registry.js";
+
+export const GOVERNED_SKILL_MARKETPLACE_CANDIDATE_BINDING_SCHEMA =
+  "chainlesschain.governed-skill-marketplace-candidate-binding/v1";
+const INSTALLERS = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const BINDING_DIGESTS = [
+  "manifestDigest",
+  "packageDigest",
+  "adaptedOutputDigest",
+  "candidateId",
+  "contentDigest",
+  "dependencyLockDigest",
+  "runtimeManifestDigest",
+  "targetMatrixRoot",
+  "sbomDigest",
+  "permissionManifestDigest",
+  "bindingDigest",
+];
+const BINDING_KEYS = new Set([
+  "schema",
+  "tenantId",
+  "skillName",
+  ...BINDING_DIGESTS,
+]);
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function hash(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function bindingDigest(core) {
+  return hash(
+    `${GOVERNED_SKILL_MARKETPLACE_CANDIDATE_BINDING_SCHEMA}\0${canonical(core)}`,
+  );
+}
+
+export function serializeGovernedSkillMarketplaceCandidatePackage(candidate) {
+  return Buffer.from(
+    `${canonical(verifySkillCandidateDraft(candidate))}\n`,
+    "utf8",
+  );
+}
+
+export function digestGovernedSkillMarketplaceCandidatePermissions(candidate) {
+  const verified = verifySkillCandidateDraft(candidate);
+  return hash(
+    `chainlesschain.governed-skill-marketplace-permissions/v1\0${canonical({
+      tenantId: verified.tenantId,
+      skillName: verified.skillName,
+      requestedCapabilities: verified.requestedCapabilities,
+    })}`,
+  );
+}
+
+export function verifyGovernedSkillMarketplaceCandidateBinding(
+  value,
+  expected,
+) {
+  if (
+    !value ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    throw new TypeError("marketplace candidate binding is invalid");
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== BINDING_KEYS.size ||
+    keys.some((key) => !BINDING_KEYS.has(key))
+  )
+    throw new TypeError("marketplace candidate binding has invalid fields");
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      !descriptor ||
+      !Object.hasOwn(descriptor, "value") ||
+      !descriptor.enumerable
+    )
+      throw new TypeError(
+        "marketplace candidate binding must contain data fields",
+      );
+  }
+  const { bindingDigest: supplied, ...core } = value;
+  if (
+    value.schema !== GOVERNED_SKILL_MARKETPLACE_CANDIDATE_BINDING_SCHEMA ||
+    BINDING_DIGESTS.some(
+      (key) => typeof value[key] !== "string" || !DIGEST.test(value[key]),
+    ) ||
+    supplied !== bindingDigest(core) ||
+    [
+      "tenantId",
+      "skillName",
+      "manifestDigest",
+      "packageDigest",
+      "adaptedOutputDigest",
+    ].some((key) => value[key] !== expected[key])
+  )
+    throw new Error("marketplace candidate binding does not match its state");
+  return Object.freeze({ ...value });
+}
+
+function bytes(value, expectedDigest, name) {
+  if (
+    utilTypes.isProxy(value) ||
+    !Buffer.isBuffer(value) ||
+    value.length === 0 ||
+    value.length > SKILL_CANDIDATE_MAX_ARTIFACT_BYTES
+  )
+    throw new TypeError(`marketplace ${name} must be bounded bytes`);
+  const snapshot = Buffer.from(value);
+  if (hash(snapshot) !== expectedDigest)
+    throw new Error(`marketplace ${name} digest mismatch`);
+  return snapshot;
+}
+
+function parsePackage(value) {
+  let candidate;
+  try {
+    candidate = verifySkillCandidateDraft(
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(value)),
+    );
+  } catch (cause) {
+    throw new Error(
+      "marketplace package is not a verified Candidate v2 artifact",
+      { cause },
+    );
+  }
+  if (
+    !serializeGovernedSkillMarketplaceCandidatePackage(candidate).equals(value)
+  )
+    throw new Error("marketplace candidate package is not canonical");
+  return candidate;
+}
+
+function matchManifest(candidate, manifest) {
+  if (
+    candidate.tenantId !== manifest.tenantId ||
+    candidate.skillName !== manifest.skillName ||
+    candidate.dependencyLockDigest !== manifest.dependencyLockDigest ||
+    candidate.targetMatrixRoot !== manifest.targetMatrixDigest ||
+    digestGovernedSkillMarketplaceCandidatePermissions(candidate) !==
+      manifest.permissionManifestDigest ||
+    candidate.sourceEvidenceRefs.some(
+      ({ digest }) => !manifest.lineage.includes(digest),
+    )
+  )
+    throw new Error(
+      "marketplace candidate provenance, execution or permissions differ from the signed manifest",
+    );
+}
+
+function candidateInput(candidate) {
+  return Object.fromEntries(
+    [
+      "tenantId",
+      "skillName",
+      "content",
+      "dependencyLock",
+      "runtimeManifest",
+      "targetMatrix",
+      "sourceEvidenceRefs",
+      "derivationMode",
+      "wikiRevision",
+      "proposerModel",
+      "parentDigest",
+      "requestedCapabilities",
+    ].map((key) => [key, candidate[key]]),
+  );
+}
+
+export function isGovernedSkillMarketplaceCandidateInstaller(value) {
+  return INSTALLERS.has(value);
+}
+
+/** Owns an actual candidate-only registry; never accepts a caller-supplied write acknowledgement. */
+export function createGovernedSkillMarketplaceCandidateInstaller({
+  tenantId,
+  registryOptions,
+  artifacts,
+} = {}) {
+  const resolve = artifacts?.resolve;
+  if (typeof resolve !== "function")
+    throw new TypeError("marketplace artifact resolver is required");
+  if (
+    !registryOptions ||
+    typeof registryOptions.rootDir !== "string" ||
+    !isAbsolute(registryOptions.rootDir) ||
+    (registryOptions.tenantId !== undefined &&
+      registryOptions.tenantId !== tenantId)
+  )
+    throw new TypeError(
+      "marketplace candidate registry requires an explicit same-tenant root",
+    );
+  const authority = registryOptions.targetMatrixAdmissionAuthority;
+  if (!authority || typeof authority.resolve !== "function")
+    throw new TypeError(
+      "marketplace candidate admission authority is required",
+    );
+  const admissionResolve = authority.resolve;
+  const options = Object.freeze({
+    ...registryOptions,
+    tenantId,
+    targetMatrixAdmissionAuthority: Object.freeze({
+      ...authority,
+      resolve: (...args) => Reflect.apply(admissionResolve, authority, args),
+    }),
+  });
+  // Opening the registry validates every stored artifact. Defer that operation
+  // so a fresh CLI process can still revoke a corrupted candidate using Ledger
+  // authority alone. Materialize/read never fall back to an unverified store.
+  let registry = null;
+  const open = () => (registry ??= new SkillCandidateRegistry(options));
+  const read = (candidateId) => open().read(candidateId);
+  const create = (input) => open().create(input);
+  const verifyStored = (binding) => {
+    const candidate = read(binding.candidateId);
+    if (
+      candidate.tenantId !== tenantId ||
+      candidate.skillName !== binding.skillName ||
+      [
+        "contentDigest",
+        "dependencyLockDigest",
+        "runtimeManifestDigest",
+        "targetMatrixRoot",
+      ].some((key) => candidate[key] !== binding[key]) ||
+      hash(serializeGovernedSkillMarketplaceCandidatePackage(candidate)) !==
+        binding.adaptedOutputDigest ||
+      digestGovernedSkillMarketplaceCandidatePermissions(candidate) !==
+        binding.permissionManifestDigest
+    )
+      throw new Error(
+        "marketplace stored candidate does not match its durable binding",
+      );
+    return binding;
+  };
+  const installer = Object.freeze({
+    tenantId,
+    async materialize(inspected) {
+      const { manifest, adapted, target } = inspected;
+      if (manifest.tenantId !== tenantId)
+        throw new Error("marketplace candidate tenant mismatch");
+      const request = Object.freeze({
+        tenantId,
+        skillName: manifest.skillName,
+        version: manifest.version,
+        packageDigest: manifest.packageDigest,
+        adaptedOutputDigest: adapted.outputDigest,
+        sbomDigest: manifest.sbomDigest,
+      });
+      const resolved = await Reflect.apply(resolve, artifacts, [request]);
+      const sourceBytes = bytes(
+        resolved?.packageBytes,
+        request.packageDigest,
+        "source package",
+      );
+      const adaptedBytes = bytes(
+        resolved?.adaptedBytes,
+        request.adaptedOutputDigest,
+        "adapted package",
+      );
+      bytes(resolved?.sbomBytes, request.sbomDigest, "SBOM");
+      const source = parsePackage(sourceBytes);
+      const candidate = parsePackage(adaptedBytes);
+      matchManifest(source, manifest);
+      matchManifest(candidate, manifest);
+      const runtime = candidate.runtimeManifest.runtimes.find(
+        ({ runtimeId }) => runtimeId === target.tool,
+      );
+      if (
+        !candidate.targetRuntimes.includes(target.tool) ||
+        runtime?.descriptor.platform !== target.os ||
+        runtime.descriptor.runtime !== target.runtime
+      )
+        throw new Error(
+          "marketplace adapted candidate runtime does not match the evaluated target",
+        );
+      const core = {
+        schema: GOVERNED_SKILL_MARKETPLACE_CANDIDATE_BINDING_SCHEMA,
+        tenantId,
+        skillName: manifest.skillName,
+        manifestDigest: manifest.manifestDigest,
+        ...request,
+        candidateId: candidate.candidateId,
+        contentDigest: candidate.contentDigest,
+        dependencyLockDigest: candidate.dependencyLockDigest,
+        runtimeManifestDigest: candidate.runtimeManifestDigest,
+        targetMatrixRoot: candidate.targetMatrixRoot,
+        permissionManifestDigest: manifest.permissionManifestDigest,
+      };
+      delete core.version;
+      const binding = Object.freeze({
+        ...core,
+        bindingDigest: bindingDigest(core),
+      });
+      const result = create(candidateInput(candidate));
+      if (result.candidate.candidateId !== candidate.candidateId)
+        throw new Error(
+          "marketplace candidate registry returned a different candidate",
+        );
+      return verifyStored(binding);
+    },
+    verify(state) {
+      if (state?.tenantId !== tenantId)
+        throw new Error("marketplace candidate tenant mismatch");
+      return verifyStored(
+        verifyGovernedSkillMarketplaceCandidateBinding(
+          state.candidateBinding,
+          state,
+        ),
+      );
+    },
+  });
+  INSTALLERS.add(installer);
+  return installer;
+}

package/src/lib/evolution/governed-skill-marketplace-cli-host.js

@@ -0,0 +1,308 @@
+import { types as utilTypes } from "node:util";
+import { GovernedSkillMarketplace } from "./governed-skill-marketplace.js";
+import { isGovernedSkillMarketplaceLedgerAdapter } from "./governed-skill-marketplace-ledger-adapter.js";
+import { isGovernedSkillMarketplaceCandidateInstaller } from "./governed-skill-marketplace-candidate.js";
+
+const HOSTS = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const TARGET_KEYS = ["model", "os", "runtime", "tool"];
+export const GOVERNED_SKILL_MARKETPLACE_PUBLIC_BADGE_SCHEMA =
+  "chainlesschain.governed-skill-marketplace-public-badge/v1";
+
+function id(value, name) {
+  if (typeof value !== "string" || !ID.test(value))
+    throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function digest(value, name) {
+  if (typeof value !== "string" || !DIGEST.test(value))
+    throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function capture(owner, name) {
+  const callable = owner?.[name];
+  if (typeof callable !== "function")
+    throw new TypeError(`marketplace ${name} port is required`);
+  return (...args) => Reflect.apply(callable, owner, args);
+}
+
+function targetSnapshot(value) {
+  if (
+    !value ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    JSON.stringify(Reflect.ownKeys(value).sort()) !==
+      JSON.stringify(TARGET_KEYS)
+  )
+    throw new TypeError("marketplace deployment target is invalid");
+  const result = {};
+  for (const key of TARGET_KEYS) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !Object.hasOwn(descriptor, "value"))
+      throw new TypeError(
+        "marketplace deployment target must contain data fields",
+      );
+    result[key] = id(descriptor.value, `target ${key}`);
+  }
+  return Object.freeze(result);
+}
+
+export function isGovernedSkillMarketplaceCliHost(value) {
+  return HOSTS.has(value);
+}
+
+/** Deployment-owned catalog, verification and transition ports. No local fallback. */
+export function createGovernedSkillMarketplaceCliHost({
+  tenantId,
+  target: inputTarget,
+  ledgerAdapter,
+  candidateInstaller,
+  catalog,
+  ports,
+} = {}) {
+  id(tenantId, "tenantId");
+  if (
+    !isGovernedSkillMarketplaceLedgerAdapter(ledgerAdapter) ||
+    ledgerAdapter.descriptor.tenantId !== tenantId
+  )
+    throw new TypeError(
+      "a same-tenant branded marketplace ledger adapter is required",
+    );
+  const target = targetSnapshot(inputTarget);
+  if (
+    !isGovernedSkillMarketplaceCandidateInstaller(candidateInstaller) ||
+    candidateInstaller.tenantId !== tenantId
+  )
+    throw new TypeError(
+      "a same-tenant branded marketplace candidate installer is required",
+    );
+  const resolve = capture(catalog, "resolve");
+  const load = ledgerAdapter.load;
+  const listSkillNames = ledgerAdapter.listSkillNames;
+  const isManifestRevoked = ledgerAdapter.isManifestRevoked;
+  const marketplace = new GovernedSkillMarketplace({
+    tenantId,
+    ports: {
+      verifySignature: capture(ports, "verifySignature"),
+      adapt: capture(ports, "adapt"),
+      transition: capture(ports, "transition"),
+      verifyPilot: capture(ports, "verifyPilot"),
+      verifyRevocation: capture(ports, "verifyRevocation"),
+      load,
+      commit: ledgerAdapter.commit,
+    },
+  });
+
+  const stateFor = async (skillName, verifyCandidate = true) => {
+    id(skillName, "skillName");
+    const state = await load({ skillName });
+    if (state && TARGET_KEYS.some((key) => state.target[key] !== target[key]))
+      throw new Error("marketplace state belongs to another deployment target");
+    if (verifyCandidate && state?.candidateBinding && !state.revoked)
+      candidateInstaller.verify(state);
+    return state;
+  };
+  const resolveManifest = async (skillName, version) => {
+    id(skillName, "skillName");
+    if (version !== null) id(version, "version");
+    const manifest = await resolve(
+      Object.freeze({ tenantId, skillName, version }),
+    );
+    if (
+      manifest?.tenantId !== tenantId ||
+      manifest.skillName !== skillName ||
+      (version !== null && manifest.version !== version)
+    )
+      throw new Error(
+        "marketplace catalog returned a different Skill or version",
+      );
+    return manifest;
+  };
+  const exactState = async (
+    skillName,
+    expectedStateDigest,
+    verifyCandidate = true,
+  ) => {
+    digest(expectedStateDigest, "expectedStateDigest");
+    const state = await stateFor(skillName, verifyCandidate);
+    if (!state || state.stateDigest !== expectedStateDigest)
+      throw new Error("marketplace state baseline changed");
+    return state;
+  };
+
+  const host = Object.freeze({
+    tenantId,
+    target,
+    async list({ offset = 0, limit = 100 } = {}) {
+      if (
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 500
+      )
+        throw new TypeError("marketplace list bounds are invalid");
+      const names = listSkillNames();
+      const items = [];
+      for (const skillName of names.slice(offset, offset + limit))
+        items.push(await stateFor(skillName));
+      return Object.freeze({
+        items: Object.freeze(items),
+        total: names.length,
+        offset,
+        limit,
+      });
+    },
+    async inspect({ skillName, version = null } = {}) {
+      const manifest = await resolveManifest(skillName, version);
+      const inspected = await marketplace.inspect(manifest, target);
+      return Object.freeze({
+        skillName,
+        version: inspected.manifest.version,
+        manifestDigest: inspected.manifest.manifestDigest,
+        packageDigest: inspected.manifest.packageDigest,
+        sourceModel: inspected.manifest.sourceModel,
+        target,
+        evalBadgeDigest: inspected.manifest.evalBadgeDigest,
+        evalReceiptDigest: inspected.cell.evalReceiptDigest,
+        qualityScore: inspected.cell.qualityScore,
+        sampleCount: inspected.cell.sampleCount,
+        adaptedOutputDigest: inspected.adapted.outputDigest,
+        state: await stateFor(skillName),
+      });
+    },
+    async preparePublicBadge({ skillName, version, manifestDigest } = {}) {
+      id(version, "exact public badge version");
+      digest(manifestDigest, "manifestDigest");
+      const manifest = await resolveManifest(skillName, version);
+      if (manifest.manifestDigest !== manifestDigest)
+        throw new Error("public badge manifest changed");
+      // Adaptation/evaluation happens only during explicit publication, never
+      // in response to anonymous HTTP traffic. The server expires this snapshot.
+      const inspected = await marketplace.inspect(manifest, target);
+      const projection = Object.freeze({
+        schema: GOVERNED_SKILL_MARKETPLACE_PUBLIC_BADGE_SCHEMA,
+        skillName,
+        version,
+        manifestDigest,
+        sourceModel: inspected.manifest.sourceModel,
+        sourceCommitDigest: inspected.manifest.sourceCommitDigest,
+        packageDigest: inspected.manifest.packageDigest,
+        sbomDigest: inspected.manifest.sbomDigest,
+        dependencyLockDigest: inspected.manifest.dependencyLockDigest,
+        permissionManifestDigest: inspected.manifest.permissionManifestDigest,
+        targetMatrixDigest: inspected.manifest.targetMatrixDigest,
+        evalBadgeDigest: inspected.manifest.evalBadgeDigest,
+        evalReceiptDigest: inspected.cell.evalReceiptDigest,
+        qualityScore: inspected.cell.qualityScore,
+        sampleCount: inspected.cell.sampleCount,
+        adaptedOutputDigest: inspected.adapted.outputDigest,
+        target,
+      });
+      return Object.freeze({
+        read: async () => {
+          const current = await resolveManifest(skillName, version);
+          if (current.manifestDigest !== manifestDigest)
+            throw new Error("public badge manifest changed");
+          await marketplace.verifyListing(current, target);
+          const revoked = await isManifestRevoked({
+            skillName,
+            manifestDigest,
+          });
+          return Object.freeze({ ...projection, revoked });
+        },
+      });
+    },
+    state: ({ skillName } = {}) => stateFor(skillName),
+    async install({
+      skillName,
+      version = null,
+      manifestDigest,
+      expectedStateDigest = null,
+    } = {}) {
+      digest(manifestDigest, "manifestDigest");
+      if (expectedStateDigest !== null)
+        digest(expectedStateDigest, "expectedStateDigest");
+      const manifest = await resolveManifest(skillName, version);
+      if (manifest.manifestDigest !== manifestDigest)
+        throw new Error("marketplace catalog manifest changed; inspect again");
+      const inspected = await marketplace.inspect(manifest, target);
+      if (await isManifestRevoked({ skillName, manifestDigest }))
+        throw new Error(
+          "marketplace manifest was revoked and cannot be staged again",
+        );
+      const isReplay = (state) =>
+        state?.candidateBinding !== undefined &&
+        state?.stage === "candidate" &&
+        state.revoked === false &&
+        state.manifestDigest === manifestDigest &&
+        state.adaptedOutputDigest === inspected.adapted.outputDigest &&
+        state.previousStateDigest === expectedStateDigest;
+      const result = (state, recovered) => {
+        candidateInstaller.verify(state);
+        return Object.freeze({
+          status: "candidate-staged",
+          activated: false,
+          materialized: true,
+          recovered,
+          state,
+        });
+      };
+      const current = await stateFor(skillName);
+      if (isReplay(current)) return result(current, true);
+      if (
+        current?.manifestDigest === manifestDigest &&
+        (current.candidateBinding ||
+          current.stage !== "candidate" ||
+          current.revoked)
+      )
+        throw new Error(
+          "marketplace manifest is already staged, advanced or revoked",
+        );
+      if ((current?.stateDigest ?? null) !== expectedStateDigest)
+        throw new Error("marketplace install baseline changed");
+      const candidateBinding = await candidateInstaller.materialize(inspected);
+      try {
+        return result(
+          await marketplace.stage({
+            manifest,
+            target,
+            expectedStateDigest,
+            candidateBinding,
+          }),
+          false,
+        );
+      } catch (error) {
+        // A durable append may have succeeded before its acknowledgement was lost.
+        const recovered = await stateFor(skillName);
+        if (isReplay(recovered)) return result(recovered, true);
+        throw error;
+      }
+    },
+    async rollout({ skillName, expectedStateDigest, receiptRef } = {}) {
+      id(receiptRef, "Pilot receipt reference");
+      const current = await exactState(skillName, expectedStateDigest);
+      candidateInstaller.verify(current);
+      return marketplace.advance({
+        skillName,
+        expectedStateDigest,
+        pilotReceipt: receiptRef,
+      });
+    },
+    async revoke({ skillName, expectedStateDigest, receiptRef } = {}) {
+      id(receiptRef, "revocation receipt reference");
+      // A missing/corrupt candidate must block rollout, not emergency rollback.
+      await exactState(skillName, expectedStateDigest, false);
+      return marketplace.revoke({
+        skillName,
+        expectedStateDigest,
+        revocationReceipt: receiptRef,
+      });
+    },
+  });
+  HOSTS.add(host);
+  return host;
+}