Returns a reference to the underlying envelope case.
The EnvelopeCase enum represents the specific structural variant of
this envelope. This method provides access to that underlying
variant for operations that need to differentiate between the
different envelope types.
The EnvelopeCase that defines this envelope's structure.
StaticNULLStaticcodecTagged-CBOR codec; decode requires tag 200 (fromCbor), like every codec in the stack.
StaticFALSEThe false leaf.
StaticTRUEThe true leaf.
StaticUNITUnit envelopes have the known value ''. They represent a position
where no meaningful data can exist. In this sense they make a
semantically stronger assertion than null, which represents a
position where no meaningful data currently exists, but could exist in
the future.
Method form of confirmContainsSet from @blockchaincommons/envelope/proof.
Method form of proofContainsSet from @blockchaincommons/envelope/proof.
Method form of addAttachment from @blockchaincommons/envelope/attachment.
Method form of attachmentConformsTo from @blockchaincommons/envelope/attachment.
Method form of attachmentPayload from @blockchaincommons/envelope/attachment.
Method form of attachmentVendor from @blockchaincommons/envelope/attachment.
Method form of expectAttachment from @blockchaincommons/envelope/attachment.
Method form of attachments from @blockchaincommons/envelope/attachment.
Method form of validateAttachment from @blockchaincommons/envelope/attachment.
Method form of edgeIsA from @blockchaincommons/envelope/edge.
Method form of edgeSource from @blockchaincommons/envelope/edge.
Method form of edgeSubject from @blockchaincommons/envelope/edge.
Method form of edgeTarget from @blockchaincommons/envelope/edge.
Method form of edges from @blockchaincommons/envelope/edge.
Method form of edgesMatching from @blockchaincommons/envelope/edge.
Method form of validateEdge from @blockchaincommons/envelope/edge.
Method form of addRecipient from @blockchaincommons/envelope/recipient.
Method form of decryptSubjectToRecipient from @blockchaincommons/envelope/recipient.
Method form of decryptToRecipient from @blockchaincommons/envelope/recipient.
Method form of encryptSubjectToRecipient from @blockchaincommons/envelope/recipient.
Method form of encryptSubjectToRecipients from @blockchaincommons/envelope/recipient.
Method form of encryptToRecipients from @blockchaincommons/envelope/recipient.
Method form of recipients from @blockchaincommons/envelope/recipient.
Method form of addSecret from @blockchaincommons/envelope/secret.
Method form of isLockedWithPassword from @blockchaincommons/envelope/secret.
Method form of isLockedWithSshAgent from @blockchaincommons/envelope/secret.
Method form of lock from @blockchaincommons/envelope/secret.
Method form of lockSubject from @blockchaincommons/envelope/secret.
Method form of lockSubjectWith from @blockchaincommons/envelope/secret.
Method form of lockWith from @blockchaincommons/envelope/secret.
Method form of unlock from @blockchaincommons/envelope/secret.
Method form of unlockSubject from @blockchaincommons/envelope/secret.
Method form of unlockSubjectWith from @blockchaincommons/envelope/secret.
Method form of unlockWith from @blockchaincommons/envelope/secret.
Method form of addSignature from @blockchaincommons/envelope/signature.
Method form of addSignatures from @blockchaincommons/envelope/signature.
Method form of hasSignatureFrom from @blockchaincommons/envelope/signature.
Method form of hasSignatureFromReturningMetadata from @blockchaincommons/envelope/signature.
Method form of hasSignaturesFrom from @blockchaincommons/envelope/signature.
Method form of hasSignaturesFromThreshold from @blockchaincommons/envelope/signature.
Method form of isVerifiedSignature from @blockchaincommons/envelope/signature.
Method form of makeSignedAssertion from @blockchaincommons/envelope/signature.
Method form of sign from @blockchaincommons/envelope/signature.
Method form of signatures from @blockchaincommons/envelope/signature.
Method form of verify from @blockchaincommons/envelope/signature.
Method form of verifySignature from @blockchaincommons/envelope/signature.
Method form of verifySignatureFrom from @blockchaincommons/envelope/signature.
Method form of verifySignatureFromReturningMetadata from @blockchaincommons/envelope/signature.
Method form of verifySignaturesFrom from @blockchaincommons/envelope/signature.
Method form of verifySignaturesFromThreshold from @blockchaincommons/envelope/signature.
Method form of sskrSplit from @blockchaincommons/envelope/sskr.
Method form of addType from @blockchaincommons/envelope/types.
Method form of expectType from @blockchaincommons/envelope/types.
Method form of expectTypeValue from @blockchaincommons/envelope/types.
Method form of getType from @blockchaincommons/envelope/types.
Method form of hasType from @blockchaincommons/envelope/types.
Method form of hasTypeValue from @blockchaincommons/envelope/types.
Method form of types from @blockchaincommons/envelope/types.
Method form of diagnostic from @blockchaincommons/envelope/format.
Method form of hex from @blockchaincommons/envelope/format.
Method form of mermaidFormat from @blockchaincommons/envelope/format.
Method form of format from @blockchaincommons/envelope/format.
Method form of formatFlat from @blockchaincommons/envelope/format.
Method form of shortId from @blockchaincommons/envelope/format.
Method form of summary from @blockchaincommons/envelope/format.
Method form of treeFormat from @blockchaincommons/envelope/format.
Method form of encryptToRecipient from @blockchaincommons/envelope/seal.
Method form of seal from @blockchaincommons/envelope/seal.
Method form of unseal from @blockchaincommons/envelope/seal.
StaticfromCreates an envelope with a subject, which can be any value that can be encoded as an envelope.
The subject value
A new envelope containing the subject
StaticfromCreates an envelope with a subject, or undefined if the subject is
absent (undefined or JS null).
port ↔ reference note: the reference Envelope::new_or_none returns
Option<Envelope> — the None branch fires only on None. We
follow the same convention as Envelope.from(x ?? null) and treat
JS null and undefined interchangeably as the absent case.
The optional subject value (undefined or null
triggers the absent branch).
A new envelope or undefined
StaticfromCreates an envelope from an EnvelopeCase.
This is an internal method used by extensions to create envelopes from custom case types like compressed or encrypted.
The envelope case to wrap
A new envelope with the given case
StaticassertionCreates an assertion envelope with a predicate and object.
The predicate of the assertion
The object of the assertion
A new assertion envelope
StaticnodeStaticfromStaticknownCreates an envelope with a known value.
The known value (can be a KnownValue instance or a number/bigint)
A new known value envelope
StaticencryptedCreates an envelope with encrypted content.
Err(Error::MissingDigest) when the message has no AAD digest.
The encrypted message
A new encrypted envelope
StaticcompressedCreates an envelope with compressed content.
Err(Error::MissingDigest) when the compressed value has no digest.
The compressed data
A new compressed envelope
StaticelidedCreates an elided envelope containing only a digest.
The digest of the elided content
A new elided envelope
StaticleafCreates a leaf envelope containing a CBOR value.
The value to encode as CBOR
A new leaf envelope
StaticwrapCreates a wrapped envelope.
The envelope (or value) to wrap
A new wrapped envelope
Returns the digest of this envelope.
The envelope's digest
Returns the subject of this envelope.
For different envelope cases:
The subject envelope
Checks if the envelope's subject is an assertion.
true if the subject is an assertion, false otherwise
Checks if the envelope's subject is obscured (elided, encrypted, or compressed).
true if the subject is obscured, false otherwise
Returns the untagged CBOR representation of this envelope.
The untagged CBOR
Returns the tagged CBOR representation of this envelope.
All envelopes are tagged with TAG_ENVELOPE (200).
The tagged CBOR
The envelope tag (200).
As ur:envelope/….
StaticfromDecodes an envelope from its tagged CBOR (tag 200): the reference's
TryFrom<CBOR> / from_tagged_cbor.
StaticfromDecodes an envelope from tagged CBOR bytes: the reference's
try_from_cbor_data.
StaticfromDecodes an envelope from its untagged CBOR (the content of tag 200): the
reference's from_untagged_cbor. A tag-24 or tag-201 value is a leaf, a
tag-200 value a wrapped envelope, tag 40002 an encrypted message, tag
40003 a compressed value, a 32-byte string an elided envelope, an array
a node, a single-element map an assertion and an unsigned integer a
known value.
EnvelopeError with code Cbor whose message is the dcbor Display
the reference returns and whose cause is the CborError: the dcbor
error of a malformed component as it is, else Custom with the
reference's text (unknown envelope tag: <n>, invalid digest size: expected 32, got <n>, node must have at least two elements,
invalid format, assertion must be a map with exactly one element,
a digest was expected but not found, invalid envelope). A failure
inside an assertion's key or value nests as dcbor error: <message>.
Adds an assertion to this envelope.
The assertion predicate
The assertion object
A new envelope with the assertion added
Adds an assertion envelope to this envelope.
The assertion envelope
A new envelope with the assertion added
Creates a string representation of this envelope.
A string representation
Adds assertion when given (deduplicated by digest); this envelope otherwise.
Adds predicate: object when object is given; this envelope otherwise.
Adds a salt assertion of random bytes so that this envelope's digest
cannot be correlated with another envelope of the same content.
By default the salt length is proportional to the envelope's size
(5–25 %, at least 8 bytes; the reference's add_salt_using); give
length (add_salt_with_len_using), a range
(add_salt_in_range_using), or the exact salt (add_salt_instance)
instead. rng overrides the secure default. The salt itself comes from
components' Salt, whose checks the reference's Salt::new_* make.
Adds predicate: text when text is not empty; this envelope otherwise.
Adds predicate: object when condition holds; this envelope otherwise.
The assertions of a node (a frozen array); empty for every other case.
true when the subject is the boolean false (the reference's is_false: subject extraction, so a node whose subject is false qualifies).
true when the subject is the boolean true (the reference's is_true).
true when the subject is a boolean (the reference's is_bool).
true when the envelope is a number leaf.
true when the envelope is a node whose subject is a number.
true when the envelope is the NaN leaf.
true when the envelope is a node whose subject is NaN.
true when the subject is null (the reference's is_null: subject extraction).
A copy of the subject's bytes, or undefined when it is not a byte-string leaf.
A copy of the subject's array, or undefined when it is not an array leaf.
A copy of the subject's map, or undefined when it is not a map leaf.
The subject's text, or undefined when it is not a text leaf.
The subject's CBOR, or undefined when it is not a leaf.
The known value, or undefined when the subject is not one.
true when the envelope is a known value.
true when the envelope is a node whose subject is the unit known value.
Throws SubjectNotUnit unless the subject is the unit known value.
true when the envelope is a node with at least one assertion.
The assertion, or undefined when this envelope is not one.
The assertion, or undefined when this envelope is not one.
The predicate, or undefined when this envelope is not an assertion.
The predicate, or undefined when this envelope is not an assertion.
The object, or undefined when this envelope is not an assertion.
The object, or undefined when this envelope is not an assertion.
true when the envelope is an assertion.
true when the envelope is elided.
true when the envelope is a leaf.
true when the envelope is a node (a subject with assertions).
true when the envelope is a wrapped envelope.
true when the envelope is internal (a node, a wrapped envelope or an assertion, never a leaf or known value).
true when the envelope is obscured (elided, encrypted or compressed).
The single assertion with predicate; NonexistentPredicate / AmbiguousPredicate otherwise.
The single assertion with predicate, or undefined; AmbiguousPredicate when there are several.
The object of the single assertion with predicate; NonexistentPredicate / AmbiguousPredicate otherwise.
The object of the single assertion with predicate, or undefined; AmbiguousPredicate when there are several.
The objects of every assertion with predicate.
The number of elements in the tree (the subject, the assertions and their parts).
true when the envelope is encrypted or a node whose subject is (recursively).
true when the envelope is compressed or a node whose subject is (recursively).
true when the envelope is elided or a node whose subject is (recursively).
Adds a 'position' assertion with the given ordinal (the reference's
set_position(usize)): a non-negative safe integer number, or a
bigint in 0 ..= 2⁶⁴ − 1 for the exact form.
The value of the 'position' assertion (the reference's position(),
extract_subject::<usize>()): a number when at most 2⁵³ − 1, a
bigint otherwise. A negative integer wraps to 2⁶⁴ + n, as the
reference's usize::try_from(CBOR) wraps it.
A copy without the 'position' assertion.
Wraps this envelope as the subject of a new one, so assertions can be attached to it as a whole.
The wrapped envelope, or undefined when this envelope is not a wrapper.
Returns the set of digests in the envelope, down to the specified level.
the reference uses HashSet<Digest> which dedupes by content; native JS Set
dedupes by reference, so we route inserts through a hex-keyed Map
before materialising the final Set. That keeps the public signature
(Set<Digest>) while guaranteeing each value appears at most once,
which is what every consumer of these methods actually wants.
Returns all digests in the envelope at all levels.
Returns the digests in the envelope down to its second level.
structure mode, building an image:
0 for Encrypted,
1 for Elided, 2 for Compressed (matching the the reference order).The full image is then SHA-256-hashed via Digest.fromImage.
Unlike Envelope.digest (which captures semantic identity),
structuralDigest captures the envelope's structural form too, including
where elision / encryption / compression has been applied. Two
envelopes whose digest()s match are semantically equivalent; their
structuralDigest()s match only if the structures themselves are
identical.
The object, or undefined when this envelope is not an assertion (alias of tryObject).
The predicate, or undefined when this envelope is not an assertion (alias of tryPredicate).
Elide this envelope, or with options elide (or encrypt or compress)
parts of it: removing obscures the elements whose digests are listed,
revealing obscures everything but the listed elements and their
ancestors. action defaults to "elide".
Optionaloptions: ElideOptionsSet<Digest> for backward compatibility with callers, but the
underlying dedup is by hex content (via a hex-keyed Map) so two
Digest instances that represent the same hash bytes count once,
matching the reference's HashSet<Digest> semantics.
Two envelopes are equivalent if they have the same digest (semantic equivalence).
This is a weaker comparison than isIdenticalTo which also checks the case type.
short-circuit on a semantic mismatch (different digest()), then fall
through to a Envelope.structuralDigest comparison. Two envelopes
whose digests match but whose structures differ — e.g. an envelope and a
version of it with one assertion elided — are not identical.
Recursively walks the envelope and decrypts every encrypted node it
can. For an Encrypted node, each provided key is tried in order; the
first one that successfully decrypts wins, and the recursion continues
into the result so chains of nested encryption peel off one layer per
matching key. Nodes whose decryption fails for every key are returned
unchanged — matching the reference's if let Ok(decrypted) = ... pattern.
Structural sharing: if a recursion produces an envelope that is Envelope.isIdenticalTo the original, the original instance is reused instead of allocating a new node.
Recursively walks the envelope and decompresses any compressed node
whose digest is in targetDigests (or every compressed node if
targetDigests is undefined). Decompression failures are tolerated —
the original node is returned in that case, mirroring the reference's
if let Ok(decompressed) = ... pattern.
OptionaltargetDigests: Set<Digest>The leaf's number as dcbor's expectFloat reads it: the reference's
f64::try_from(envelope). An integer the f64 cannot represent exactly
is rejected (OutOfRange), as the reference rejects it.
extractSubject as a method: the reference's extract_subject::<T>().
Add tryObjectForPredicate method to Envelope prototype
Add tryOptionalObjectForPredicate method to Envelope prototype
extractObjectForPredicateWithDefault as a method.
extractObjectsForPredicate as a method.
A copy with the subject encrypted by key (ChaCha20-Poly1305 over the
subject's CBOR, the digest as AAD): the reference's encrypt_subject.
A copy with the subject decrypted by key (the reference's
decrypt_subject).
Wraps this envelope and encrypts the wrapper's subject, so the whole envelope is hidden.
Decrypts a subject encrypted with encrypt and unwraps it.
true when the envelope is encrypted.
A copy compressed (deflate over its CBOR): the reference's compress;
this envelope when already compressed.
A copy decompressed (the reference's decompress).
A copy with the subject compressed; AlreadyEncrypted / AlreadyElided when it cannot be.
A copy with the subject decompressed; NotCompressed when it is not.
true when the envelope is compressed.
A flexible container for structured data with built-in integrity verification.
Gordian Envelope is the primary data structure of this library. It provides a way to encapsulate and organize data with cryptographic integrity, privacy features, and selective disclosure capabilities.
Key characteristics of envelopes:
Immutability: Envelopes are immutable. Operations that appear to "modify" an envelope actually create a new envelope. This immutability is fundamental to maintaining the integrity of the envelope's digest tree.
Efficient Cloning: Envelopes use shallow copying for efficient O(1) cloning. Since they're immutable, clones share the same underlying data.
Semantic Structure: Envelopes can represent various semantic relationships through subjects, predicates, and objects (similar to RDF triples).
Digest Tree: Each envelope maintains a Merkle-like digest tree that ensures the integrity of its contents and enables verification of individual parts.
Privacy Features: Envelopes support selective disclosure through elision, encryption, and compression of specific parts, while maintaining the overall integrity of the structure.
Deterministic Representation: Envelopes use deterministic CBOR encoding to ensure consistent serialization across platforms.
The Gordian Envelope specification is defined in an IETF Internet Draft, and this implementation closely follows that specification.
Example