@bcts/envelope 1.0.0-alpha.5

package/src/extension/attachment.ts

@@ -0,0 +1,369 @@
+/**
+ * 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;
+  }
+}
+
+/**
+ * Support for attachments in envelopes.
+ */
+declare module "../base/envelope" {
+  interface Envelope {
+    /**
+     * Creates a new envelope with an attachment as its subject.
+     *
+     * The attachment consists of:
+     * - The predicate 'attachment'
+     * - An object that is a wrapped envelope containing:
+     *   - The payload (as the subject)
+     *   - A required 'vendor': String assertion
+     *   - An optional 'conformsTo': String assertion
+     *
+     * @param payload - The content of the attachment
+     * @param vendor - A string identifying the entity (typically reverse domain name)
+     * @param conformsTo - Optional URI identifying the format of the attachment
+     * @returns A new attachment envelope
+     *
+     * @example
+     * ```typescript
+     * const attachment = Envelope.newAttachment(
+     *   "Custom data",
+     *   "com.example",
+     *   "https://example.com/format/v1"
+     * );
+     * ```
+     */
+    addAttachment(payload: EnvelopeEncodableValue, vendor: string, conformsTo?: string): Envelope;
+
+    /**
+     * Returns the payload of an attachment envelope.
+     *
+     * @returns The payload envelope
+     * @throws {EnvelopeError} If the envelope is not a valid attachment
+     */
+    attachmentPayload(): Envelope;
+
+    /**
+     * Returns the vendor identifier of an attachment envelope.
+     *
+     * @returns The vendor string
+     * @throws {EnvelopeError} If the envelope is not a valid attachment
+     */
+    attachmentVendor(): string;
+
+    /**
+     * Returns the optional conformsTo URI of an attachment envelope.
+     *
+     * @returns The conformsTo string if present, or undefined
+     * @throws {EnvelopeError} If the envelope is not a valid attachment
+     */
+    attachmentConformsTo(): string | undefined;
+
+    /**
+     * Returns all attachment assertions in this envelope.
+     *
+     * @returns Array of attachment envelopes
+     */
+    attachments(): Envelope[];
+
+    /**
+     * Searches for attachments matching the given vendor and conformsTo.
+     *
+     * @param vendor - Optional vendor identifier to match
+     * @param conformsTo - Optional conformsTo URI to match
+     * @returns Array of matching attachment envelopes
+     */
+    attachmentsWithVendorAndConformsTo(vendor?: string, conformsTo?: string): Envelope[];
+  }
+
+  namespace Envelope {
+    /**
+     * Creates a new attachment envelope.
+     *
+     * @param payload - The content of the attachment
+     * @param vendor - A string identifying the entity
+     * @param conformsTo - Optional URI identifying the format
+     * @returns A new attachment envelope
+     */
+    function newAttachment(
+      payload: EnvelopeEncodableValue,
+      vendor: string,
+      conformsTo?: string,
+    ): Envelope;
+  }
+}
+
+// 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,293 @@
+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);
+  }
+}
+
+declare module "../base/envelope" {
+  interface Envelope {
+    /// Returns a compressed version of this envelope.
+    ///
+    /// This method compresses the envelope using the DEFLATE algorithm,
+    /// creating a more space-efficient representation while preserving the
+    /// envelope's digest and semantic content. The compressed envelope
+    /// maintains the same digest as the original, ensuring compatibility
+    /// with the envelope's digest tree structure.
+    ///
+    /// When an envelope is compressed, the entire envelope structure (including
+    /// its subject and assertions) is compressed as a single unit. The
+    /// compression preserves all the information but reduces the size of
+    /// the serialized envelope.
+    ///
+    /// @returns The compressed envelope
+    /// @throws {EnvelopeError} If the envelope is already encrypted or elided
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with some content
+    /// const text = "This is a fairly long text that will benefit from compression.";
+    /// const envelope = Envelope.new(text);
+    ///
+    /// // Compress the envelope
+    /// const compressed = envelope.compress();
+    ///
+    /// // Check that the compressed version has the same digest
+    /// console.log(envelope.digest().equals(compressed.digest())); // true
+    ///
+    /// // Verify that the compressed version takes less space
+    /// console.log(compressed.cborBytes().length < envelope.cborBytes().length);
+    /// ```
+    compress(): Envelope;
+
+    /// Returns the decompressed variant of this envelope.
+    ///
+    /// This method reverses the compression process, restoring the envelope to
+    /// its original decompressed form. The decompressed envelope will have
+    /// the same digest as the compressed version.
+    ///
+    /// @returns The decompressed envelope
+    /// @throws {EnvelopeError} If the envelope is not compressed, missing digest, or has invalid digest
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create and compress an envelope
+    /// const original = Envelope.new("Hello, world!");
+    /// const compressed = original.compress();
+    ///
+    /// // Decompress it
+    /// const decompressed = compressed.decompress();
+    ///
+    /// // The decompressed envelope should match the original
+    /// console.log(decompressed.asText() === "Hello, world!"); // true
+    /// console.log(decompressed.digest().equals(original.digest())); // true
+    /// ```
+    decompress(): Envelope;
+
+    /// Returns this envelope with its subject compressed.
+    ///
+    /// Unlike `compress()` which compresses the entire envelope, this method
+    /// only compresses the subject of the envelope, leaving the assertions
+    /// decompressed. This is useful when you want to compress a large
+    /// subject while keeping the assertions readable and accessible.
+    ///
+    /// @returns A new envelope with a compressed subject
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with a large subject and some assertions
+    /// const lorem = "Lorem ipsum dolor sit amet...";
+    /// const envelope = Envelope.new(lorem)
+    ///   .addAssertion("note", "This is a metadata note");
+    ///
+    /// // Compress just the subject
+    /// const subjectCompressed = envelope.compressSubject();
+    ///
+    /// // The envelope's digest is preserved
+    /// console.log(envelope.digest().equals(subjectCompressed.digest())); // true
+    ///
+    /// // The subject is now compressed
+    /// console.log(subjectCompressed.subject().isCompressed()); // true
+    /// ```
+    compressSubject(): Envelope;
+
+    /// Returns this envelope with its subject decompressed.
+    ///
+    /// This method reverses the effect of `compressSubject()`, decompressing
+    /// the subject of the envelope while leaving the rest of the envelope
+    /// unchanged.
+    ///
+    /// @returns A new envelope with a decompressed subject
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope and compress its subject
+    /// const original = Envelope.new("Hello, world!")
+    ///   .addAssertion("note", "Test note");
+    /// const compressed = original.compressSubject();
+    ///
+    /// // Verify the subject is compressed
+    /// console.log(compressed.subject().isCompressed()); // true
+    ///
+    /// // Decompress the subject
+    /// const decompressed = compressed.decompressSubject();
+    ///
+    /// // Verify the subject is now decompressed
+    /// console.log(!decompressed.subject().isCompressed()); // true
+    /// ```
+    decompressSubject(): Envelope;
+
+    /// Checks if this envelope is compressed
+    isCompressed(): boolean;
+  }
+}
+
+/// 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();