@bcts/envelope 1.0.0-alpha.10

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@bcts/envelope",
+  "version": "1.0.0-alpha.10",
+  "type": "module",
+  "description": "Gordian Envelope for TypeScript",
+  "license": "BSD-2-Clause-Patent",
+  "author": "Leonardo Custodio <leonardo@custodio.me>",
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leonardocustodio/bcts",
+    "directory": "packages/envelope"
+  },
+  "bugs": {
+    "url": "https://github.com/leonardocustodio/bcts/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "browser": "dist/index.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "envelope",
+    "cbor",
+    "dcbor",
+    "gordian",
+    "blockchain-commons",
+    "privacy",
+    "encryption",
+    "deterministic",
+    "encoding",
+    "serialization"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "^0.1.0",
+    "@bcts/tsconfig": "^0.1.0",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.3",
+    "@types/pako": "^2.0.3",
+    "eslint": "^9.39.2",
+    "prettier": "^3.2.5",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.18.3",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@bcts/components": "^1.0.0-alpha.10",
+    "@bcts/crypto": "^1.0.0-alpha.10",
+    "@bcts/dcbor": "^1.0.0-alpha.10",
+    "@bcts/known-values": "^1.0.0-alpha.10",
+    "@bcts/rand": "^1.0.0-alpha.10",
+    "@bcts/uniform-resources": "^1.0.0-alpha.10",
+    "pako": "^2.1.0"
+  }
+}

package/src/base/assertion.ts

@@ -0,0 +1,179 @@
+import { Digest, type DigestProvider } from "./digest";
+import { Envelope } from "./envelope";
+import { type EnvelopeEncodable } from "./envelope-encodable";
+import { EnvelopeError } from "./error";
+import type { Cbor } from "@bcts/dcbor";
+import { CborMap } from "@bcts/dcbor";
+
+/// A predicate-object relationship representing an assertion about a subject.
+///
+/// In Gordian Envelope, assertions are the basic building blocks for attaching
+/// information to a subject. An assertion consists of a predicate (which states
+/// what is being asserted) and an object (which provides the assertion's
+/// value).
+///
+/// Assertions can be attached to envelope subjects to form semantic statements
+/// like: "subject hasAttribute value" or "document signedBy signature".
+///
+/// Assertions are equivalent to RDF (Resource Description Framework) triples,
+/// where:
+/// - The envelope's subject is the subject of the triple
+/// - The assertion's predicate is the predicate of the triple
+/// - The assertion's object is the object of the triple
+///
+/// Generally you do not create an instance of this type directly, but
+/// instead use `Envelope.newAssertion()`, or the various functions
+/// on `Envelope` that create assertions.
+export class Assertion implements DigestProvider {
+  readonly #predicate: Envelope;
+  readonly #object: Envelope;
+  readonly #digest: Digest;
+
+  /// Creates a new assertion and calculates its digest.
+  ///
+  /// This constructor takes a predicate and object, both of which are
+  /// converted to envelopes using the `EnvelopeEncodable` trait. It then
+  /// calculates the assertion's digest by combining the digests of the
+  /// predicate and object.
+  ///
+  /// The digest is calculated according to the Gordian Envelope
+  /// specification, which ensures that semantically equivalent assertions
+  /// always produce the same digest.
+  ///
+  /// @param predicate - The predicate of the assertion, which states what is
+  ///   being asserted
+  /// @param object - The object of the assertion, which provides the assertion's
+  ///   value
+  ///
+  /// @returns A new assertion with the specified predicate, object, and calculated
+  /// digest.
+  ///
+  /// @example
+  /// ```typescript
+  /// // Direct method - create an assertion envelope
+  /// const assertionEnvelope = Envelope.newAssertion("name", "Alice");
+  ///
+  /// // Or create and add an assertion to a subject
+  /// const person = Envelope.new("person").addAssertion("name", "Alice");
+  /// ```
+  constructor(predicate: EnvelopeEncodable | Envelope, object: EnvelopeEncodable | Envelope) {
+    this.#predicate = predicate instanceof Envelope ? predicate : Envelope.new(predicate);
+    this.#object = object instanceof Envelope ? object : Envelope.new(object);
+    this.#digest = Digest.fromDigests([this.#predicate.digest(), this.#object.digest()]);
+  }
+
+  /// Returns the predicate of the assertion.
+  ///
+  /// The predicate states what is being asserted about the subject. It is
+  /// typically a string or known value, but can be any envelope.
+  ///
+  /// @returns A clone of the assertion's predicate envelope.
+  predicate(): Envelope {
+    return this.#predicate;
+  }
+
+  /// Returns the object of the assertion.
+  ///
+  /// The object provides the value or content of the assertion. It can be any
+  /// type that can be represented as an envelope.
+  ///
+  /// @returns A clone of the assertion's object envelope.
+  object(): Envelope {
+    return this.#object;
+  }
+
+  /// Returns the digest of this assertion.
+  ///
+  /// Implementation of the DigestProvider interface.
+  ///
+  /// @returns The assertion's digest
+  digest(): Digest {
+    return this.#digest;
+  }
+
+  /// Checks if two assertions are equal based on digest equality.
+  ///
+  /// Two assertions are considered equal if they have the same digest,
+  /// regardless of how they were constructed.
+  ///
+  /// @param other - The other assertion to compare with
+  /// @returns `true` if the assertions are equal, `false` otherwise
+  equals(other: Assertion): boolean {
+    return this.#digest.equals(other.#digest);
+  }
+
+  /// Converts this assertion to CBOR.
+  ///
+  /// The CBOR representation of an assertion is a map with a single key-value
+  /// pair, where the key is the predicate's CBOR and the value is the object's
+  /// CBOR.
+  ///
+  /// @returns A CBOR representation of this assertion
+  toCbor(): Cbor {
+    const map = new CborMap();
+    map.set(this.#predicate.untaggedCbor(), this.#object.untaggedCbor());
+    return map as unknown as Cbor;
+  }
+
+  /// Attempts to create an assertion from a CBOR value.
+  ///
+  /// The CBOR must be a map with exactly one entry, where the key represents
+  /// the predicate and the value represents the object.
+  ///
+  /// @param cbor - The CBOR value to convert
+  /// @returns A new Assertion instance
+  /// @throws {EnvelopeError} If the CBOR is not a valid assertion
+  static fromCbor(cbor: Cbor): Assertion {
+    // Check if cbor is a Map
+    if (!(cbor instanceof CborMap)) {
+      throw EnvelopeError.invalidAssertion();
+    }
+
+    return Assertion.fromCborMap(cbor);
+  }
+
+  /// Attempts to create an assertion from a CBOR map.
+  ///
+  /// The map must have exactly one entry, where the key represents the
+  /// predicate and the value represents the object. This is used in
+  /// the deserialization process.
+  ///
+  /// @param map - The CBOR map to convert
+  /// @returns A new Assertion instance
+  /// @throws {EnvelopeError} If the map doesn't have exactly one entry
+  static fromCborMap(map: CborMap): Assertion {
+    if (map.size !== 1) {
+      throw EnvelopeError.invalidAssertion();
+    }
+
+    const entries = Array.from(map.entries());
+    const firstEntry = entries[0];
+    if (firstEntry === undefined) {
+      throw EnvelopeError.invalidAssertion();
+    }
+    const [predicateCbor, objectCbor] = firstEntry;
+
+    const predicate = Envelope.fromUntaggedCbor(predicateCbor);
+
+    const object = Envelope.fromUntaggedCbor(objectCbor);
+
+    return new Assertion(predicate, object);
+  }
+
+  /// Creates a string representation of this assertion for debugging.
+  ///
+  /// @returns A string representation
+  toString(): string {
+    return `Assertion(${String(this.#predicate)}: ${String(this.#object)})`;
+  }
+
+  /// Creates a copy of this assertion.
+  ///
+  /// Since assertions are immutable and envelopes are cheap to clone,
+  /// this returns the same instance.
+  ///
+  /// @returns This assertion instance
+  clone(): Assertion {
+    return this;
+  }
+}

package/src/base/assertions.ts

@@ -0,0 +1,153 @@
+import { Envelope } from "./envelope";
+import type { EnvelopeEncodableValue } from "./envelope-encodable";
+import { EnvelopeError } from "./error";
+
+/// Support for adding assertions.
+///
+/// Assertions are predicate-object pairs that make statements about an
+/// envelope's subject. This implementation provides methods for adding various
+/// types of assertions to envelopes.
+///
+/// These methods extend the Envelope class to provide a rich API for
+/// working with assertions, matching the Rust bc-envelope implementation.
+
+/// Implementation of addAssertionEnvelopes
+Envelope.prototype.addAssertionEnvelopes = function (
+  this: Envelope,
+  assertions: Envelope[],
+): Envelope {
+  return assertions.reduce((result, assertion) => result.addAssertionEnvelope(assertion), this);
+};
+
+/// Implementation of addOptionalAssertionEnvelope
+Envelope.prototype.addOptionalAssertionEnvelope = function (
+  this: Envelope,
+  assertion: Envelope | undefined,
+): Envelope {
+  if (assertion === undefined) {
+    return this;
+  }
+
+  // Validate that the assertion is a valid assertion or obscured envelope
+  if (!assertion.isSubjectAssertion() && !assertion.isSubjectObscured()) {
+    throw EnvelopeError.invalidFormat();
+  }
+
+  const c = this.case();
+
+  // Check if this is already a node
+  if (c.type === "node") {
+    // Check for duplicate assertions
+    const isDuplicate = c.assertions.some((a) => a.digest().equals(assertion.digest()));
+    if (isDuplicate) {
+      return this;
+    }
+
+    // Add the new assertion
+    return Envelope.newWithUncheckedAssertions(c.subject, [...c.assertions, assertion]);
+  }
+
+  // Otherwise, create a new node with this envelope as subject
+  return Envelope.newWithUncheckedAssertions(this.subject(), [assertion]);
+};
+
+/// Implementation of addOptionalAssertion
+Envelope.prototype.addOptionalAssertion = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+  object: EnvelopeEncodableValue | undefined,
+): Envelope {
+  if (object === undefined || object === null) {
+    return this;
+  }
+  return this.addAssertion(predicate, object);
+};
+
+/// Implementation of addNonemptyStringAssertion
+Envelope.prototype.addNonemptyStringAssertion = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+  str: string,
+): Envelope {
+  if (str.length === 0) {
+    return this;
+  }
+  return this.addAssertion(predicate, str);
+};
+
+/// Implementation of addAssertions
+Envelope.prototype.addAssertions = function (this: Envelope, envelopes: Envelope[]): Envelope {
+  return envelopes.reduce((result, envelope) => result.addAssertionEnvelope(envelope), this);
+};
+
+/// Implementation of addAssertionIf
+Envelope.prototype.addAssertionIf = function (
+  this: Envelope,
+  condition: boolean,
+  predicate: EnvelopeEncodableValue,
+  object: EnvelopeEncodableValue,
+): Envelope {
+  if (condition) {
+    return this.addAssertion(predicate, object);
+  }
+  return this;
+};
+
+/// Implementation of addAssertionEnvelopeIf
+Envelope.prototype.addAssertionEnvelopeIf = function (
+  this: Envelope,
+  condition: boolean,
+  assertionEnvelope: Envelope,
+): Envelope {
+  if (condition) {
+    return this.addAssertionEnvelope(assertionEnvelope);
+  }
+  return this;
+};
+
+/// Implementation of removeAssertion
+Envelope.prototype.removeAssertion = function (this: Envelope, target: Envelope): Envelope {
+  const assertions = this.assertions();
+  const targetDigest = target.digest();
+
+  const index = assertions.findIndex((a) => a.digest().equals(targetDigest));
+
+  if (index === -1) {
+    // Assertion not found, return unchanged
+    return this;
+  }
+
+  // Remove the assertion
+  const newAssertions = [...assertions.slice(0, index), ...assertions.slice(index + 1)];
+
+  if (newAssertions.length === 0) {
+    // No assertions left, return just the subject
+    return this.subject();
+  }
+
+  // Return envelope with remaining assertions
+  return Envelope.newWithUncheckedAssertions(this.subject(), newAssertions);
+};
+
+/// Implementation of replaceAssertion
+Envelope.prototype.replaceAssertion = function (
+  this: Envelope,
+  assertion: Envelope,
+  newAssertion: Envelope,
+): Envelope {
+  return this.removeAssertion(assertion).addAssertionEnvelope(newAssertion);
+};
+
+/// Implementation of replaceSubject
+Envelope.prototype.replaceSubject = function (this: Envelope, subject: Envelope): Envelope {
+  return this.assertions().reduce((e, a) => e.addAssertionEnvelope(a), subject);
+};
+
+/// Implementation of assertions
+Envelope.prototype.assertions = function (this: Envelope): Envelope[] {
+  const c = this.case();
+  if (c.type === "node") {
+    return c.assertions;
+  }
+  return [];
+};

package/src/base/cbor.ts

@@ -0,0 +1,122 @@
+import type { Cbor } from "@bcts/dcbor";
+import {
+  type CborTagged,
+  type CborTaggedEncodable,
+  type CborTaggedDecodable,
+  tagsForValues,
+  cborData,
+  decodeCbor,
+} from "@bcts/dcbor";
+import { ENVELOPE } from "@bcts/components";
+import { Envelope } from "./envelope";
+
+const TAG_ENVELOPE = ENVELOPE.value;
+
+/// Support for CBOR encoding and decoding of `Envelope`.
+///
+/// All envelopes are tagged with the `envelope` tag (200). Within that tag,
+/// each of the envelope cases has a unique CBOR signature:
+///
+/// * `.node` contains a CBOR array, the first element of which is the subject,
+///   followed by one or more assertions.
+/// * `.leaf` is tagged #6.24 (TAG_ENCODED_CBOR) or #6.204 (TAG_LEAF), which
+///   are the IANA tag for embedded CBOR.
+/// * `.wrapped` is tagged with the `envelope` tag.
+/// * `.assertion` is a single-element map `{predicate: object}`.
+/// * `.knownValue` is an unsigned 64-bit integer.
+/// * `.encrypted` is tagged with the `crypto-msg` tag.
+/// * `.elided` is a byte string of length 32 (the digest).
+/// * `.compressed` is tagged with the `compressed` tag.
+///
+/// This module provides implementations of the CBOR encoding/decoding traits
+/// for the Envelope type, matching the Rust bc-envelope implementation.
+
+/// Implements CborTagged interface for Envelope.
+///
+/// Returns the tags that should be used for CBOR encoding.
+export class EnvelopeCBORTagged implements CborTagged {
+  cborTags(): ReturnType<typeof tagsForValues> {
+    return tagsForValues([TAG_ENVELOPE]);
+  }
+
+  static cborTags(): number[] {
+    return tagsForValues([TAG_ENVELOPE]).map((tag) => Number(tag.value));
+  }
+}
+
+/// Implements CborTaggedEncodable for Envelope.
+///
+/// Provides the untagged CBOR representation of an envelope.
+export class EnvelopeCBORTaggedEncodable implements CborTaggedEncodable {
+  constructor(private readonly envelope: Envelope) {}
+
+  cborTags(): ReturnType<typeof tagsForValues> {
+    return tagsForValues([TAG_ENVELOPE]);
+  }
+
+  untaggedCbor(): Cbor {
+    return this.envelope.untaggedCbor();
+  }
+
+  taggedCbor(): Cbor {
+    return this.envelope.taggedCbor();
+  }
+}
+
+/// Implements CborTaggedDecodable for Envelope.
+///
+/// Provides the ability to decode an envelope from untagged CBOR.
+export class EnvelopeCBORTaggedDecodable<T = Envelope> implements CborTaggedDecodable<T> {
+  cborTags(): ReturnType<typeof tagsForValues> {
+    return tagsForValues([TAG_ENVELOPE]);
+  }
+
+  static fromUntaggedCbor(cbor: Cbor): Envelope {
+    return Envelope.fromUntaggedCbor(cbor);
+  }
+
+  static fromTaggedCbor(cbor: Cbor): Envelope {
+    return Envelope.fromTaggedCbor(cbor);
+  }
+
+  fromUntaggedCbor(cbor: Cbor): T {
+    return Envelope.fromUntaggedCbor(cbor) as T;
+  }
+
+  fromTaggedCbor(cbor: Cbor): T {
+    return Envelope.fromTaggedCbor(cbor) as T;
+  }
+}
+
+/// Convenience function to convert an Envelope to CBOR.
+///
+/// @param envelope - The envelope to convert
+/// @returns The CBOR representation (tagged)
+export function envelopeToCbor(envelope: Envelope): Cbor {
+  return envelope.taggedCbor();
+}
+
+/// Convenience function to create an Envelope from CBOR.
+///
+/// @param cbor - The CBOR value (expected to be tagged with TAG_ENVELOPE)
+/// @returns A new Envelope
+export function envelopeFromCbor(cbor: Cbor): Envelope {
+  return Envelope.fromTaggedCbor(cbor);
+}
+
+/// Convenience function to encode an Envelope to CBOR bytes.
+///
+/// @param envelope - The envelope to encode
+/// @returns The CBOR bytes
+export function envelopeToBytes(envelope: Envelope): Uint8Array {
+  return cborData(envelope.taggedCbor());
+}
+
+/// Convenience function to decode an Envelope from CBOR bytes.
+///
+/// @param bytes - The CBOR bytes
+/// @returns A new Envelope
+export function envelopeFromBytes(bytes: Uint8Array): Envelope {
+  const cbor = decodeCbor(bytes);
+  return Envelope.fromTaggedCbor(cbor);
+}