chainlesschain 0.166.18 → 0.166.21

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

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
+
+import { verifyGovernedKnowledgeMergePlan } from "./governed-knowledge-conflict-merge.js";
+
+export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_REQUEST_SCHEMA =
+  "chainlesschain.governed-knowledge-merge-publish-request/v1";
+export const GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA =
+  "chainlesschain.governed-knowledge-merge-publish-result/v1";
+
+const AUTHORITIES = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const MAX_RESULT_AGE_MS = 24 * 60 * 60 * 1000;
+const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const DESCRIPTOR_KEYS = new Set([
+  "authorityId",
+  "handlerArtifactDigest",
+  "revision",
+]);
+const RESULT_KEYS = new Set([
+  "attestation",
+  "deviceId",
+  "durable",
+  "envelopeDigest",
+  "idempotent",
+  "knowledgeId",
+  "mergedContentDigest",
+  "operationId",
+  "planDigest",
+  "providerAuthorityId",
+  "providerHandlerArtifactDigest",
+  "providerRevision",
+  "publishedAt",
+  "requestDigest",
+  "resultDigest",
+  "schema",
+  "tenantId",
+]);
+const ATTESTATION_KEYS = new Set(["algorithm", "keyId", "value"]);
+
+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 exact(value, keys, 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`);
+  }
+  const actual = Reflect.ownKeys(value);
+  if (
+    actual.length !== keys.size ||
+    actual.some((key) => typeof key !== "string" || !keys.has(key))
+  ) {
+    throw new TypeError(`${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;
+}
+
+function capture(owner, method, label) {
+  if (
+    !owner ||
+    typeof owner !== "object" ||
+    utilTypes.isProxy(owner) ||
+    typeof owner[method] !== "function"
+  ) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  return (...args) => Reflect.apply(owner[method], owner, args);
+}
+
+function descriptor(input, label) {
+  exact(input, DESCRIPTOR_KEYS, `${label} descriptor`);
+  if (
+    !Number.isSafeInteger(input.revision) ||
+    input.revision < 1 ||
+    !DIGEST.test(input.handlerArtifactDigest ?? "")
+  ) {
+    throw new TypeError(`${label} descriptor is invalid`);
+  }
+  return freeze({
+    authorityId: identifier(input.authorityId, `${label} authorityId`),
+    revision: input.revision,
+    handlerArtifactDigest: input.handlerArtifactDigest,
+  });
+}
+
+function requestFor(plan) {
+  const core = {
+    schema: GOVERNED_KNOWLEDGE_MERGE_PUBLISH_REQUEST_SCHEMA,
+    tenantId: plan.tenantId,
+    deviceId: plan.deviceId,
+    operationId: `knowledge-merge:${plan.planDigest.slice(7)}`,
+    planDigest: plan.planDigest,
+    knowledgeId: plan.knowledgeId,
+    mergedContentDigest: plan.mergedKnowledge.contentDigest,
+    mergedKnowledge: plan.mergedKnowledge,
+  };
+  return freeze({
+    ...core,
+    requestDigest: hash(GOVERNED_KNOWLEDGE_MERGE_PUBLISH_REQUEST_SCHEMA, core),
+  });
+}
+
+function validateResult(input, request, providerDescriptor, now) {
+  const result = exact(input, RESULT_KEYS, "merge publish result");
+  const attestation = exact(
+    result.attestation,
+    ATTESTATION_KEYS,
+    "merge publish attestation",
+  );
+  const core = clone(result);
+  delete core.resultDigest;
+  delete core.attestation;
+  const publishedAt = Date.parse(result.publishedAt);
+  if (
+    result.schema !== GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA ||
+    result.tenantId !== request.tenantId ||
+    result.deviceId !== request.deviceId ||
+    result.operationId !== request.operationId ||
+    result.requestDigest !== request.requestDigest ||
+    result.planDigest !== request.planDigest ||
+    result.knowledgeId !== request.knowledgeId ||
+    result.mergedContentDigest !== request.mergedContentDigest ||
+    result.providerAuthorityId !== providerDescriptor.authorityId ||
+    result.providerRevision !== providerDescriptor.revision ||
+    result.providerHandlerArtifactDigest !==
+      providerDescriptor.handlerArtifactDigest ||
+    result.durable !== true ||
+    result.idempotent !== true ||
+    !DIGEST.test(result.envelopeDigest ?? "") ||
+    !DIGEST.test(result.resultDigest ?? "") ||
+    result.resultDigest !==
+      hash(GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA, core) ||
+    !Number.isFinite(publishedAt) ||
+    publishedAt < now - MAX_RESULT_AGE_MS ||
+    publishedAt > now + MAX_FUTURE_SKEW_MS
+  ) {
+    throw new Error("merge publisher returned an invalid durable result");
+  }
+  for (const [key, value] of Object.entries(attestation)) {
+    if (
+      typeof value !== "string" ||
+      value.trim() !== value ||
+      value.length < 1 ||
+      value.length > (key === "value" ? 4096 : 256)
+    ) {
+      throw new TypeError("merge publish attestation is invalid");
+    }
+  }
+  return freeze(clone(result));
+}
+
+export function digestGovernedKnowledgeMergePublishResult(value) {
+  const core = clone(value);
+  delete core.resultDigest;
+  delete core.attestation;
+  delete core.verificationReceiptDigest;
+  return hash(GOVERNED_KNOWLEDGE_MERGE_PUBLISH_RESULT_SCHEMA, core);
+}
+
+export function createGovernedKnowledgeMergePublisherAuthority({
+  tenantId: tenantIdInput,
+  deviceId: deviceIdInput,
+  providerDescriptor: providerDescriptorInput,
+  verifierDescriptor: verifierDescriptorInput,
+  provider,
+  verifier,
+  now = Date.now,
+} = {}) {
+  const tenantId = identifier(tenantIdInput, "tenantId");
+  const deviceId = identifier(deviceIdInput, "deviceId");
+  const providerDescriptor = descriptor(providerDescriptorInput, "provider");
+  const verifierDescriptor = descriptor(verifierDescriptorInput, "verifier");
+  if (
+    providerDescriptor.authorityId === verifierDescriptor.authorityId ||
+    providerDescriptor.handlerArtifactDigest ===
+      verifierDescriptor.handlerArtifactDigest
+  ) {
+    throw new TypeError("merge provider and verifier must be independent");
+  }
+  if (typeof now !== "function" || utilTypes.isProxy(now)) {
+    throw new TypeError("now must be a non-proxy function");
+  }
+  const publish = capture(provider, "publish", "provider");
+  const verify = capture(verifier, "verify", "verifier");
+  const authority = Object.freeze({
+    tenantId,
+    deviceId,
+    async publish(planInput) {
+      const plan = verifyGovernedKnowledgeMergePlan(planInput);
+      if (plan.tenantId !== tenantId || plan.deviceId !== deviceId) {
+        throw new Error("merge publish plan crossed its authority boundary");
+      }
+      const request = requestFor(plan);
+      const currentTime = Number(now());
+      if (!Number.isFinite(currentTime)) {
+        throw new TypeError("merge publisher authority clock is invalid");
+      }
+      const result = validateResult(
+        await publish(request),
+        request,
+        providerDescriptor,
+        currentTime,
+      );
+      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.planDigest !== plan.planDigest ||
+        verified.resultDigest !== result.resultDigest ||
+        verified.envelopeDigest !== result.envelopeDigest ||
+        verified.providerAuthorityId !== providerDescriptor.authorityId ||
+        verified.providerRevision !== providerDescriptor.revision ||
+        verified.verifierAuthorityId !== verifierDescriptor.authorityId ||
+        verified.verifierRevision !== verifierDescriptor.revision ||
+        !DIGEST.test(verified.verificationReceiptDigest ?? "")
+      ) {
+        throw new Error(
+          "merge publisher result was not independently verified",
+        );
+      }
+      return freeze({
+        ...clone(result),
+        verificationReceiptDigest: verified.verificationReceiptDigest,
+      });
+    },
+  });
+  AUTHORITIES.add(authority);
+  return authority;
+}
+
+export function isGovernedKnowledgeMergePublisherAuthority(value) {
+  return AUTHORITIES.has(value);
+}

package/src/lib/evolution/governed-knowledge-node-crypto-authority.js

@@ -0,0 +1,348 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  randomBytes,
+  sign,
+  verify,
+} from "node:crypto";
+import { types as utilTypes } from "node:util";
+
+export const GOVERNED_KNOWLEDGE_CRYPTO_AUTHORITY_SCHEMA =
+  "chainlesschain.governed-knowledge-node-crypto-authority/v1";
+
+const AUTHORITIES = new WeakSet();
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const SIGNATURE_KEYS = new Set(["algorithm", "keyId", "value"]);
+const CIPHER_VERSION = 1;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const MAX_PLAINTEXT_BYTES = 12 * 1024 * 1024;
+
+function identifier(value, label) {
+  if (typeof value !== "string" || !ID.test(value)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function plainRecord(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`);
+  }
+  return value;
+}
+
+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 sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function keyObject(value, kind, label) {
+  let key;
+  try {
+    if (
+      value &&
+      typeof value === "object" &&
+      !utilTypes.isProxy(value) &&
+      value.type === kind
+    ) {
+      key = value;
+    } else {
+      key =
+        kind === "private" ? createPrivateKey(value) : createPublicKey(value);
+    }
+  } catch {
+    throw new TypeError(`${label} is not a valid ${kind} key`);
+  }
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new TypeError(`${label} must be Ed25519`);
+  }
+  return key;
+}
+
+function publicKeyId(key) {
+  const spki = key.export({ format: "der", type: "spki" });
+  return `key:ed25519:${createHash("sha256").update(spki).digest("hex")}`;
+}
+
+function scopeBinding(value) {
+  const source = plainRecord(value, "knowledge metadata");
+  const tenantId = identifier(source.tenantId, "knowledge tenantId");
+  const knowledgeId = identifier(source.knowledgeId, "knowledgeId");
+  const scope = identifier(source.scope, "knowledge scope");
+  const scopeId = identifier(source.scopeId, "knowledge scopeId");
+  const action = identifier(source.action, "knowledge action");
+  if (!["project", "team", "org"].includes(scope)) {
+    throw new Error("shared knowledge encryption scope is invalid");
+  }
+  if (!["upsert", "tombstone", "revoke"].includes(action)) {
+    throw new Error("shared knowledge action is invalid");
+  }
+  if (!DIGEST.test(source.contentDigest ?? "")) {
+    throw new TypeError("knowledge contentDigest is invalid");
+  }
+  plainRecord(source.vectorClock, "knowledge vectorClock");
+  return Object.freeze({
+    schema: GOVERNED_KNOWLEDGE_CRYPTO_AUTHORITY_SCHEMA,
+    tenantId,
+    knowledgeId,
+    scope,
+    scopeId,
+    action,
+    contentDigest: source.contentDigest,
+    vectorClock: structuredClone(source.vectorClock),
+  });
+}
+
+function aadFor(value) {
+  return Buffer.from(canonical(scopeBinding(value)), "utf8");
+}
+
+function normalizeScopeKeys(scopeKeys, tenantId) {
+  if (
+    !Array.isArray(scopeKeys) ||
+    scopeKeys.length < 1 ||
+    scopeKeys.length > 256
+  ) {
+    throw new TypeError("scopeKeys must contain 1..256 keys");
+  }
+  const byScope = new Map();
+  const byReference = new Map();
+  for (const input of scopeKeys) {
+    const record = plainRecord(input, "scope key");
+    const keyTenantId = identifier(record.tenantId, "scope key tenantId");
+    const scope = identifier(record.scope, "scope key scope");
+    const scopeId = identifier(record.scopeId, "scope key scopeId");
+    const keyRef = identifier(record.keyRef, "scope key keyRef");
+    if (
+      keyTenantId !== tenantId ||
+      !["project", "team", "org"].includes(scope)
+    ) {
+      throw new Error("scope key crossed its tenant or scope boundary");
+    }
+    if (!Buffer.isBuffer(record.key) || record.key.length !== 32) {
+      throw new TypeError("scope key must be a 32-byte AES key");
+    }
+    const binding = `${scope}\0${scopeId}`;
+    if (byReference.has(keyRef)) throw new Error("scope keyRef is duplicated");
+    byReference.set(keyRef, {
+      tenantId,
+      scope,
+      scopeId,
+      keyRef,
+      key: Buffer.from(record.key),
+    });
+    if (record.active === true) {
+      if (byScope.has(binding))
+        throw new Error("scope has multiple active keys");
+      byScope.set(binding, byReference.get(keyRef));
+    }
+  }
+  if (byScope.size < 1)
+    throw new Error("no active scope encryption key exists");
+  return { byScope, byReference };
+}
+
+function normalizePeers(peers, tenantId) {
+  if (!Array.isArray(peers) || peers.length < 1 || peers.length > 256) {
+    throw new TypeError("peerIdentities must contain 1..256 devices");
+  }
+  const result = new Map();
+  const keyIds = new Set();
+  for (const input of peers) {
+    const peer = plainRecord(input, "peer identity");
+    if (identifier(peer.tenantId, "peer tenantId") !== tenantId) {
+      throw new Error("peer identity crossed its tenant boundary");
+    }
+    const deviceId = identifier(peer.deviceId, "peer deviceId");
+    const publicKey = keyObject(peer.publicKey, "public", "peer publicKey");
+    const keyId = publicKeyId(publicKey);
+    if (peer.keyId !== undefined && peer.keyId !== keyId) {
+      throw new Error("peer keyId does not bind its Ed25519 public key");
+    }
+    if (result.has(deviceId))
+      throw new Error("peer device identity is duplicated");
+    if (keyIds.has(keyId)) {
+      throw new Error("peer Ed25519 key is assigned to multiple devices");
+    }
+    keyIds.add(keyId);
+    result.set(deviceId, { publicKey, keyId });
+  }
+  return result;
+}
+
+function signatureMessage(envelopeDigest) {
+  if (!DIGEST.test(envelopeDigest ?? "")) {
+    throw new TypeError("envelopeDigest is invalid");
+  }
+  return Buffer.from(
+    `chainlesschain.governed-knowledge-envelope-signature/v1\0${envelopeDigest}`,
+    "utf8",
+  );
+}
+
+export function createGovernedKnowledgeNodeCryptoAuthority({
+  tenantId: tenantIdInput,
+  deviceId: deviceIdInput,
+  privateKey: privateKeyInput,
+  scopeKeys,
+  peerIdentities,
+  random = randomBytes,
+} = {}) {
+  const tenantId = identifier(tenantIdInput, "tenantId");
+  const deviceId = identifier(deviceIdInput, "deviceId");
+  if (typeof random !== "function" || utilTypes.isProxy(random)) {
+    throw new TypeError("random must be a non-proxy function");
+  }
+  const privateKey = keyObject(privateKeyInput, "private", "privateKey");
+  const ownPublicKey = createPublicKey(privateKey);
+  const ownKeyId = publicKeyId(ownPublicKey);
+  const keys = normalizeScopeKeys(scopeKeys, tenantId);
+  const peers = normalizePeers(peerIdentities, tenantId);
+  const ownPeer = peers.get(deviceId);
+  if (!ownPeer || ownPeer.keyId !== ownKeyId) {
+    throw new Error("device private key is not pinned in peer identities");
+  }
+
+  const authority = Object.freeze({
+    schema: GOVERNED_KNOWLEDGE_CRYPTO_AUTHORITY_SCHEMA,
+    tenantId,
+    deviceId,
+    keyId: ownKeyId,
+    async encrypt({ knowledge, plaintext } = {}) {
+      const aad = aadFor(knowledge);
+      const binding = `${knowledge.scope}\0${knowledge.scopeId}`;
+      const scopeKey = keys.byScope.get(binding);
+      if (!scopeKey)
+        throw new Error("no active key exists for knowledge scope");
+      if (
+        !Buffer.isBuffer(plaintext) ||
+        plaintext.length < 1 ||
+        plaintext.length > MAX_PLAINTEXT_BYTES
+      ) {
+        throw new TypeError("knowledge plaintext is empty or unbounded");
+      }
+      const nonce = Buffer.from(random(NONCE_BYTES));
+      if (nonce.length !== NONCE_BYTES) {
+        throw new Error("crypto authority returned an invalid nonce");
+      }
+      const cipher = createCipheriv("aes-256-gcm", scopeKey.key, nonce);
+      cipher.setAAD(aad);
+      const encrypted = Buffer.concat([
+        cipher.update(plaintext),
+        cipher.final(),
+      ]);
+      const ciphertext = Buffer.concat([
+        Buffer.from([CIPHER_VERSION]),
+        nonce,
+        cipher.getAuthTag(),
+        encrypted,
+      ]);
+      return Object.freeze({
+        ciphertext,
+        ciphertextDigest: sha256(ciphertext),
+        keyRef: scopeKey.keyRef,
+      });
+    },
+    async decrypt({ envelope } = {}) {
+      const source = plainRecord(envelope, "knowledge envelope");
+      if (source.tenantId !== tenantId)
+        throw new Error("envelope tenant mismatch");
+      const scopeKey = keys.byReference.get(source.keyRef);
+      if (
+        !scopeKey ||
+        scopeKey.scope !== source.scope ||
+        scopeKey.scopeId !== source.scopeId
+      ) {
+        throw new Error("envelope key is not authorized for its scope");
+      }
+      const ciphertext = Buffer.from(source.ciphertext ?? "", "base64");
+      if (
+        ciphertext.length <= 1 + NONCE_BYTES + TAG_BYTES ||
+        ciphertext[0] !== CIPHER_VERSION ||
+        sha256(ciphertext) !== source.ciphertextDigest
+      ) {
+        throw new Error("encrypted knowledge payload is invalid");
+      }
+      const nonce = ciphertext.subarray(1, 1 + NONCE_BYTES);
+      const tag = ciphertext.subarray(
+        1 + NONCE_BYTES,
+        1 + NONCE_BYTES + TAG_BYTES,
+      );
+      const body = ciphertext.subarray(1 + NONCE_BYTES + TAG_BYTES);
+      const decipher = createDecipheriv("aes-256-gcm", scopeKey.key, nonce);
+      decipher.setAAD(aadFor(source));
+      decipher.setAuthTag(tag);
+      try {
+        return Object.freeze({
+          plaintext: Buffer.concat([decipher.update(body), decipher.final()]),
+        });
+      } catch {
+        throw new Error("encrypted knowledge authentication failed");
+      }
+    },
+    async sign({ envelopeDigest } = {}) {
+      return Object.freeze({
+        algorithm: "Ed25519",
+        keyId: ownKeyId,
+        value: sign(
+          null,
+          signatureMessage(envelopeDigest),
+          privateKey,
+        ).toString("base64url"),
+      });
+    },
+    async verify({ core, envelopeDigest, signature } = {}) {
+      const source = plainRecord(core, "knowledge envelope core");
+      const peer = peers.get(source.senderDeviceId);
+      if (
+        source.tenantId !== tenantId ||
+        !peer ||
+        !signature ||
+        typeof signature !== "object" ||
+        Array.isArray(signature) ||
+        Object.keys(signature).some((key) => !SIGNATURE_KEYS.has(key)) ||
+        signature.algorithm !== "Ed25519" ||
+        signature.keyId !== peer.keyId ||
+        typeof signature.value !== "string"
+      ) {
+        return false;
+      }
+      let bytes;
+      try {
+        bytes = Buffer.from(signature.value, "base64url");
+      } catch {
+        return false;
+      }
+      return (
+        bytes.length === 64 &&
+        bytes.toString("base64url") === signature.value &&
+        verify(null, signatureMessage(envelopeDigest), peer.publicKey, bytes)
+      );
+    },
+  });
+  AUTHORITIES.add(authority);
+  return authority;
+}
+
+export function isGovernedKnowledgeNodeCryptoAuthority(value) {
+  return AUTHORITIES.has(value);
+}