chainlesschain 0.166.22 → 0.166.25

package/src/lib/evolution/governed-knowledge-dependency-authority.js

@@ -1,12 +1,31 @@
 import { createHash } from "node:crypto";
 import { types as utilTypes } from "node:util";
 
+import { verifyGovernedKnowledgeRecord } from "./governed-knowledge-sync.js";
+import {
+  digestGovernedKnowledgeDependencyOperation,
+  isGovernedKnowledgeDependencyExecutionRequest,
+} from "./governed-knowledge-dependency-ledger-executor.js";
+
 export const GOVERNED_KNOWLEDGE_DEPENDENCY_REQUEST_SCHEMA =
   "chainlesschain.governed-knowledge-dependency-request/v1";
 export const GOVERNED_KNOWLEDGE_DEPENDENCY_RESULT_SCHEMA =
   "chainlesschain.governed-knowledge-dependency-result/v1";
 
 const AUTHORITIES = new WeakSet();
+// Only this module can dispatch a prepared router request into a leaf's full
+// request/result verification pipeline. No public rebranding API is exposed.
+const PREPARED_EXECUTIONS = new WeakMap();
+const PREPARED_REVERIFIERS = new WeakMap();
+
+// A read-only final check for the genuine executor. Reverification cannot call
+// a provider again, mint a request, or bypass the original leaf verifier.
+export function captureGovernedKnowledgeDependencyReverifier(authority) {
+  const verify = PREPARED_REVERIFIERS.get(authority);
+  if (!verify)
+    throw new TypeError("a genuine dependency authority is required");
+  return verify;
+}
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
 const DESCRIPTOR_KEYS = new Set([
@@ -36,6 +55,14 @@ const RESULT_KEYS = new Set([
   "tenantId",
 ]);
 const ATTESTATION_KEYS = new Set(["algorithm", "keyId", "value"]);
+const INPUT_KEYS = new Set([
+  "tenantId",
+  "deviceId",
+  "operationDigest",
+  "knowledge",
+  "dependency",
+]);
+const DEPENDENCY_KEYS = new Set(["kind", "digest", "disposition"]);
 
 function canonical(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -83,6 +110,14 @@ function exact(value, keys, label) {
   ) {
     throw new TypeError(`${label} has an invalid shape`);
   }
+  if (
+    actual.some(
+      (key) =>
+        !Object.hasOwn(Object.getOwnPropertyDescriptor(value, key), "value"),
+    )
+  ) {
+    throw new TypeError(`${label} must contain only data properties`);
+  }
   return value;
 }
 
@@ -94,15 +129,17 @@ function identifier(value, label) {
 }
 
 function capture(owner, method, label) {
+  if (!owner || typeof owner !== "object" || utilTypes.isProxy(owner)) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  const implementation = owner[method];
   if (
-    !owner ||
-    typeof owner !== "object" ||
-    utilTypes.isProxy(owner) ||
-    typeof owner[method] !== "function"
+    typeof implementation !== "function" ||
+    utilTypes.isProxy(implementation)
   ) {
-    throw new TypeError(`${label}.${method}() is required`);
+    throw new TypeError(`${label}.${method}() must be a non-proxy function`);
   }
-  return (...args) => Reflect.apply(owner[method], owner, args);
+  return (...args) => Reflect.apply(implementation, owner, args);
 }
 
 function descriptor(input, label) {
@@ -219,55 +256,201 @@ export function createGovernedKnowledgeDependencyAuthority({
   }
   const apply = capture(provider, "apply", "provider");
   const verify = capture(verifier, "verify", "verifier");
+  const executePrepared = async (input, revalidation = null) => {
+    exact(input, INPUT_KEYS, "dependency execution input");
+    if (
+      input?.tenantId !== tenantId ||
+      input.deviceId !== deviceId ||
+      !DIGEST.test(input.operationDigest ?? "")
+    ) {
+      throw new Error("dependency request crossed its authority boundary");
+    }
+    // Normalize and snapshot before the first await, then bind both the entire
+    // operation and the selected edge. A plausible digest is not authorization
+    // to apply an unlisted dependency or to change its disposition.
+    const knowledge = verifyGovernedKnowledgeRecord(input.knowledge, {
+      tenantId,
+    });
+    const dependency = exact(input.dependency, DEPENDENCY_KEYS, "dependency");
+    const selected = knowledge.dependencies.find(
+      (entry) =>
+        entry.kind === dependency.kind &&
+        entry.digest === dependency.digest &&
+        entry.disposition === dependency.disposition,
+    );
+    if (
+      !["tombstone", "revoke"].includes(knowledge.action) ||
+      !selected ||
+      input.operationDigest !==
+        digestGovernedKnowledgeDependencyOperation({
+          tenantId,
+          deviceId,
+          knowledge,
+        })
+    ) {
+      throw new Error(
+        "dependency request is not bound to its revocation operation",
+      );
+    }
+    const request = requestFor({
+      tenantId,
+      deviceId,
+      operationDigest: input.operationDigest,
+      knowledge,
+      dependency: selected,
+    });
+    let supplied;
+    if (revalidation !== null) {
+      exact(
+        revalidation.result,
+        new Set([...RESULT_KEYS, "verificationReceiptDigest"]),
+        "previously verified dependency result",
+      );
+      if (!DIGEST.test(revalidation.result.verificationReceiptDigest))
+        throw new TypeError("dependency verification receipt is invalid");
+      supplied = clone(revalidation.result);
+      delete supplied.verificationReceiptDigest;
+    }
+    const result = validateResult(
+      revalidation === null ? await apply(request) : supplied,
+      request,
+      providerDescriptor,
+    );
+    const verified = await verify({
+      request,
+      result,
+      providerDescriptor,
+      verifierDescriptor,
+    });
+    if (
+      verified?.authenticated !== true ||
+      verified.durable !== true ||
+      verified.tenantId !== tenantId ||
+      verified.deviceId !== deviceId ||
+      verified.operationId !== request.operationId ||
+      verified.requestDigest !== request.requestDigest ||
+      verified.resultDigest !== result.resultDigest ||
+      verified.providerAuthorityId !== providerDescriptor.authorityId ||
+      verified.providerRevision !== providerDescriptor.revision ||
+      verified.verifierAuthorityId !== verifierDescriptor.authorityId ||
+      verified.verifierRevision !== verifierDescriptor.revision ||
+      !DIGEST.test(verified.verificationReceiptDigest ?? "")
+    ) {
+      throw new Error("dependency result was not independently verified");
+    }
+    return freeze({
+      ...clone(result),
+      verificationReceiptDigest: verified.verificationReceiptDigest,
+    });
+  };
   const authority = Object.freeze({
     tenantId,
     deviceId,
     async apply(input) {
-      if (
-        input?.tenantId !== tenantId ||
-        input.deviceId !== deviceId ||
-        !DIGEST.test(input.operationDigest ?? "")
-      ) {
-        throw new Error("dependency request crossed its authority boundary");
+      if (!isGovernedKnowledgeDependencyExecutionRequest(input, authority)) {
+        throw new TypeError(
+          "dependency execution requires a prepared executor request",
+        );
       }
-      const request = requestFor(input);
-      const result = validateResult(
-        await apply(request),
-        request,
-        providerDescriptor,
-      );
-      const verified = await verify({
-        request,
-        result,
-        providerDescriptor,
-        verifierDescriptor,
-      });
-      if (
-        verified?.authenticated !== true ||
-        verified.durable !== true ||
-        verified.tenantId !== tenantId ||
-        verified.deviceId !== deviceId ||
-        verified.operationId !== request.operationId ||
-        verified.requestDigest !== request.requestDigest ||
-        verified.resultDigest !== result.resultDigest ||
-        verified.providerAuthorityId !== providerDescriptor.authorityId ||
-        verified.providerRevision !== providerDescriptor.revision ||
-        verified.verifierAuthorityId !== verifierDescriptor.authorityId ||
-        verified.verifierRevision !== verifierDescriptor.revision ||
-        !DIGEST.test(verified.verificationReceiptDigest ?? "")
-      ) {
-        throw new Error("dependency result was not independently verified");
-      }
-      return freeze({
-        ...clone(result),
-        verificationReceiptDigest: verified.verificationReceiptDigest,
-      });
+      return executePrepared(input);
     },
   });
   AUTHORITIES.add(authority);
+  PREPARED_EXECUTIONS.set(authority, executePrepared);
+  PREPARED_REVERIFIERS.set(
+    authority,
+    Object.freeze((input, result) => {
+      if (!isGovernedKnowledgeDependencyExecutionRequest(input, authority))
+        throw new TypeError(
+          "dependency verification requires a prepared executor request",
+        );
+      return executePrepared(input, { result });
+    }),
+  );
   return authority;
 }
 
+export function createGovernedKnowledgeDependencyRouter({
+  tenantId,
+  deviceId,
+  routes,
+} = {}) {
+  identifier(tenantId, "router tenantId");
+  identifier(deviceId, "router deviceId");
+  if (
+    !routes ||
+    typeof routes !== "object" ||
+    utilTypes.isProxy(routes) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(routes))
+  ) {
+    throw new TypeError("dependency routes must be a plain object");
+  }
+  const keys = Reflect.ownKeys(routes);
+  exact(routes, new Set(keys), "dependency routes");
+  const allowed = new Set([
+    "wiki/tombstone",
+    "wiki/quarantine",
+    "candidate/reject-candidate",
+    "candidate/quarantine",
+    "active-skill/rollback-active",
+    "active-skill/quarantine",
+  ]);
+  if (!keys.length || keys.some((key) => !allowed.has(key)))
+    throw new TypeError("dependency route is unsupported");
+  const handlers = new Map();
+  for (const key of keys) {
+    const authority = routes[key];
+    const execute = PREPARED_EXECUTIONS.get(authority);
+    if (
+      !execute ||
+      authority.tenantId !== tenantId ||
+      authority.deviceId !== deviceId
+    ) {
+      throw new TypeError(
+        "dependency route requires a genuine same-boundary leaf authority",
+      );
+    }
+    handlers.set(key, execute);
+  }
+  const router = Object.freeze({
+    tenantId,
+    deviceId,
+    async apply(input) {
+      if (!isGovernedKnowledgeDependencyExecutionRequest(input, router))
+        throw new TypeError(
+          "dependency routing requires a prepared executor request",
+        );
+      exact(input, INPUT_KEYS, "dependency routing input");
+      exact(input.dependency, DEPENDENCY_KEYS, "dependency route selection");
+      const execute = handlers.get(
+        `${input.dependency.kind}/${input.dependency.disposition}`,
+      );
+      if (!execute)
+        throw new Error("no real authority for this dependency disposition");
+      return execute(input);
+    },
+  });
+  AUTHORITIES.add(router);
+  PREPARED_REVERIFIERS.set(
+    router,
+    Object.freeze((input, result) => {
+      if (!isGovernedKnowledgeDependencyExecutionRequest(input, router))
+        throw new TypeError(
+          "dependency verification requires a prepared router request",
+        );
+      exact(input, INPUT_KEYS, "dependency verification input");
+      exact(input.dependency, DEPENDENCY_KEYS, "dependency verification route");
+      const execute = handlers.get(
+        `${input.dependency.kind}/${input.dependency.disposition}`,
+      );
+      if (!execute)
+        throw new Error("no real authority for dependency verification");
+      return execute(input, { result });
+    }),
+  );
+  return router;
+}
+
 export function isGovernedKnowledgeDependencyAuthority(value) {
   return AUTHORITIES.has(value);
 }