chainlesschain 0.166.22 → 0.166.25

package/src/lib/evolution/governed-wiki-pruning-plan-authority.js

@@ -0,0 +1,169 @@
+import { captureWikiRevisionReader } from "./wiki-maintainer-ledger-adapter.js";
+import { createWikiPruningPlanner } from "./governed-wiki-pruning.js";
+import {
+  pruningCanonical,
+  verifyPruningJournalPlan,
+} from "./governed-wiki-pruning-journal.js";
+
+function capture(owner, name, label) {
+  const method = owner?.[name];
+  if (typeof method !== "function")
+    throw new TypeError(`${label}.${name} is required`);
+  return (...args) => Reflect.apply(method, owner, args);
+}
+
+function contextSnapshot(context) {
+  if (
+    !context ||
+    typeof context !== "object" ||
+    Array.isArray(context) ||
+    Object.keys(context).length !== 2 ||
+    !Object.hasOwn(context, "mode") ||
+    !Object.hasOwn(context, "checkpoint")
+  )
+    throw new TypeError("pruning authorization context is invalid");
+  if (
+    !["current", "checkpoint"].includes(context.mode) ||
+    !context.checkpoint ||
+    typeof context.checkpoint !== "object" ||
+    Array.isArray(context.checkpoint)
+  )
+    throw new TypeError("pruning authorization checkpoint is required");
+  // The branded reader validates all fields and authenticates this exact head
+  // against its own ledger. A head from a different domain ledger is not enough.
+  return Object.freeze({
+    mode: context.mode,
+    checkpoint: Object.freeze({ ...context.checkpoint }),
+  });
+}
+
+// Combines a real immutable Wiki source with the SAME planner used by execute.
+// wikiMaintenance must derive the exact ordered request digests from this plan
+// and independently verify each successor's operation AND resulting state.
+// A matching maintenance request digest or an echoed boolean is not an effect
+// proof. The journal separately reauthenticates the individual provider receipts
+// and enforces the enclosing ledger head CAS around asynchronous verification.
+export class GovernedWikiPruningPlanAuthority {
+  #reader;
+  #resolveDeletion;
+  #requests;
+  #verifySuccessors;
+  #descriptor;
+  #streamId;
+  #verify;
+
+  constructor({
+    descriptor,
+    wikiLedgerAdapter,
+    deletionReceipts,
+    wikiMaintenance,
+  } = {}) {
+    this.#reader = captureWikiRevisionReader(wikiLedgerAdapter);
+    if (
+      typeof descriptor?.streamId !== "string" ||
+      !descriptor.streamId.trim() ||
+      descriptor.streamId.length > 256 ||
+      descriptor.tenantId !== this.#reader.descriptor.tenantId
+    )
+      throw new TypeError("pruning plan authority scope is invalid");
+    this.#streamId = descriptor.streamId;
+    this.#resolveDeletion = capture(
+      deletionReceipts,
+      "resolve",
+      "deletionReceipts",
+    );
+    this.#requests = capture(
+      wikiMaintenance,
+      "requestDigests",
+      "wikiMaintenance",
+    );
+    this.#verifySuccessors = capture(
+      wikiMaintenance,
+      "verifySuccessors",
+      "wikiMaintenance",
+    );
+    this.#descriptor = createWikiPruningPlanner({
+      descriptor,
+      ports: {
+        loadWikiState: this.#reader.loadWiki,
+        resolveDeletionReceipt: this.#resolveDeletion,
+      },
+    }).descriptor;
+    this.#verify = (input) => this.#verifyPlan(input);
+    Object.freeze(this);
+  }
+
+  // The returned facade calls the captured private implementation.
+  verifier() {
+    return Object.freeze({ verify: this.#verify });
+  }
+
+  async #verifyPlan({ plan: input, tenantId, streamId, context } = {}) {
+    if (tenantId !== this.#descriptor.tenantId || streamId !== this.#streamId)
+      throw new TypeError("pruning plan authorization scope is invalid");
+    const plan = verifyPruningJournalPlan(input, tenantId);
+    const capturedContext = contextSnapshot(context);
+    const allowedMaintenanceRequestDigests = await this.#requests({
+      plan,
+      tenantId,
+      streamId,
+    });
+    const query = {
+      tenantId,
+      stateDigest: plan.wikiStateDigest,
+      allowedMaintenanceRequestDigests,
+    };
+    const history =
+      capturedContext.mode === "current"
+        ? this.#reader.resolveHistory(query)
+        : this.#reader.resolveAtCheckpoint({
+            ...query,
+            checkpoint: capturedContext.checkpoint,
+          });
+    if (capturedContext.mode === "current") {
+      const keys = [
+        "epoch",
+        "ledgerId",
+        "identityDigest",
+        "sequence",
+        "headDigest",
+      ];
+      if (
+        Object.keys(capturedContext.checkpoint).length !== keys.length ||
+        keys.some(
+          (key) =>
+            !Object.hasOwn(capturedContext.checkpoint, key) ||
+            capturedContext.checkpoint[key] !== history.ledgerHead[key],
+        )
+      ) {
+        throw new Error(
+          "pruning plan current ledger identity or head differs from the Wiki ledger",
+        );
+      }
+    }
+    const planner = createWikiPruningPlanner({
+      descriptor: this.#descriptor,
+      ports: {
+        loadWikiState: () => history.source,
+        resolveDeletionReceipt: this.#resolveDeletion,
+      },
+    });
+    const rebuilt = await planner.plan({
+      expectedStateDigest: plan.wikiStateDigest,
+      effectiveAt: plan.effectiveAt,
+      deletionReceiptDigests: plan.deletions.map(
+        (entry) => entry.receiptDigest,
+      ),
+    });
+    if (pruningCanonical(plan) !== pruningCanonical(rebuilt)) return false;
+    return (
+      (await this.#verifySuccessors({
+        plan,
+        history,
+        tenantId,
+        streamId,
+        context: capturedContext,
+      })) === true
+    );
+  }
+}

package/src/lib/evolution/governed-wiki-pruning-raw-shred.js

@@ -0,0 +1,207 @@
+import { captureRawDeletionLedgerReader } from "./evolution-raw-deletion-ledger-adapter.js";
+import {
+  EvolutionRawCryptoShred,
+  buildEvolutionRawCryptoShredRequest,
+} from "./evolution-raw-crypto-shred.js";
+import { captureWikiPruningJournalStore } from "./governed-wiki-pruning-ledger-adapter.js";
+import {
+  capturePruningData,
+  pruningCanonical,
+  pruningOperationCalls,
+  verifyPruningJournalPlan,
+} from "./governed-wiki-pruning-journal.js";
+
+export const WIKI_PRUNING_KMS_PROOF_SCHEMA =
+  "chainlesschain.wiki-pruning-kms-destruction-proof/v1";
+const HEAD_KEYS = [
+  "epoch",
+  "ledgerId",
+  "identityDigest",
+  "sequence",
+  "headDigest",
+];
+const headOf = (head) =>
+  Object.fromEntries(HEAD_KEYS.map((key) => [key, head[key]]));
+const same = (left, right) =>
+  pruningCanonical(left) === pruningCanonical(right);
+function fail(message) {
+  const error = new Error(message);
+  error.code = "CC_WIKI_PRUNING_RAW_SHRED_INVALID";
+  throw error;
+}
+function capture(owner, name) {
+  const method = owner?.[name];
+  if (typeof method !== "function")
+    throw new TypeError(`KMS ${name} is required`);
+  return (...args) => Reflect.apply(method, owner, args);
+}
+
+// The deployment owns KMS/HSM authority. The repository owns plan/frontier
+// authorization, actual shredder + retained tombstone integration, independent
+// KMS proof resolution, historical causality and exact response-loss recovery.
+export class GovernedWikiPruningRawShred {
+  #reader;
+  #shred;
+  #resolveDestruction;
+  constructor({ descriptor, deletionLedgerAdapter, keyAuthority } = {}) {
+    this.descriptor = capturePruningData(descriptor);
+    this.#reader = captureRawDeletionLedgerReader(
+      deletionLedgerAdapter,
+      descriptor.tenantId,
+      descriptor.streamId,
+    );
+    const shredder = new EvolutionRawCryptoShred({
+      tenantId: descriptor.tenantId,
+      ports: this.#reader.cryptoShredPorts({
+        destroyKey: capture(keyAuthority, "destroyKey"),
+        confirmKeyDestroyed: capture(keyAuthority, "confirmKeyDestroyed"),
+      }),
+    });
+    this.#shred = shredder.shred.bind(shredder);
+    // Not an echoed destroy acknowledgement: this independently resolves the
+    // original persisted destruction/confirmation evidence and key status.
+    this.#resolveDestruction = capture(keyAuthority, "resolveDestruction");
+    Object.freeze(this);
+  }
+  operationReceiptVerifier() {
+    return Object.freeze({ verify: (input) => this.#verify(input) });
+  }
+  #call(plan, input) {
+    const call = capturePruningData(input);
+    const index = pruningOperationCalls(plan).findIndex((item) =>
+      same(item, call),
+    );
+    if (
+      index < 2 ||
+      index >= 2 + plan.deletions.length ||
+      call.request.operation !== "crypto-shred"
+    )
+      fail("Raw shred call differs from the exact planned deletion");
+    return { call, index };
+  }
+  async #verify({
+    plan: inputPlan,
+    request,
+    requestDigest,
+    receipt: inputReceipt,
+    tenantId,
+    streamId,
+    context,
+  } = {}) {
+    if (
+      tenantId !== this.descriptor.tenantId ||
+      streamId !== this.descriptor.streamId
+    )
+      return false;
+    const plan = verifyPruningJournalPlan(inputPlan, tenantId);
+    const { call } = this.#call(plan, { request, requestDigest });
+    const receipt = capturePruningData(inputReceipt);
+    const resolved = await this.#reader.resolveTombstone({
+      tenantId,
+      tombstoneDigest: receipt.tombstoneDigest,
+      context: context ?? {
+        mode: "current",
+        checkpoint: headOf(this.#reader.head()),
+      },
+    });
+    const verificationHead = resolved.ledgerHead;
+    const destruction = buildEvolutionRawCryptoShredRequest(call, tenantId);
+    const tombstone = resolved.tombstone;
+    if (
+      tombstone.pruningRequestDigest !== call.requestDigest ||
+      tombstone.destructionRequestDigest !== destruction.requestDigest ||
+      tombstone.evidenceRef !== destruction.evidenceRef ||
+      tombstone.rawArtifactRef !== destruction.rawArtifactRef ||
+      tombstone.rawCipherDigest !== destruction.rawCipherDigest ||
+      tombstone.deletionReceiptDigest !== destruction.deletionReceiptDigest
+    )
+      return false;
+    const proof = capturePruningData(
+      await this.#resolveDestruction({
+        request: destruction,
+        destructionReceiptDigest: tombstone.destructionReceiptDigest,
+        confirmationReceiptDigest: tombstone.confirmationReceiptDigest,
+      }),
+    );
+    if (
+      !same(proof, {
+        schema: WIKI_PRUNING_KMS_PROOF_SCHEMA,
+        authenticated: true,
+        durable: true,
+        destroyed: true,
+        tenantId,
+        keyRef: destruction.keyRef,
+        requestDigest: destruction.requestDigest,
+        destructionReceiptDigest: tombstone.destructionReceiptDigest,
+        confirmationReceiptDigest: tombstone.confirmationReceiptDigest,
+      })
+    )
+      return false;
+    if (!same(headOf(this.#reader.head()), verificationHead))
+      fail("Raw deletion authority changed during KMS proof resolution");
+    return same(receipt, {
+      authenticated: true,
+      durable: true,
+      requestDigest: call.requestDigest,
+      receiptDigest: resolved.ledgerEventDigest,
+      tombstoneDigest: resolved.tombstoneDigest,
+    });
+  }
+  createProvider(journalStore) {
+    const journal = captureWikiPruningJournalStore(journalStore);
+    if (
+      journal.descriptor.tenantId !== this.descriptor.tenantId ||
+      journal.descriptor.streamId !== this.descriptor.streamId
+    )
+      throw new TypeError("Raw shred journal scope differs");
+    return Object.freeze({
+      cryptoShred: (input) => this.#apply(journal, input),
+    });
+  }
+  async #apply(journal, input) {
+    const captured = capturePruningData(input);
+    const resolution = await journal.load({
+      tenantId: this.descriptor.tenantId,
+    });
+    if (!resolution.state)
+      fail("Raw shred requires a durably prepared pruning plan");
+    const plan = verifyPruningJournalPlan(
+      resolution.state.plan,
+      this.descriptor.tenantId,
+    );
+    const { call, index } = this.#call(plan, captured);
+    const verification = (receipt, context) =>
+      this.#verify({ ...call, ...this.descriptor, plan, receipt, context });
+    if (resolution.state.operationReceipts.length > index) {
+      const receipt = resolution.state.operationReceipts[index];
+      if (
+        !(await verification(receipt, {
+          mode: "checkpoint",
+          checkpoint: resolution.checkpoint,
+        }))
+      )
+        fail("saved Raw shred receipt was substituted");
+      return receipt;
+    }
+    if (
+      resolution.state.phase !== "running" ||
+      resolution.state.operationReceipts.length !== index
+    )
+      fail(
+        "Raw shred requires the complete dependency/Wiki and prior deletion frontier",
+      );
+    if (!same(headOf(this.#reader.head()), resolution.ledgerHead))
+      fail("Raw shred authorization is not on the current deletion ledger");
+    // Repeated delivery uses the SAME deterministic KMS request. The provider
+    // must reconcile its durable evidence, not issue another key destruction.
+    const receipt = await this.#shred(call);
+    if (
+      !(await verification(receipt, {
+        mode: "current",
+        checkpoint: headOf(this.#reader.head()),
+      }))
+    )
+      fail("Raw shred has no independently verified durable destruction proof");
+    return receipt;
+  }
+}