@bcts/envelope 1.0.0-alpha.10

package/src/extension/attachment.ts

@@ -0,0 +1,280 @@
+/**
+ * Attachment Extension for Gordian Envelope
+ *
+ * Provides functionality for attaching vendor-specific metadata to envelopes.
+ * Attachments enable flexible, extensible data storage without modifying
+ * the core data model, facilitating interoperability and future compatibility.
+ *
+ * Each attachment has:
+ * - A payload (arbitrary data)
+ * - A required vendor identifier (typically a reverse domain name)
+ * - An optional conformsTo URI that indicates the format of the attachment
+ *
+ * See BCR-2023-006: https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2023-006-envelope-attachment.md
+ */
+
+import { Envelope } from "../base/envelope";
+import { type Digest } from "../base/digest";
+import { EnvelopeError } from "../base/error";
+import type { EnvelopeEncodableValue } from "../base/envelope-encodable";
+
+/**
+ * Known value for the 'attachment' predicate.
+ */
+export const ATTACHMENT = "attachment";
+
+/**
+ * Known value for the 'vendor' predicate.
+ */
+export const VENDOR = "vendor";
+
+/**
+ * Known value for the 'conformsTo' predicate.
+ */
+export const CONFORMS_TO = "conformsTo";
+
+/**
+ * A container for vendor-specific metadata attachments.
+ *
+ * Attachments provides a flexible mechanism for attaching arbitrary metadata
+ * to envelopes without modifying their core structure.
+ */
+export class Attachments {
+  readonly #envelopes = new Map<string, Envelope>();
+
+  /**
+   * Creates a new empty attachments container.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  constructor() {}
+
+  /**
+   * Adds a new attachment with the specified payload and metadata.
+   *
+   * @param payload - The data to attach
+   * @param vendor - A string identifying the entity that defined the attachment format
+   * @param conformsTo - Optional URI identifying the structure the payload conforms to
+   */
+  add(payload: EnvelopeEncodableValue, vendor: string, conformsTo?: string): void {
+    const attachment = Envelope.newAttachment(payload, vendor, conformsTo);
+    this.#envelopes.set(attachment.digest().hex(), attachment);
+  }
+
+  /**
+   * Retrieves an attachment by its digest.
+   *
+   * @param digest - The unique digest of the attachment to retrieve
+   * @returns The envelope if found, or undefined
+   */
+  get(digest: Digest): Envelope | undefined {
+    return this.#envelopes.get(digest.hex());
+  }
+
+  /**
+   * Removes an attachment by its digest.
+   *
+   * @param digest - The unique digest of the attachment to remove
+   * @returns The removed envelope if found, or undefined
+   */
+  remove(digest: Digest): Envelope | undefined {
+    const envelope = this.#envelopes.get(digest.hex());
+    this.#envelopes.delete(digest.hex());
+    return envelope;
+  }
+
+  /**
+   * Removes all attachments from the container.
+   */
+  clear(): void {
+    this.#envelopes.clear();
+  }
+
+  /**
+   * Returns whether the container has any attachments.
+   */
+  isEmpty(): boolean {
+    return this.#envelopes.size === 0;
+  }
+
+  /**
+   * Adds all attachments from this container to an envelope.
+   *
+   * @param envelope - The envelope to add attachments to
+   * @returns A new envelope with all attachments added as assertions
+   */
+  addToEnvelope(envelope: Envelope): Envelope {
+    let result = envelope;
+    for (const attachment of this.#envelopes.values()) {
+      result = result.addAssertion(ATTACHMENT, attachment);
+    }
+    return result;
+  }
+
+  /**
+   * Creates an Attachments container from an envelope's attachment assertions.
+   *
+   * @param envelope - The envelope to extract attachments from
+   * @returns A new Attachments container with the envelope's attachments
+   */
+  static fromEnvelope(envelope: Envelope): Attachments {
+    const attachments = new Attachments();
+    const attachmentEnvelopes = envelope.attachments();
+
+    for (const attachment of attachmentEnvelopes) {
+      attachments.#envelopes.set(attachment.digest().hex(), attachment);
+    }
+
+    return attachments;
+  }
+}
+
+// Implementation
+
+/**
+ * Creates a new attachment envelope.
+ */
+Envelope.newAttachment = function (
+  payload: EnvelopeEncodableValue,
+  vendor: string,
+  conformsTo?: string,
+): Envelope {
+  // Create the payload envelope wrapped with vendor assertion
+  let attachmentObj = Envelope.new(payload).wrap().addAssertion(VENDOR, vendor);
+
+  // Add optional conformsTo
+  if (conformsTo !== undefined) {
+    attachmentObj = attachmentObj.addAssertion(CONFORMS_TO, conformsTo);
+  }
+
+  // Create an assertion with 'attachment' as predicate and the wrapped payload as object
+  // This returns an assertion envelope
+  const attachmentPredicate = Envelope.new(ATTACHMENT);
+  return attachmentPredicate.addAssertion(ATTACHMENT, attachmentObj).assertions()[0];
+};
+
+/**
+ * Adds an attachment to an envelope.
+ */
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (Envelope?.prototype) {
+  Envelope.prototype.addAttachment = function (
+    this: Envelope,
+    payload: EnvelopeEncodableValue,
+    vendor: string,
+    conformsTo?: string,
+  ): Envelope {
+    let attachmentObj = Envelope.new(payload).wrap().addAssertion(VENDOR, vendor);
+
+    if (conformsTo !== undefined) {
+      attachmentObj = attachmentObj.addAssertion(CONFORMS_TO, conformsTo);
+    }
+
+    return this.addAssertion(ATTACHMENT, attachmentObj);
+  };
+
+  /**
+   * Returns the payload of an attachment envelope.
+   */
+  Envelope.prototype.attachmentPayload = function (this: Envelope): Envelope {
+    const c = this.case();
+    if (c.type !== "assertion") {
+      throw EnvelopeError.general("Envelope is not an attachment assertion");
+    }
+
+    const obj = c.assertion.object();
+    return obj.unwrap();
+  };
+
+  /**
+   * Returns the vendor of an attachment envelope.
+   */
+  Envelope.prototype.attachmentVendor = function (this: Envelope): string {
+    const c = this.case();
+    if (c.type !== "assertion") {
+      throw EnvelopeError.general("Envelope is not an attachment assertion");
+    }
+
+    const obj = c.assertion.object();
+    const vendorEnv = obj.objectForPredicate(VENDOR);
+    const vendor = vendorEnv.asText();
+
+    if (vendor === undefined || vendor === "") {
+      throw EnvelopeError.general("Attachment has no vendor");
+    }
+
+    return vendor;
+  };
+
+  /**
+   * Returns the conformsTo of an attachment envelope.
+   */
+  Envelope.prototype.attachmentConformsTo = function (this: Envelope): string | undefined {
+    const c = this.case();
+    if (c.type !== "assertion") {
+      throw EnvelopeError.general("Envelope is not an attachment assertion");
+    }
+
+    const obj = c.assertion.object();
+    const conformsToEnv = obj.optionalObjectForPredicate(CONFORMS_TO);
+
+    if (conformsToEnv === undefined) {
+      return undefined;
+    }
+
+    return conformsToEnv.asText();
+  };
+
+  /**
+   * Returns all attachment assertions.
+   */
+  Envelope.prototype.attachments = function (this: Envelope): Envelope[] {
+    return this.assertionsWithPredicate(ATTACHMENT).map((a) => {
+      const c = a.case();
+      if (c.type === "assertion") {
+        return c.assertion.object();
+      }
+      throw EnvelopeError.general("Invalid attachment assertion");
+    });
+  };
+
+  /**
+   * Returns attachments matching vendor and/or conformsTo.
+   */
+  Envelope.prototype.attachmentsWithVendorAndConformsTo = function (
+    this: Envelope,
+    vendor?: string,
+    conformsTo?: string,
+  ): Envelope[] {
+    const allAttachments = this.attachments();
+
+    return allAttachments.filter((attachment) => {
+      try {
+        // The attachment is already a wrapped envelope with vendor/conformsTo assertions
+        // Check vendor if specified
+        if (vendor !== undefined) {
+          const vendorEnv = attachment.objectForPredicate(VENDOR);
+          const attachmentVendor = vendorEnv.asText();
+          if (attachmentVendor !== vendor) {
+            return false;
+          }
+        }
+
+        // Check conformsTo if specified
+        if (conformsTo !== undefined) {
+          const conformsToEnv = attachment.optionalObjectForPredicate(CONFORMS_TO);
+          if (conformsToEnv === undefined) {
+            return false;
+          }
+          const conformsToText = conformsToEnv.asText();
+          if (conformsToText !== conformsTo) {
+            return false;
+          }
+        }
+
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  };
+}

package/src/extension/compress.ts

@@ -0,0 +1,176 @@
+import { Envelope } from "../base/envelope";
+import { EnvelopeError } from "../base/error";
+import { type Digest } from "../base/digest";
+import * as pako from "pako";
+import { cborData, decodeCbor } from "@bcts/dcbor";
+
+/// Extension for compressing and decompressing envelopes.
+///
+/// This module provides functionality for compressing envelopes to reduce their
+/// size while maintaining their digests. Unlike elision, which removes content,
+/// compression preserves all the information in the envelope but represents it
+/// more efficiently.
+///
+/// Compression is implemented using the DEFLATE algorithm (via pako) and preserves
+/// the envelope's digest, making it compatible with the envelope's hierarchical
+/// digest tree structure.
+///
+/// @example
+/// ```typescript
+/// // Create an envelope with some larger, compressible content
+/// const lorem = "Lorem ipsum dolor sit amet...".repeat(10);
+/// const envelope = Envelope.new(lorem);
+///
+/// // Compress the envelope
+/// const compressed = envelope.compress();
+///
+/// // The compressed envelope has the same digest as the original
+/// console.log(envelope.digest().equals(compressed.digest())); // true
+///
+/// // But it takes up less space when serialized
+/// console.log(compressed.cborBytes().length < envelope.cborBytes().length); // true
+///
+/// // The envelope can be decompressed to recover the original content
+/// const decompressed = compressed.decompress();
+/// console.log(decompressed.asText() === lorem); // true
+/// ```
+
+/// Represents compressed data with optional digest
+export class Compressed {
+  readonly #compressedData: Uint8Array;
+  readonly #digest?: Digest;
+
+  constructor(compressedData: Uint8Array, digest?: Digest) {
+    this.#compressedData = compressedData;
+    if (digest !== undefined) {
+      this.#digest = digest;
+    }
+  }
+
+  /// Creates a Compressed instance from decompressed data
+  static fromDecompressedData(decompressedData: Uint8Array, digest?: Digest): Compressed {
+    const compressed = pako.deflate(decompressedData);
+    return new Compressed(compressed, digest);
+  }
+
+  /// Returns the compressed data
+  compressedData(): Uint8Array {
+    return this.#compressedData;
+  }
+
+  /// Returns the optional digest
+  digestOpt(): Digest | undefined {
+    return this.#digest;
+  }
+
+  /// Decompresses the data
+  decompress(): Uint8Array {
+    return pako.inflate(this.#compressedData);
+  }
+}
+
+/// Register compression extension methods on Envelope prototype
+/// This function is exported and called during module initialization
+/// to ensure Envelope is fully defined before attaching methods.
+export function registerCompressExtension(): void {
+  if (Envelope?.prototype === undefined) {
+    return;
+  }
+
+  // Skip if already registered
+  if (typeof Envelope.prototype.compress === "function") {
+    return;
+  }
+
+  Envelope.prototype.compress = function (this: Envelope): Envelope {
+    const c = this.case();
+
+    // If already compressed, return as-is
+    if (c.type === "compressed") {
+      return this;
+    }
+
+    // Can't compress encrypted or elided envelopes
+    if (c.type === "encrypted") {
+      throw EnvelopeError.general("Cannot compress encrypted envelope");
+    }
+    if (c.type === "elided") {
+      throw EnvelopeError.general("Cannot compress elided envelope");
+    }
+
+    // Compress the entire envelope
+    const cbor = this.taggedCbor();
+
+    const decompressedData = cborData(cbor);
+
+    const compressed = Compressed.fromDecompressedData(decompressedData, this.digest());
+
+    // Create a compressed envelope case
+    return Envelope.fromCase({ type: "compressed", value: compressed });
+  };
+
+  /// Implementation of decompress()
+  Envelope.prototype.decompress = function (this: Envelope): Envelope {
+    const c = this.case();
+
+    if (c.type !== "compressed") {
+      throw EnvelopeError.general("Envelope is not compressed");
+    }
+
+    const compressed = c.value;
+    const digest = compressed.digestOpt();
+
+    if (digest === undefined) {
+      throw EnvelopeError.general("Missing digest in compressed envelope");
+    }
+
+    // Verify the digest matches
+    if (!digest.equals(this.digest())) {
+      throw EnvelopeError.general("Invalid digest in compressed envelope");
+    }
+
+    // Decompress the data
+    const decompressedData = compressed.decompress();
+
+    // Parse back to envelope
+
+    const cbor = decodeCbor(decompressedData);
+    const envelope = Envelope.fromTaggedCbor(cbor);
+
+    // Verify the decompressed envelope has the correct digest
+    if (!envelope.digest().equals(digest)) {
+      throw EnvelopeError.general("Invalid digest after decompression");
+    }
+
+    return envelope;
+  };
+
+  /// Implementation of compressSubject()
+  Envelope.prototype.compressSubject = function (this: Envelope): Envelope {
+    if (this.subject().isCompressed()) {
+      return this;
+    }
+
+    const subject = this.subject().compress();
+    return this.replaceSubject(subject);
+  };
+
+  /// Implementation of decompressSubject()
+  Envelope.prototype.decompressSubject = function (this: Envelope): Envelope {
+    if (this.subject().isCompressed()) {
+      const subject = this.subject().decompress();
+      return this.replaceSubject(subject);
+    }
+
+    return this;
+  };
+
+  /// Implementation of isCompressed()
+  Envelope.prototype.isCompressed = function (this: Envelope): boolean {
+    return this.case().type === "compressed";
+  };
+}
+
+// Auto-register on module load - will be called again from index.ts
+// to ensure proper ordering after all modules are loaded
+registerCompressExtension();