@bcts/envelope 1.0.0-alpha.8 → 1.0.0-alpha.9

package/src/base/leaf.ts

@@ -1,4 +1,4 @@
-import type { Cbor, CborMap } from "@bcts/dcbor";
+import type { Cbor } from "@bcts/dcbor";
 import { isNumber, isNaN, asArray, asMap, asText } from "@bcts/dcbor";
 import { Envelope } from "./envelope";
 
@@ -8,85 +8,6 @@ import { Envelope } from "./envelope";
 /// This module extends the Envelope class with convenience methods for
 /// working with leaf values, including type checking and extraction.
 
-declare module "./envelope" {
-  interface Envelope {
-    /// Checks if this envelope contains false.
-    ///
-    /// @returns `true` if the envelope's subject is false, `false` otherwise
-    isFalse(): boolean;
-
-    /// Checks if this envelope contains true.
-    ///
-    /// @returns `true` if the envelope's subject is true, `false` otherwise
-    isTrue(): boolean;
-
-    /// Checks if this envelope contains a boolean value.
-    ///
-    /// @returns `true` if the envelope's subject is a boolean, `false`
-    ///   otherwise
-    isBool(): boolean;
-
-    /// Checks if this envelope is a leaf node that contains a number.
-    ///
-    /// @returns `true` if the envelope is a leaf containing a number, `false`
-    ///   otherwise
-    isNumber(): boolean;
-
-    /// Checks if the subject of this envelope is a number.
-    ///
-    /// @returns `true` if the subject is a number, `false` otherwise
-    isSubjectNumber(): boolean;
-
-    /// Checks if this envelope is a leaf node that contains NaN.
-    ///
-    /// @returns `true` if the envelope is a leaf containing NaN, `false`
-    ///   otherwise
-    isNaN(): boolean;
-
-    /// Checks if the subject of this envelope is NaN.
-    ///
-    /// @returns `true` if the subject is NaN, `false` otherwise
-    isSubjectNaN(): boolean;
-
-    /// Checks if this envelope contains null.
-    ///
-    /// @returns `true` if the envelope's subject is null, `false` otherwise
-    isNull(): boolean;
-
-    /// Attempts to extract the leaf CBOR as a byte string.
-    ///
-    /// @returns The byte string value
-    /// @throws {EnvelopeError} If the envelope is not a leaf or not a byte
-    ///   string
-    tryByteString(): Uint8Array;
-
-    /// Returns the leaf CBOR as a byte string if possible.
-    ///
-    /// @returns The byte string value or undefined
-    asByteString(): Uint8Array | undefined;
-
-    /// Returns the leaf CBOR as an array if possible.
-    ///
-    /// @returns The array value or undefined
-    asArray(): readonly Cbor[] | undefined;
-
-    /// Returns the leaf CBOR as a map if possible.
-    ///
-    /// @returns The map value or undefined
-    asMap(): CborMap | undefined;
-
-    /// Returns the leaf CBOR as text if possible.
-    ///
-    /// @returns The text value or undefined
-    asText(): string | undefined;
-
-    /// Returns the leaf CBOR value if this envelope is a leaf.
-    ///
-    /// @returns The CBOR value or undefined
-    asLeaf(): Cbor | undefined;
-  }
-}
-
 // Note: Static methods Envelope.false() and Envelope.true() are implemented below
 // but cannot be declared in TypeScript module augmentation due to reserved keywords.
 

package/src/base/queries.ts

@@ -19,136 +19,6 @@ import { EnvelopeError } from "./error";
 /// These methods enable traversal and inspection of envelope hierarchies,
 /// allowing for flexible manipulation and access to envelope data structures.
 
-declare module "./envelope" {
-  interface Envelope {
-    /// Returns true if the envelope has at least one assertion.
-    ///
-    /// @returns `true` if there are assertions, `false` otherwise
-    hasAssertions(): boolean;
-
-    /// Returns the envelope as an assertion if it is one.
-    ///
-    /// @returns The assertion envelope or undefined
-    asAssertion(): Envelope | undefined;
-
-    /// Returns the envelope as an assertion or throws an error.
-    ///
-    /// @returns The assertion envelope
-    /// @throws {EnvelopeError} If the envelope is not an assertion
-    tryAssertion(): Envelope;
-
-    /// Returns the predicate of this assertion envelope.
-    ///
-    /// @returns The predicate envelope or undefined
-    asPredicate(): Envelope | undefined;
-
-    /// Returns the predicate of this assertion envelope or throws an error.
-    ///
-    /// @returns The predicate envelope
-    /// @throws {EnvelopeError} If the envelope is not an assertion
-    tryPredicate(): Envelope;
-
-    /// Returns the object of this assertion envelope.
-    ///
-    /// @returns The object envelope or undefined
-    asObject(): Envelope | undefined;
-
-    /// Returns the object of this assertion envelope or throws an error.
-    ///
-    /// @returns The object envelope
-    /// @throws {EnvelopeError} If the envelope is not an assertion
-    tryObject(): Envelope;
-
-    /// Checks if this envelope is case Assertion.
-    ///
-    /// @returns `true` if this is an assertion envelope
-    isAssertion(): boolean;
-
-    /// Checks if this envelope is case Elided.
-    ///
-    /// @returns `true` if this is an elided envelope
-    isElided(): boolean;
-
-    /// Checks if this envelope is case Leaf.
-    ///
-    /// @returns `true` if this is a leaf envelope
-    isLeaf(): boolean;
-
-    /// Checks if this envelope is case Node.
-    ///
-    /// @returns `true` if this is a node envelope
-    isNode(): boolean;
-
-    /// Checks if this envelope is case Wrapped.
-    ///
-    /// @returns `true` if this is a wrapped envelope
-    isWrapped(): boolean;
-
-    /// Checks if this envelope is internal (has child elements).
-    ///
-    /// Internal elements include node, wrapped, and assertion.
-    ///
-    /// @returns `true` if this envelope has children
-    isInternal(): boolean;
-
-    /// Checks if this envelope is obscured (elided, encrypted, or compressed).
-    ///
-    /// @returns `true` if this envelope is obscured
-    isObscured(): boolean;
-
-    /// Returns all assertions with the given predicate.
-    ///
-    /// Match is performed by comparing digests.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns An array of matching assertion envelopes
-    assertionsWithPredicate(predicate: EnvelopeEncodableValue): Envelope[];
-
-    /// Returns the assertion with the given predicate.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns The matching assertion envelope
-    /// @throws {EnvelopeError} If no assertion or multiple assertions match
-    assertionWithPredicate(predicate: EnvelopeEncodableValue): Envelope;
-
-    /// Returns the assertion with the given predicate, or undefined if not
-    /// found.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns The matching assertion envelope or undefined
-    /// @throws {EnvelopeError} If multiple assertions match
-    optionalAssertionWithPredicate(predicate: EnvelopeEncodableValue): Envelope | undefined;
-
-    /// Returns the object of the assertion with the given predicate.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns The object envelope
-    /// @throws {EnvelopeError} If no assertion or multiple assertions match
-    objectForPredicate(predicate: EnvelopeEncodableValue): Envelope;
-
-    /// Returns the object of the assertion with the given predicate, or
-    /// undefined if not found.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns The object envelope or undefined
-    /// @throws {EnvelopeError} If multiple assertions match
-    optionalObjectForPredicate(predicate: EnvelopeEncodableValue): Envelope | undefined;
-
-    /// Returns the objects of all assertions with the matching predicate.
-    ///
-    /// @param predicate - The predicate to search for
-    /// @returns An array of object envelopes
-    objectsForPredicate(predicate: EnvelopeEncodableValue): Envelope[];
-
-    /// Returns the number of structural elements in the envelope.
-    ///
-    /// This includes the envelope itself and all nested elements.
-    ///
-    /// @returns The total element count
-    elementsCount(): number;
-  }
-}
-
 /// Implementation of hasAssertions()
 Envelope.prototype.hasAssertions = function (this: Envelope): boolean {
   const c = this.case();

package/src/base/walk.ts

@@ -79,32 +79,6 @@ export type Visitor<State> = (
   state: State,
 ) => [State, boolean];
 
-declare module "./envelope" {
-  interface Envelope {
-    /// Walks the envelope structure, calling the visitor function for each
-    /// element.
-    ///
-    /// This function traverses the entire envelope hierarchy and calls the
-    /// visitor function on each element. The traversal can be performed in
-    /// two modes:
-    ///
-    /// - Structure-based traversal (`hideNodes = false`): Visits every element
-    ///   including node containers
-    /// - Tree-based traversal (`hideNodes = true`): Skips node elements and
-    ///   focuses on semantic content
-    ///
-    /// The visitor function can optionally return a context value that is
-    /// passed to child elements, enabling state to be accumulated or passed
-    /// down during traversal.
-    ///
-    /// @param hideNodes - If true, the visitor will not be called for node
-    ///   containers
-    /// @param state - Initial state passed to the visitor
-    /// @param visit - The visitor function called for each element
-    walk<State>(hideNodes: boolean, state: State, visit: Visitor<State>): void;
-  }
-}
-
 /// Implementation of walk()
 Envelope.prototype.walk = function <State>(
   this: Envelope,

package/src/base/wrap.ts

@@ -6,52 +6,6 @@ import { EnvelopeError } from "./error";
 /// Wrapping allows treating an envelope (including its assertions) as a single
 /// unit, making it possible to add assertions about the envelope as a whole.
 
-declare module "./envelope" {
-  interface Envelope {
-    /// Returns a new envelope which wraps the current envelope.
-    ///
-    /// Wrapping an envelope allows you to treat an envelope (including its
-    /// assertions) as a single unit, making it possible to add assertions
-    /// about the envelope as a whole.
-    ///
-    /// @returns A new wrapped envelope
-    ///
-    /// @example
-    /// ```typescript
-    /// // Create an envelope with an assertion
-    /// const envelope = Envelope.new("Hello.").addAssertion("language", "English");
-    ///
-    /// // Wrap it to add an assertion about the envelope as a whole
-    /// const wrapped = envelope.wrap().addAssertion("authenticated", true);
-    /// ```
-    wrap(): Envelope;
-
-    /// Unwraps and returns the inner envelope.
-    ///
-    /// This extracts the envelope contained within a wrapped envelope.
-    ///
-    /// @returns The unwrapped envelope
-    /// @throws {EnvelopeError} If this is not a wrapped envelope
-    ///
-    /// @example
-    /// ```typescript
-    /// // Create an envelope and wrap it
-    /// const envelope = Envelope.new("Hello.");
-    /// const wrapped = envelope.wrap();
-    ///
-    /// // Unwrap to get the original envelope
-    /// const unwrapped = wrapped.tryUnwrap();
-    /// ```
-    tryUnwrap(): Envelope;
-
-    /// Alias for tryUnwrap() - unwraps and returns the inner envelope.
-    ///
-    /// @returns The unwrapped envelope
-    /// @throws {EnvelopeError} If this is not a wrapped envelope
-    unwrap(): Envelope;
-  }
-}
-
 /// Implementation of wrap()
 Envelope.prototype.wrap = function (this: Envelope): Envelope {
   return Envelope.newWrapped(this);

package/src/extension/attachment.ts

@@ -128,95 +128,6 @@ export class 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
 
 /**

package/src/extension/compress.ts

@@ -69,123 +69,6 @@ export class Compressed {
   }
 }
 
-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.

package/src/extension/encrypt.ts

@@ -172,88 +172,6 @@ export class EncryptedMessage {
   }
 }
 
-declare module "../base/envelope" {
-  interface Envelope {
-    /// Returns a new envelope with its subject encrypted.
-    ///
-    /// Encrypts only the subject of the envelope, leaving assertions
-    /// unencrypted. To encrypt an entire envelope including its assertions,
-    /// it must first be wrapped using the `wrap()` method, or you
-    /// can use the `encrypt()` convenience method.
-    ///
-    /// The encryption uses IETF ChaCha20-Poly1305 and preserves the envelope's
-    /// digest, allowing for features like selective disclosure and
-    /// signature verification to work even on encrypted envelopes.
-    ///
-    /// @param key - The SymmetricKey to use for encryption
-    /// @returns A new envelope with its subject encrypted
-    /// @throws {EnvelopeError} If the envelope is already encrypted or elided
-    ///
-    /// @example
-    /// ```typescript
-    /// const envelope = Envelope.new("Secret data");
-    /// const key = SymmetricKey.generate();
-    /// const encrypted = envelope.encryptSubject(key);
-    /// console.log(encrypted.subject().isEncrypted()); // true
-    /// ```
-    encryptSubject(key: SymmetricKey): Envelope;
-
-    /// Returns a new envelope with its subject decrypted.
-    ///
-    /// Decrypts the subject of an envelope that was previously encrypted using
-    /// `encryptSubject()`. The symmetric key used must be the same one
-    /// used for encryption.
-    ///
-    /// @param key - The SymmetricKey to use for decryption
-    /// @returns A new envelope with its subject decrypted
-    /// @throws {EnvelopeError} If the envelope's subject is not encrypted, key is incorrect, or digest mismatch
-    ///
-    /// @example
-    /// ```typescript
-    /// const decrypted = encrypted.decryptSubject(key);
-    /// console.log(decrypted.asText()); // "Secret data"
-    /// ```
-    decryptSubject(key: SymmetricKey): Envelope;
-
-    /// Convenience method to encrypt an entire envelope including its assertions.
-    ///
-    /// This method wraps the envelope and then encrypts its subject, which has
-    /// the effect of encrypting the entire original envelope including all
-    /// its assertions.
-    ///
-    /// @param key - The SymmetricKey to use for encryption
-    /// @returns A new envelope with the entire original envelope encrypted
-    ///
-    /// @example
-    /// ```typescript
-    /// const envelope = Envelope.new("Alice").addAssertion("knows", "Bob");
-    /// const key = SymmetricKey.generate();
-    /// const encrypted = envelope.encrypt(key);
-    /// ```
-    encrypt(key: SymmetricKey): Envelope;
-
-    /// Convenience method to decrypt an entire envelope that was encrypted
-    /// using the `encrypt()` method.
-    ///
-    /// This method decrypts the subject and then unwraps the resulting
-    /// envelope, returning the original envelope with all its assertions.
-    ///
-    /// @param key - The SymmetricKey to use for decryption
-    /// @returns The original decrypted envelope
-    /// @throws {EnvelopeError} If envelope is not encrypted, key is incorrect, digest mismatch, or cannot unwrap
-    ///
-    /// @example
-    /// ```typescript
-    /// const decrypted = encrypted.decrypt(key);
-    /// console.log(envelope.digest().equals(decrypted.digest())); // true
-    /// ```
-    decrypt(key: SymmetricKey): Envelope;
-
-    /// Checks if this envelope is encrypted
-    isEncrypted(): boolean;
-  }
-}
-
 /// Register encryption extension methods on Envelope prototype
 /// This function is exported and called during module initialization
 /// to ensure Envelope is fully defined before attaching methods.

package/src/extension/proof.ts

@@ -47,55 +47,6 @@ import { type Digest } from "../base/digest";
 /// }
 /// ```
 
-declare module "../base/envelope" {
-  interface Envelope {
-    /// Creates a proof that this envelope includes every element in the target set.
-    ///
-    /// An inclusion proof is a specially constructed envelope that:
-    /// - Has the same digest as the original envelope (or an elided version of it)
-    /// - Contains the minimal structure needed to prove the existence of target elements
-    /// - Keeps all other content elided to preserve privacy
-    ///
-    /// @param target - The set of digests representing elements that the proof must include
-    /// @returns A proof envelope if all targets can be proven to exist, undefined otherwise
-    proofContainsSet(target: Set<Digest>): Envelope | undefined;
-
-    /// Creates a proof that this envelope includes the single target element.
-    ///
-    /// This is a convenience method that wraps `proofContainsSet()` for the
-    /// common case of proving the existence of just one element.
-    ///
-    /// @param target - The element that the proof must demonstrate exists in this envelope
-    /// @returns A proof envelope if the target can be proven to exist, undefined otherwise
-    proofContainsTarget(target: Envelope): Envelope | undefined;
-
-    /// Verifies whether this envelope contains all elements in the target set
-    /// using the given inclusion proof.
-    ///
-    /// This method is used by a verifier to check if a proof demonstrates the
-    /// existence of all target elements within this envelope. The verification
-    /// succeeds only if:
-    /// 1. The proof's digest matches this envelope's digest
-    /// 2. The proof contains all the target elements
-    ///
-    /// @param target - The set of digests representing elements that need to be proven to exist
-    /// @param proof - The inclusion proof envelope to verify
-    /// @returns true if all target elements are proven to exist in this envelope by the proof
-    confirmContainsSet(target: Set<Digest>, proof: Envelope): boolean;
-
-    /// Verifies whether this envelope contains the single target element using
-    /// the given inclusion proof.
-    ///
-    /// This is a convenience method that wraps `confirmContainsSet()` for the
-    /// common case of verifying just one element.
-    ///
-    /// @param target - The element that needs to be proven to exist in this envelope
-    /// @param proof - The inclusion proof envelope to verify
-    /// @returns true if the target element is proven to exist in this envelope by the proof
-    confirmContainsTarget(target: Envelope, proof: Envelope): boolean;
-  }
-}
-
 /// Implementation of proof methods on Envelope prototype
 // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
 if (Envelope?.prototype) {