chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/governed-knowledge-merge-publisher-authority.js

@@ -5,8 +5,10 @@ import { verifyGovernedKnowledgeMergePlan } from "./governed-knowledge-conflict-
 
 export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_REQUEST_SCHEMA =
   "chainlesschain.governed-knowledge-merge-publish-request/v1";
-export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA =
+export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_LEGACY_SCHEMA =
   "chainlesschain.governed-knowledge-merge-publish-result/v1";
+export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA =
+  "chainlesschain.governed-knowledge-merge-publish-result/v2";
 
 const AUTHORITIES = new WeakSet();
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
@@ -20,6 +22,11 @@ const DESCRIPTOR_KEYS = new Set([
 ]);
 const RESULT_KEYS = new Set([
   "attestation",
+  "artifactCandidateDigest",
+  "artifactDigest",
+  "artifactReleaseId",
+  "artifactTransitionOperationId",
+  "artifactTransitionReceiptDigest",
   "deviceId",
   "durable",
   "envelopeDigest",
@@ -166,6 +173,12 @@ function validateResult(input, request, providerDescriptor, now) {
       providerDescriptor.handlerArtifactDigest ||
     result.durable !== true ||
     result.idempotent !== true ||
+    !DIGEST.test(result.artifactCandidateDigest ?? "") ||
+    !DIGEST.test(result.artifactDigest ?? "") ||
+    !ID.test(result.artifactReleaseId ?? "") ||
+    !ID.test(result.artifactTransitionOperationId ?? "") ||
+    !result.artifactTransitionOperationId.startsWith("artifact-transition:") ||
+    !DIGEST.test(result.artifactTransitionReceiptDigest ?? "") ||
     !DIGEST.test(result.envelopeDigest ?? "") ||
     !DIGEST.test(result.resultDigest ?? "") ||
     result.resultDigest !==
@@ -194,7 +207,15 @@ export function digestGovernedKnowledgeMergePublishResult(value) {
   delete core.resultDigest;
   delete core.attestation;
   delete core.verificationReceiptDigest;
-  return hash(GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA, core);
+  if (
+    ![
+      GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA,
+      GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_LEGACY_SCHEMA,
+    ].includes(value.schema)
+  ) {
+    throw new TypeError("merge publish result schema is invalid");
+  }
+  return hash(value.schema, core);
 }
 
 export function createGovernedKnowledgeMergePublisherAuthority({
@@ -236,7 +257,7 @@ export function createGovernedKnowledgeMergePublisherAuthority({
         throw new TypeError("merge publisher authority clock is invalid");
       }
       const result = validateResult(
-        await publish(request),
+        await publish(request, plan),
         request,
         providerDescriptor,
         currentTime,
@@ -257,6 +278,13 @@ export function createGovernedKnowledgeMergePublisherAuthority({
         verified.planDigest !== plan.planDigest ||
         verified.resultDigest !== result.resultDigest ||
         verified.envelopeDigest !== result.envelopeDigest ||
+        verified.artifactCandidateDigest !== result.artifactCandidateDigest ||
+        verified.artifactDigest !== result.artifactDigest ||
+        verified.artifactReleaseId !== result.artifactReleaseId ||
+        verified.artifactTransitionOperationId !==
+          result.artifactTransitionOperationId ||
+        verified.artifactTransitionReceiptDigest !==
+          result.artifactTransitionReceiptDigest ||
         verified.providerAuthorityId !== providerDescriptor.authorityId ||
         verified.providerRevision !== providerDescriptor.revision ||
         verified.verifierAuthorityId !== verifierDescriptor.authorityId ||

package/src/lib/evolution/governed-knowledge-record.js

@@ -0,0 +1,148 @@
+import { types as utilTypes } from "node:util";
+
+// Pure wire-record validation shared by synchronization and mandatory Ledger
+// admission. This module cannot mint execution brands or access persistence.
+export const GOVERNED_KNOWLEDGE_SYNC_SCHEMA =
+  "chainlesschain.governed-evolution-knowledge-sync/v1";
+export const GOVERNED_KNOWLEDGE_SCOPE = Object.freeze({
+  PERSONAL: "personal",
+  PROJECT: "project",
+  TEAM: "team",
+  ORG: "org",
+});
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const SCOPES = new Set(Object.values(GOVERNED_KNOWLEDGE_SCOPE));
+const ACTIONS = new Set(["upsert", "tombstone", "revoke"]);
+// A durable receipt for a different kind of effect is not a revocation.
+// In particular, tombstoning metadata must never count as stopping an active Skill.
+const REVOCATION_DISPOSITIONS = new Map([
+  ["wiki", new Set(["tombstone", "quarantine"])],
+  ["candidate", new Set(["reject-candidate", "quarantine"])],
+  ["active-skill", new Set(["rollback-active", "quarantine"])],
+]);
+function freeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freeze(child);
+  }
+  return value;
+}
+
+function record(value, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    throw new TypeError(`${label} must be a plain object`);
+  for (const key of Reflect.ownKeys(value)) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !Object.hasOwn(property, "value"))
+      throw new TypeError(`${label} must contain only data properties`);
+  }
+  return value;
+}
+
+function id(value, label) {
+  if (typeof value !== "string" || !ID.test(value))
+    throw new TypeError(`${label} is invalid`);
+  return value;
+}
+
+function digest(value, label) {
+  if (typeof value !== "string" || !DIGEST.test(value))
+    throw new TypeError(`${label} must be sha256-bound`);
+  return value;
+}
+
+function vectorClock(value) {
+  record(value, "vectorClock");
+  const entries = Object.entries(value);
+  if (entries.length < 1 || entries.length > 64)
+    throw new TypeError("vectorClock is empty or unbounded");
+  const result = {};
+  for (const [deviceId, revision] of entries.sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    id(deviceId, "vectorClock device");
+    if (!Number.isSafeInteger(revision) || revision < 0)
+      throw new TypeError("vectorClock revision is invalid");
+    result[deviceId] = revision;
+  }
+  return result;
+}
+
+function normalizeDependencies(value, action) {
+  if (!Array.isArray(value) || utilTypes.isProxy(value) || value.length > 256)
+    throw new TypeError("dependency dispositions are unbounded");
+  const seen = new Set();
+  const result = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const property = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!property || !Object.hasOwn(property, "value"))
+      throw new TypeError("dependency dispositions must be dense data");
+    const entry = property.value;
+    record(entry, "dependency disposition");
+    const normalized = {
+      kind: id(entry.kind, "dependency kind"),
+      digest: digest(entry.digest, "dependency digest"),
+      disposition: id(entry.disposition, "dependency disposition"),
+    };
+    const key = `${normalized.kind}:${normalized.digest}`;
+    if (seen.has(key)) throw new TypeError("duplicate dependency disposition");
+    seen.add(key);
+    if (
+      ["tombstone", "revoke"].includes(action) &&
+      !REVOCATION_DISPOSITIONS.get(normalized.kind)?.has(normalized.disposition)
+    )
+      throw new TypeError("revocation dependency disposition is unsafe");
+    result.push(normalized);
+  }
+  return result;
+}
+
+function normalizeRecord(input, descriptor) {
+  record(input, "knowledge record");
+  const action = ACTIONS.has(input.action) ? input.action : null;
+  const scope = SCOPES.has(input.scope) ? input.scope : null;
+  if (!action || !scope || input.tenantId !== descriptor.tenantId)
+    throw new TypeError("knowledge record boundary is invalid");
+  const dependencies = normalizeDependencies(input.dependencies || [], action);
+  if (
+    ["team", "org"].includes(scope) &&
+    !DIGEST.test(input.approvalReceiptDigest || "")
+  )
+    throw new TypeError("shared knowledge requires approval");
+  if (
+    ["tombstone", "revoke"].includes(action) &&
+    (!DIGEST.test(input.revocationReceiptDigest || "") ||
+      dependencies.length < 1)
+  )
+    throw new TypeError(
+      "revocation must bind its receipt and dependency graph",
+    );
+  const normalized = freeze({
+    schema: GOVERNED_KNOWLEDGE_SYNC_SCHEMA,
+    tenantId: descriptor.tenantId,
+    knowledgeId: id(input.knowledgeId, "knowledgeId"),
+    scope,
+    scopeId: id(input.scopeId, "scopeId"),
+    action,
+    contentDigest: digest(input.contentDigest, "contentDigest"),
+    vectorClock: vectorClock(input.vectorClock),
+    approvalReceiptDigest: input.approvalReceiptDigest || null,
+    revocationReceiptDigest: input.revocationReceiptDigest || null,
+    dependencies,
+  });
+  return normalized;
+}
+
+export function verifyGovernedKnowledgeRecord(input, { tenantId } = {}) {
+  return normalizeRecord(input, { tenantId: id(tenantId, "tenantId") });
+}
+
+export { vectorClock as normalizeGovernedKnowledgeVectorClock };

package/src/lib/evolution/governed-knowledge-revocation-record.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
+import { verifyGovernedKnowledgeRecord } from "./governed-knowledge-record.js";
+
+// Immutable prepared-record protocol only; no executor, writer, or authority brand.
+export const GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA =
+  "chainlesschain.governed-knowledge-dependencies-prepared/v1";
+export const GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE =
+  "knowledge.revocation-dependencies.prepared";
+export const GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT_CODE =
+  "CC_GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const PREPARED_KEYS = new Set([
+  "deviceId",
+  "knowledge",
+  "operationDigest",
+  "preparedAt",
+  "recordDigest",
+  "schema",
+  "tenantId",
+]);
+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(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function freeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freeze(child);
+  }
+  return value;
+}
+
+function corrupt(message) {
+  const error = new Error(message);
+  error.code = GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT_CODE;
+  throw error;
+}
+
+function exact(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    corrupt(`${label} is not a plain object`);
+  }
+  const actual = Reflect.ownKeys(value);
+  if (
+    actual.length !== keys.size ||
+    actual.some((key) => typeof key !== "string" || !keys.has(key))
+  ) {
+    corrupt(`${label} has an invalid shape`);
+  }
+  return value;
+}
+
+function identifier(value, label) {
+  if (typeof value !== "string" || !ID.test(value)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+export function digestGovernedKnowledgeDependencyOperation({
+  tenantId,
+  deviceId,
+  knowledge,
+}) {
+  return hash(GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA, {
+    tenantId,
+    deviceId,
+    knowledge,
+  });
+}
+
+function preparedCore(value) {
+  return {
+    schema: value.schema,
+    tenantId: value.tenantId,
+    deviceId: value.deviceId,
+    operationDigest: value.operationDigest,
+    knowledge: value.knowledge,
+    preparedAt: value.preparedAt,
+  };
+}
+
+export function verifyGovernedKnowledgeDependencyPrepared(
+  value,
+  descriptorValue,
+) {
+  exact(value, PREPARED_KEYS, "dependency prepared record");
+  identifier(value.deviceId, "dependency prepared deviceId");
+  const knowledge = verifyGovernedKnowledgeRecord(value.knowledge, {
+    tenantId: descriptorValue.tenantId,
+  });
+  const operationDigest = digestGovernedKnowledgeDependencyOperation({
+    tenantId: descriptorValue.tenantId,
+    deviceId: descriptorValue.deviceId,
+    knowledge,
+  });
+  if (
+    value.schema !== GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA ||
+    value.tenantId !== descriptorValue.tenantId ||
+    value.deviceId !== descriptorValue.deviceId ||
+    !["tombstone", "revoke"].includes(knowledge.action) ||
+    value.operationDigest !== operationDigest ||
+    !Number.isFinite(Date.parse(value.preparedAt)) ||
+    value.recordDigest !==
+      hash(GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA, preparedCore(value))
+  ) {
+    corrupt("dependency prepared record is invalid");
+  }
+  return freeze(clone(value));
+}