@bcts/envelope 1.0.0-alpha.10

package/src/base/digest.ts

@@ -0,0 +1,204 @@
+import { sha256 } from "@bcts/crypto";
+
+/// A cryptographic digest used to uniquely identify digital objects.
+///
+/// Digests in Gordian Envelope are always SHA-256 hashes (32 bytes).
+/// This is a fundamental building block for the Merkle-like digest tree
+/// that enables privacy features while maintaining integrity.
+///
+/// Based on BCR-2021-002: Digests for Digital Objects
+/// @see https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2021-002-digest.md
+export class Digest {
+  readonly #data: Uint8Array;
+
+  /// Creates a new Digest from raw bytes.
+  ///
+  /// @param data - The 32-byte digest data
+  /// @throws {Error} If data is not exactly 32 bytes
+  constructor(data: Uint8Array) {
+    if (data.length !== 32) {
+      throw new Error(`Digest must be exactly 32 bytes, got ${data.length} bytes`);
+    }
+    this.#data = data;
+  }
+
+  /// Returns the raw digest bytes.
+  ///
+  /// @returns A Uint8Array containing the 32-byte digest
+  data(): Uint8Array {
+    return this.#data;
+  }
+
+  /// Creates a digest from an image (arbitrary byte array).
+  ///
+  /// This is the primary way to create a digest from data. The data is
+  /// hashed using SHA-256 to produce a 32-byte digest.
+  ///
+  /// @param image - The data to hash
+  /// @returns A new Digest instance
+  ///
+  /// @example
+  /// ```typescript
+  /// const digest = Digest.fromImage(new TextEncoder().encode("Hello, world!"));
+  /// ```
+  static fromImage(image: Uint8Array): Digest {
+    const hash = sha256(image);
+    return new Digest(hash);
+  }
+
+  /// Creates a digest from multiple digests.
+  ///
+  /// This is used to combine digests in the Merkle-like tree structure.
+  /// The digests are concatenated and then hashed.
+  ///
+  /// @param digests - An array of digests to combine
+  /// @returns A new Digest instance representing the combined digests
+  ///
+  /// @example
+  /// ```typescript
+  /// const digest1 = Digest.fromImage(data1);
+  /// const digest2 = Digest.fromImage(data2);
+  /// const combined = Digest.fromDigests([digest1, digest2]);
+  /// ```
+  static fromDigests(digests: Digest[]): Digest {
+    const totalLength = digests.length * 32;
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const digest of digests) {
+      combined.set(digest.data(), offset);
+      offset += 32;
+    }
+    return Digest.fromImage(combined);
+  }
+
+  /// Returns the hexadecimal string representation of the digest.
+  ///
+  /// @returns A 64-character hexadecimal string
+  ///
+  /// @example
+  /// ```typescript
+  /// const digest = Digest.fromImage(data);
+  /// console.log(digest.hex()); // "5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"
+  /// ```
+  hex(): string {
+    return Array.from(this.#data)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  /// Returns an abbreviated hexadecimal representation for visual comparison.
+  ///
+  /// Following Blockchain Commons conventions, this returns the first 7
+  /// hexadecimal digits of the digest, which provides sufficient entropy
+  /// for human visual comparison while being easy to read.
+  ///
+  /// @returns A 7-character hexadecimal string
+  ///
+  /// @example
+  /// ```typescript
+  /// const digest = Digest.fromImage(data);
+  /// console.log(digest.short()); // "5feceb6"
+  /// ```
+  short(): string {
+    return this.hex().substring(0, 7);
+  }
+
+  /// Creates a digest from a hexadecimal string.
+  ///
+  /// @param hex - A 64-character hexadecimal string
+  /// @returns A new Digest instance
+  /// @throws {Error} If the hex string is not exactly 64 characters
+  ///
+  /// @example
+  /// ```typescript
+  /// const digest = Digest.fromHex("5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9");
+  /// ```
+  static fromHex(hex: string): Digest {
+    if (hex.length !== 64) {
+      throw new Error(`Hex string must be exactly 64 characters, got ${hex.length}`);
+    }
+    const data = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      data[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    }
+    return new Digest(data);
+  }
+
+  /// Checks if two digests are equal.
+  ///
+  /// @param other - The other digest to compare with
+  /// @returns `true` if the digests are equal, `false` otherwise
+  equals(other: Digest): boolean {
+    if (this.#data.length !== other.#data.length) {
+      return false;
+    }
+    for (let i = 0; i < this.#data.length; i++) {
+      if (this.#data[i] !== other.#data[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /// Returns a string representation of the digest (short form).
+  ///
+  /// @returns The short hexadecimal representation
+  toString(): string {
+    return this.short();
+  }
+
+  /// Creates a deep copy of the digest.
+  ///
+  /// @returns A new Digest instance with the same data
+  clone(): Digest {
+    return new Digest(new Uint8Array(this.#data));
+  }
+}
+
+/// Trait for types that can provide a digest.
+///
+/// This is equivalent to Rust's `DigestProvider` trait. Types that
+/// implement this interface can be used in contexts where a digest
+/// is needed for identity or integrity verification.
+export interface DigestProvider {
+  /// Returns the digest of this object.
+  ///
+  /// The digest uniquely identifies the semantic content of the object,
+  /// regardless of whether parts of it are elided, encrypted, or compressed.
+  digest(): Digest;
+}
+
+/// Helper function to create a digest from a string.
+///
+/// This is a convenience function for creating digests from text strings,
+/// which are encoded as UTF-8 before hashing.
+///
+/// @param text - The text to hash
+/// @returns A new Digest instance
+///
+/// @example
+/// ```typescript
+/// const digest = digestFromString("Hello, world!");
+/// ```
+export function digestFromString(text: string): Digest {
+  const encoder = new TextEncoder();
+  return Digest.fromImage(encoder.encode(text));
+}
+
+/// Helper function to create a digest from a number.
+///
+/// The number is converted to a big-endian byte representation before hashing.
+///
+/// @param num - The number to hash
+/// @returns A new Digest instance
+///
+/// @example
+/// ```typescript
+/// const digest = digestFromNumber(42);
+/// ```
+export function digestFromNumber(num: number): Digest {
+  const buffer = new ArrayBuffer(8);
+  const view = new DataView(buffer);
+  view.setFloat64(0, num, false); // big-endian
+  return Digest.fromImage(new Uint8Array(buffer));
+}

package/src/base/elide.ts

@@ -0,0 +1,390 @@
+import { type Digest, type DigestProvider } from "./digest";
+import { Envelope } from "./envelope";
+import { Assertion } from "./assertion";
+import { EnvelopeError } from "./error";
+
+/// Types of obscuration that can be applied to envelope elements.
+///
+/// This enum identifies the different ways an envelope element can be obscured.
+export enum ObscureType {
+  /// The element has been elided, showing only its digest.
+  Elided = "elided",
+
+  /// The element has been encrypted using symmetric encryption.
+  /// TODO: Implement when encrypt feature is added
+  Encrypted = "encrypted",
+
+  /// The element has been compressed to reduce its size.
+  /// TODO: Implement when compress feature is added
+  Compressed = "compressed",
+}
+
+/// Actions that can be performed on parts of an envelope to obscure them.
+///
+/// Gordian Envelope supports several ways to obscure parts of an envelope while
+/// maintaining its semantic integrity and digest tree.
+export type ObscureAction =
+  | { type: "elide" }
+  | { type: "encrypt"; key: unknown } // TODO: SymmetricKey type
+  | { type: "compress" };
+
+/// Helper to create elide action
+export function elideAction(): ObscureAction {
+  return { type: "elide" };
+}
+
+/// Implementation of elide()
+Envelope.prototype.elide = function (this: Envelope): Envelope {
+  const c = this.case();
+  if (c.type === "elided") {
+    return this;
+  }
+  return Envelope.newElided(this.digest());
+};
+
+/// Core elision logic
+function elideSetWithAction(
+  envelope: Envelope,
+  target: Set<Digest>,
+  isRevealing: boolean,
+  action: ObscureAction,
+): Envelope {
+  const selfDigest = envelope.digest();
+  const targetContainsSelf = Array.from(target).some((d) => d.equals(selfDigest));
+
+  // Target Matches  isRevealing  elide
+  // false          false         false
+  // false          true          true
+  // true           false         true
+  // true           true          false
+
+  if (targetContainsSelf !== isRevealing) {
+    // Should obscure this envelope
+    if (action.type === "elide") {
+      return envelope.elide();
+    } else if (action.type === "encrypt") {
+      // TODO: Implement encryption
+      throw new Error("Encryption not yet implemented");
+    } else if (action.type === "compress") {
+      // TODO: Implement compression
+      throw new Error("Compression not yet implemented");
+    }
+  }
+
+  const c = envelope.case();
+
+  // Recursively process structure
+  if (c.type === "assertion") {
+    const predicate = elideSetWithAction(c.assertion.predicate(), target, isRevealing, action);
+    const object = elideSetWithAction(c.assertion.object(), target, isRevealing, action);
+    const elidedAssertion = new Assertion(predicate, object);
+    return Envelope.newWithAssertion(elidedAssertion);
+  } else if (c.type === "node") {
+    const elidedSubject = elideSetWithAction(c.subject, target, isRevealing, action);
+    const elidedAssertions = c.assertions.map((a) =>
+      elideSetWithAction(a, target, isRevealing, action),
+    );
+    return Envelope.newWithUncheckedAssertions(elidedSubject, elidedAssertions);
+  } else if (c.type === "wrapped") {
+    const elidedEnvelope = elideSetWithAction(c.envelope, target, isRevealing, action);
+    return Envelope.newWrapped(elidedEnvelope);
+  }
+
+  return envelope;
+}
+
+/// Implementation of elideRemovingSetWithAction
+Envelope.prototype.elideRemovingSetWithAction = function (
+  this: Envelope,
+  target: Set<Digest>,
+  action: ObscureAction,
+): Envelope {
+  return elideSetWithAction(this, target, false, action);
+};
+
+/// Implementation of elideRemovingSet
+Envelope.prototype.elideRemovingSet = function (this: Envelope, target: Set<Digest>): Envelope {
+  return elideSetWithAction(this, target, false, elideAction());
+};
+
+/// Implementation of elideRemovingArrayWithAction
+Envelope.prototype.elideRemovingArrayWithAction = function (
+  this: Envelope,
+  target: DigestProvider[],
+  action: ObscureAction,
+): Envelope {
+  const targetSet = new Set(target.map((p) => p.digest()));
+  return elideSetWithAction(this, targetSet, false, action);
+};
+
+/// Implementation of elideRemovingArray
+Envelope.prototype.elideRemovingArray = function (
+  this: Envelope,
+  target: DigestProvider[],
+): Envelope {
+  const targetSet = new Set(target.map((p) => p.digest()));
+  return elideSetWithAction(this, targetSet, false, elideAction());
+};
+
+/// Implementation of elideRemovingTargetWithAction
+Envelope.prototype.elideRemovingTargetWithAction = function (
+  this: Envelope,
+  target: DigestProvider,
+  action: ObscureAction,
+): Envelope {
+  return this.elideRemovingArrayWithAction([target], action);
+};
+
+/// Implementation of elideRemovingTarget
+Envelope.prototype.elideRemovingTarget = function (
+  this: Envelope,
+  target: DigestProvider,
+): Envelope {
+  return this.elideRemovingArray([target]);
+};
+
+/// Implementation of elideRevealingSetWithAction
+Envelope.prototype.elideRevealingSetWithAction = function (
+  this: Envelope,
+  target: Set<Digest>,
+  action: ObscureAction,
+): Envelope {
+  return elideSetWithAction(this, target, true, action);
+};
+
+/// Implementation of elideRevealingSet
+Envelope.prototype.elideRevealingSet = function (this: Envelope, target: Set<Digest>): Envelope {
+  return elideSetWithAction(this, target, true, elideAction());
+};
+
+/// Implementation of elideRevealingArrayWithAction
+Envelope.prototype.elideRevealingArrayWithAction = function (
+  this: Envelope,
+  target: DigestProvider[],
+  action: ObscureAction,
+): Envelope {
+  const targetSet = new Set(target.map((p) => p.digest()));
+  return elideSetWithAction(this, targetSet, true, action);
+};
+
+/// Implementation of elideRevealingArray
+Envelope.prototype.elideRevealingArray = function (
+  this: Envelope,
+  target: DigestProvider[],
+): Envelope {
+  const targetSet = new Set(target.map((p) => p.digest()));
+  return elideSetWithAction(this, targetSet, true, elideAction());
+};
+
+/// Implementation of elideRevealingTargetWithAction
+Envelope.prototype.elideRevealingTargetWithAction = function (
+  this: Envelope,
+  target: DigestProvider,
+  action: ObscureAction,
+): Envelope {
+  return this.elideRevealingArrayWithAction([target], action);
+};
+
+/// Implementation of elideRevealingTarget
+Envelope.prototype.elideRevealingTarget = function (
+  this: Envelope,
+  target: DigestProvider,
+): Envelope {
+  return this.elideRevealingArray([target]);
+};
+
+/// Implementation of unelide
+Envelope.prototype.unelide = function (this: Envelope, envelope: Envelope): Envelope {
+  if (this.digest().equals(envelope.digest())) {
+    return envelope;
+  }
+  throw EnvelopeError.invalidDigest();
+};
+
+/// Implementation of nodesMatching
+Envelope.prototype.nodesMatching = function (
+  this: Envelope,
+  targetDigests: Set<Digest> | undefined,
+  obscureTypes: ObscureType[],
+): Set<Digest> {
+  const result = new Set<Digest>();
+
+  const visitor = (envelope: Envelope): void => {
+    // Check if this node matches the target digests
+    const digestMatches =
+      targetDigests === undefined ||
+      Array.from(targetDigests).some((d) => d.equals(envelope.digest()));
+
+    if (!digestMatches) {
+      return;
+    }
+
+    // If no obscure types specified, include all nodes
+    if (obscureTypes.length === 0) {
+      result.add(envelope.digest());
+      return;
+    }
+
+    // Check if this node matches any of the specified obscure types
+    const c = envelope.case();
+    const typeMatches = obscureTypes.some((obscureType) => {
+      if (obscureType === ObscureType.Elided && c.type === "elided") {
+        return true;
+      }
+      if (obscureType === ObscureType.Encrypted && c.type === "encrypted") {
+        return true;
+      }
+      if (obscureType === ObscureType.Compressed && c.type === "compressed") {
+        return true;
+      }
+      return false;
+    });
+
+    if (typeMatches) {
+      result.add(envelope.digest());
+    }
+  };
+
+  // Walk the envelope tree
+  walkEnvelope(this, visitor);
+
+  return result;
+};
+
+/// Helper to walk envelope tree
+function walkEnvelope(envelope: Envelope, visitor: (e: Envelope) => void): void {
+  visitor(envelope);
+
+  const c = envelope.case();
+  if (c.type === "node") {
+    walkEnvelope(c.subject, visitor);
+    for (const assertion of c.assertions) {
+      walkEnvelope(assertion, visitor);
+    }
+  } else if (c.type === "assertion") {
+    walkEnvelope(c.assertion.predicate(), visitor);
+    walkEnvelope(c.assertion.object(), visitor);
+  } else if (c.type === "wrapped") {
+    walkEnvelope(c.envelope, visitor);
+  }
+}
+
+/// Implementation of walkUnelide
+Envelope.prototype.walkUnelide = function (this: Envelope, envelopes: Envelope[]): Envelope {
+  // Build a lookup map of digest -> envelope
+  const envelopeMap = new Map<string, Envelope>();
+  for (const env of envelopes) {
+    envelopeMap.set(env.digest().hex(), env);
+  }
+
+  return walkUnelideWithMap(this, envelopeMap);
+};
+
+/// Helper for walkUnelide with map
+function walkUnelideWithMap(envelope: Envelope, envelopeMap: Map<string, Envelope>): Envelope {
+  const c = envelope.case();
+
+  if (c.type === "elided") {
+    // Try to find a matching envelope to restore
+    const replacement = envelopeMap.get(envelope.digest().hex());
+    return replacement ?? envelope;
+  }
+
+  if (c.type === "node") {
+    const newSubject = walkUnelideWithMap(c.subject, envelopeMap);
+    const newAssertions = c.assertions.map((a) => walkUnelideWithMap(a, envelopeMap));
+
+    if (
+      newSubject.isIdenticalTo(c.subject) &&
+      newAssertions.every((a, i) => a.isIdenticalTo(c.assertions[i]))
+    ) {
+      return envelope;
+    }
+
+    return Envelope.newWithUncheckedAssertions(newSubject, newAssertions);
+  }
+
+  if (c.type === "wrapped") {
+    const newEnvelope = walkUnelideWithMap(c.envelope, envelopeMap);
+    if (newEnvelope.isIdenticalTo(c.envelope)) {
+      return envelope;
+    }
+    return Envelope.newWrapped(newEnvelope);
+  }
+
+  if (c.type === "assertion") {
+    const newPredicate = walkUnelideWithMap(c.assertion.predicate(), envelopeMap);
+    const newObject = walkUnelideWithMap(c.assertion.object(), envelopeMap);
+
+    if (
+      newPredicate.isIdenticalTo(c.assertion.predicate()) &&
+      newObject.isIdenticalTo(c.assertion.object())
+    ) {
+      return envelope;
+    }
+
+    return Envelope.newAssertion(newPredicate, newObject);
+  }
+
+  return envelope;
+}
+
+/// Implementation of walkReplace
+Envelope.prototype.walkReplace = function (
+  this: Envelope,
+  target: Set<Digest>,
+  replacement: Envelope,
+): Envelope {
+  // Check if this node matches the target
+  if (Array.from(target).some((d) => d.equals(this.digest()))) {
+    return replacement;
+  }
+
+  const c = this.case();
+
+  if (c.type === "node") {
+    const newSubject = c.subject.walkReplace(target, replacement);
+    const newAssertions = c.assertions.map((a) => a.walkReplace(target, replacement));
+
+    if (
+      newSubject.isIdenticalTo(c.subject) &&
+      newAssertions.every((a, i) => a.isIdenticalTo(c.assertions[i]))
+    ) {
+      return this;
+    }
+
+    // Validate that all assertions are either assertions or obscured
+    return Envelope.newWithAssertions(newSubject, newAssertions);
+  }
+
+  if (c.type === "wrapped") {
+    const newEnvelope = c.envelope.walkReplace(target, replacement);
+    if (newEnvelope.isIdenticalTo(c.envelope)) {
+      return this;
+    }
+    return Envelope.newWrapped(newEnvelope);
+  }
+
+  if (c.type === "assertion") {
+    const newPredicate = c.assertion.predicate().walkReplace(target, replacement);
+    const newObject = c.assertion.object().walkReplace(target, replacement);
+
+    if (
+      newPredicate.isIdenticalTo(c.assertion.predicate()) &&
+      newObject.isIdenticalTo(c.assertion.object())
+    ) {
+      return this;
+    }
+
+    return Envelope.newAssertion(newPredicate, newObject);
+  }
+
+  return this;
+};
+
+/// Implementation of isIdenticalTo
+Envelope.prototype.isIdenticalTo = function (this: Envelope, other: Envelope): boolean {
+  // Two envelopes are identical if they have the same digest
+  // and the same case type (to handle wrapped vs unwrapped with same content)
+  return this.digest().equals(other.digest()) && this.case().type === other.case().type;
+};