@bcts/envelope 1.0.0-alpha.5

package/src/extension/salt.ts

@@ -0,0 +1,223 @@
+import { Envelope } from "../base/envelope";
+import { EnvelopeError } from "../base/error";
+import {
+  SecureRandomNumberGenerator,
+  rngRandomData,
+  rngNextInClosedRangeI32,
+  type RandomNumberGenerator,
+} from "@bcts/rand";
+
+/// Extension for adding salt to envelopes to prevent correlation.
+///
+/// This module provides functionality for decorrelating envelopes by adding
+/// random salt. Salt is added as an assertion with the predicate 'salt' and
+/// a random value. When an envelope is elided, this salt ensures that the
+/// digest of the elided envelope cannot be correlated with other elided
+/// envelopes containing the same information.
+///
+/// Decorrelation is an important privacy feature that prevents third parties
+/// from determining whether two elided envelopes originally contained the same
+/// information by comparing their digests.
+///
+/// Based on bc-envelope-rust/src/extension/salt.rs and bc-components-rust/src/salt.rs
+///
+/// @example
+/// ```typescript
+/// // Create a simple envelope
+/// const envelope = Envelope.new("Hello");
+///
+/// // Create a decorrelated version by adding salt
+/// const salted = envelope.addSalt();
+///
+/// // The salted envelope has a different digest than the original
+/// console.log(envelope.digest().equals(salted.digest())); // false
+/// ```
+
+/// The standard predicate for salt assertions
+export const SALT = "salt";
+
+/// Minimum salt size in bytes (64 bits)
+const MIN_SALT_SIZE = 8;
+
+/// Creates a new SecureRandomNumberGenerator instance
+function createSecureRng(): RandomNumberGenerator {
+  return new SecureRandomNumberGenerator();
+}
+
+/// Generates random bytes using the rand package
+function generateRandomBytes(length: number, rng?: RandomNumberGenerator): Uint8Array {
+  const actualRng = rng ?? createSecureRng();
+  return rngRandomData(actualRng, length);
+}
+
+/// Calculates salt size proportional to envelope size
+/// This matches the Rust implementation in bc-components-rust/src/salt.rs
+function calculateProportionalSaltSize(envelopeSize: number, rng?: RandomNumberGenerator): number {
+  const actualRng = rng ?? createSecureRng();
+  const count = envelopeSize;
+  const minSize = Math.max(8, Math.ceil(count * 0.05));
+  const maxSize = Math.max(minSize + 8, Math.ceil(count * 0.25));
+  return rngNextInClosedRangeI32(actualRng, minSize, maxSize);
+}
+
+declare module "../base/envelope" {
+  interface Envelope {
+    /// Adds a proportionally-sized salt assertion to decorrelate the envelope.
+    ///
+    /// This method adds random salt bytes as an assertion to the envelope. The
+    /// size of the salt is proportional to the size of the envelope being
+    /// salted:
+    /// - For small envelopes: 8-16 bytes
+    /// - For larger envelopes: 5-25% of the envelope's size
+    ///
+    /// Salt is added as an assertion with the predicate 'salt' and an object
+    /// containing random bytes. This changes the digest of the envelope while
+    /// preserving its semantic content, making it impossible to correlate with
+    /// other envelopes containing the same information.
+    ///
+    /// @returns A new envelope with the salt assertion added
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with personally identifiable information
+    /// const alice = Envelope.new("Alice")
+    ///   .addAssertion("email", "alice@example.com")
+    ///   .addAssertion("ssn", "123-45-6789");
+    ///
+    /// // Create a second envelope with the same information
+    /// const alice2 = Envelope.new("Alice")
+    ///   .addAssertion("email", "alice@example.com")
+    ///   .addAssertion("ssn", "123-45-6789");
+    ///
+    /// // The envelopes have the same digest
+    /// console.log(alice.digest().equals(alice2.digest())); // true
+    ///
+    /// // Add salt to both envelopes
+    /// const aliceSalted = alice.addSalt();
+    /// const alice2Salted = alice2.addSalt();
+    ///
+    /// // Now the envelopes have different digests, preventing correlation
+    /// console.log(aliceSalted.digest().equals(alice2Salted.digest())); // false
+    /// ```
+    addSalt(): Envelope;
+
+    /// Adds salt of a specific byte length to the envelope.
+    ///
+    /// This method adds salt of a specified number of bytes to decorrelate the
+    /// envelope. It requires that the byte count be at least 8 bytes (64 bits)
+    /// to ensure sufficient entropy for effective decorrelation.
+    ///
+    /// @param count - The exact number of salt bytes to add
+    /// @returns A new envelope with salt added
+    /// @throws {EnvelopeError} If the byte count is less than 8
+    ///
+    /// @example
+    /// ```typescript
+    /// const envelope = Envelope.new("Hello");
+    ///
+    /// // Add exactly 16 bytes of salt
+    /// const salted = envelope.addSaltWithLength(16);
+    ///
+    /// // Trying to add less than 8 bytes will throw an error
+    /// try {
+    ///   envelope.addSaltWithLength(7);
+    /// } catch (e) {
+    ///   console.log("Error: salt must be at least 8 bytes");
+    /// }
+    /// ```
+    addSaltWithLength(count: number): Envelope;
+
+    /// Adds the given salt bytes as an assertion to the envelope.
+    ///
+    /// This method attaches specific salt bytes as an assertion to the
+    /// envelope, using 'salt' as the predicate. This is useful when you need
+    /// to control the specific salt content being added.
+    ///
+    /// @param saltBytes - A Uint8Array containing salt bytes
+    /// @returns A new envelope with the salt assertion added
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create salt with specific bytes
+    /// const salt = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+    ///
+    /// // Add this specific salt to an envelope
+    /// const envelope = Envelope.new("Hello");
+    /// const salted = envelope.addSaltBytes(salt);
+    /// ```
+    addSaltBytes(saltBytes: Uint8Array): Envelope;
+
+    /// Adds salt with a byte length randomly chosen from the given range.
+    ///
+    /// This method adds salt with a length randomly selected from the specified
+    /// range to decorrelate the envelope. This provides additional
+    /// decorrelation by varying the size of the salt itself.
+    ///
+    /// @param min - Minimum number of salt bytes (must be at least 8)
+    /// @param max - Maximum number of salt bytes
+    /// @returns A new envelope with salt added
+    /// @throws {EnvelopeError} If min is less than 8 or max is less than min
+    ///
+    /// @example
+    /// ```typescript
+    /// const envelope = Envelope.new("Hello");
+    ///
+    /// // Add salt with a length randomly chosen between 16 and 32 bytes
+    /// const salted = envelope.addSaltInRange(16, 32);
+    /// ```
+    addSaltInRange(min: number, max: number): Envelope;
+  }
+}
+
+/// Implementation of addSalt()
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (Envelope?.prototype) {
+  Envelope.prototype.addSalt = function (this: Envelope): Envelope {
+    const rng = createSecureRng();
+    const envelopeSize = this.cborBytes().length;
+    const saltSize = calculateProportionalSaltSize(envelopeSize, rng);
+    const saltBytes = generateRandomBytes(saltSize, rng);
+    return this.addAssertion(SALT, saltBytes);
+  };
+
+  /// Implementation of addSaltWithLength()
+  Envelope.prototype.addSaltWithLength = function (this: Envelope, count: number): Envelope {
+    if (count < MIN_SALT_SIZE) {
+      throw EnvelopeError.general(`Salt must be at least ${MIN_SALT_SIZE} bytes, got ${count}`);
+    }
+    const saltBytes = generateRandomBytes(count);
+    return this.addAssertion(SALT, saltBytes);
+  };
+
+  /// Implementation of addSaltBytes()
+  Envelope.prototype.addSaltBytes = function (this: Envelope, saltBytes: Uint8Array): Envelope {
+    if (saltBytes.length < MIN_SALT_SIZE) {
+      throw EnvelopeError.general(
+        `Salt must be at least ${MIN_SALT_SIZE} bytes, got ${saltBytes.length}`,
+      );
+    }
+    return this.addAssertion(SALT, saltBytes);
+  };
+
+  /// Implementation of addSaltInRange()
+  Envelope.prototype.addSaltInRange = function (
+    this: Envelope,
+    min: number,
+    max: number,
+  ): Envelope {
+    if (min < MIN_SALT_SIZE) {
+      throw EnvelopeError.general(
+        `Minimum salt size must be at least ${MIN_SALT_SIZE} bytes, got ${min}`,
+      );
+    }
+    if (max < min) {
+      throw EnvelopeError.general(
+        `Maximum salt size must be at least minimum, got min=${min} max=${max}`,
+      );
+    }
+    const rng = createSecureRng();
+    const saltSize = rngNextInClosedRangeI32(rng, min, max);
+    const saltBytes = generateRandomBytes(saltSize, rng);
+    return this.addAssertion(SALT, saltBytes);
+  };
+}

package/src/extension/signature.ts

@@ -0,0 +1,463 @@
+/**
+ * Signature Extension for Gordian Envelope
+ *
+ * Provides functionality for digitally signing Envelopes and verifying signatures,
+ * with optional metadata support.
+ *
+ * The signature extension allows:
+ * - Signing envelope subjects to validate their authenticity
+ * - Adding metadata to signatures (e.g., signer identity, date, purpose)
+ * - Verification of signatures, both with and without metadata
+ * - Support for multiple signatures on a single envelope
+ */
+
+import { Envelope } from "../base/envelope";
+import { EnvelopeError } from "../base/error";
+import {
+  ecdsaSign,
+  ecdsaVerify,
+  ecdsaPublicKeyFromPrivateKey,
+  ECDSA_PRIVATE_KEY_SIZE,
+  ECDSA_PUBLIC_KEY_SIZE,
+  ECDSA_UNCOMPRESSED_PUBLIC_KEY_SIZE,
+} from "@bcts/crypto";
+import { SecureRandomNumberGenerator, rngRandomData } from "@bcts/rand";
+
+/**
+ * Known value for the 'signed' predicate.
+ * This is the standard predicate used for signature assertions.
+ */
+export const SIGNED = "signed";
+
+/**
+ * Known value for the 'verifiedBy' predicate.
+ * Used to indicate verification status.
+ */
+export const VERIFIED_BY = "verifiedBy";
+
+/**
+ * Known value for the 'note' predicate.
+ * Used for adding notes/comments to signatures.
+ */
+export const NOTE = "note";
+
+/**
+ * Represents a cryptographic signature.
+ */
+export class Signature {
+  readonly #data: Uint8Array;
+
+  constructor(data: Uint8Array) {
+    this.#data = data;
+  }
+
+  /**
+   * Returns the raw signature bytes.
+   */
+  data(): Uint8Array {
+    return this.#data;
+  }
+
+  /**
+   * Returns the hex-encoded signature.
+   */
+  hex(): string {
+    return Array.from(this.#data)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  /**
+   * Creates a Signature from hex string.
+   */
+  static fromHex(hex: string): Signature {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+      bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return new Signature(bytes);
+  }
+}
+
+/**
+ * Interface for types that can sign data.
+ */
+export interface Signer {
+  /**
+   * Signs the provided data and returns a Signature.
+   */
+  sign(data: Uint8Array): Signature;
+}
+
+/**
+ * Interface for types that can verify signatures.
+ */
+export interface Verifier {
+  /**
+   * Verifies a signature against the provided data.
+   * Returns true if the signature is valid.
+   */
+  verify(data: Uint8Array, signature: Signature): boolean;
+}
+
+/**
+ * ECDSA signing key using secp256k1 curve.
+ * Uses @bcts/crypto functions.
+ */
+export class SigningPrivateKey implements Signer {
+  readonly #privateKey: Uint8Array;
+
+  constructor(privateKey: Uint8Array) {
+    if (privateKey.length !== ECDSA_PRIVATE_KEY_SIZE) {
+      throw new Error(`Private key must be ${ECDSA_PRIVATE_KEY_SIZE} bytes`);
+    }
+    this.#privateKey = privateKey;
+  }
+
+  /**
+   * Generates a new random private key.
+   */
+  static generate(): SigningPrivateKey {
+    const rng = new SecureRandomNumberGenerator();
+    const privateKey = rngRandomData(rng, ECDSA_PRIVATE_KEY_SIZE);
+    return new SigningPrivateKey(privateKey);
+  }
+
+  /**
+   * Creates a private key from hex string.
+   */
+  static fromHex(hex: string): SigningPrivateKey {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+      bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return new SigningPrivateKey(bytes);
+  }
+
+  /**
+   * Returns the corresponding public key.
+   */
+  publicKey(): SigningPublicKey {
+    const publicKey = ecdsaPublicKeyFromPrivateKey(this.#privateKey);
+    return new SigningPublicKey(publicKey);
+  }
+
+  /**
+   * Signs data and returns a Signature.
+   */
+  sign(data: Uint8Array): Signature {
+    const signatureBytes = ecdsaSign(this.#privateKey, data);
+    return new Signature(signatureBytes);
+  }
+
+  /**
+   * Returns the raw private key bytes.
+   */
+  data(): Uint8Array {
+    return this.#privateKey;
+  }
+}
+
+/**
+ * ECDSA public key for signature verification using secp256k1 curve.
+ * Uses @bcts/crypto functions.
+ */
+export class SigningPublicKey implements Verifier {
+  readonly #publicKey: Uint8Array;
+
+  constructor(publicKey: Uint8Array) {
+    if (
+      publicKey.length !== ECDSA_PUBLIC_KEY_SIZE &&
+      publicKey.length !== ECDSA_UNCOMPRESSED_PUBLIC_KEY_SIZE
+    ) {
+      throw new Error(
+        `Public key must be ${ECDSA_PUBLIC_KEY_SIZE} bytes (compressed) or ${ECDSA_UNCOMPRESSED_PUBLIC_KEY_SIZE} bytes (uncompressed)`,
+      );
+    }
+    this.#publicKey = publicKey;
+  }
+
+  /**
+   * Creates a public key from hex string.
+   */
+  static fromHex(hex: string): SigningPublicKey {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+      bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return new SigningPublicKey(bytes);
+  }
+
+  /**
+   * Verifies a signature against the provided data.
+   */
+  verify(data: Uint8Array, signature: Signature): boolean {
+    try {
+      return ecdsaVerify(this.#publicKey, signature.data(), data);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns the raw public key bytes.
+   */
+  data(): Uint8Array {
+    return this.#publicKey;
+  }
+
+  /**
+   * Returns the hex-encoded public key.
+   */
+  hex(): string {
+    return Array.from(this.#publicKey)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+}
+
+/**
+ * Metadata that can be attached to a signature.
+ */
+export class SignatureMetadata {
+  readonly #assertions: [string, unknown][] = [];
+
+  /**
+   * Adds an assertion to the metadata.
+   */
+  withAssertion(predicate: string, object: unknown): SignatureMetadata {
+    const metadata = new SignatureMetadata();
+    metadata.#assertions.push(...this.#assertions);
+    metadata.#assertions.push([predicate, object]);
+    return metadata;
+  }
+
+  /**
+   * Returns all assertions in the metadata.
+   */
+  assertions(): [string, unknown][] {
+    return this.#assertions;
+  }
+
+  /**
+   * Returns true if this metadata has any assertions.
+   */
+  hasAssertions(): boolean {
+    return this.#assertions.length > 0;
+  }
+}
+
+/**
+ * Support for signing envelopes and verifying signatures.
+ */
+declare module "../base/envelope" {
+  interface Envelope {
+    /**
+     * Creates a signature for the envelope's subject and returns a new
+     * envelope with a 'signed': Signature assertion.
+     *
+     * @param signer - The signing key
+     * @returns The signed envelope
+     *
+     * @example
+     * ```typescript
+     * const privateKey = SigningPrivateKey.generate();
+     * const envelope = Envelope.new("Hello, world!");
+     * const signed = envelope.addSignature(privateKey);
+     * ```
+     */
+    addSignature(signer: Signer): Envelope;
+
+    /**
+     * Creates a signature for the envelope's subject with optional metadata.
+     *
+     * @param signer - The signing key
+     * @param metadata - Optional metadata to attach to the signature
+     * @returns The signed envelope
+     */
+    addSignatureWithMetadata(signer: Signer, metadata?: SignatureMetadata): Envelope;
+
+    /**
+     * Creates multiple signatures for the envelope's subject.
+     *
+     * @param signers - Array of signing keys
+     * @returns The envelope with multiple signatures
+     */
+    addSignatures(signers: Signer[]): Envelope;
+
+    /**
+     * Returns whether this envelope has a valid signature from the given verifier.
+     *
+     * @param verifier - The public key to verify against
+     * @returns True if a valid signature from this verifier exists
+     */
+    hasSignatureFrom(verifier: Verifier): boolean;
+
+    /**
+     * Verifies that this envelope has a valid signature from the given verifier
+     * and returns the envelope.
+     *
+     * @param verifier - The public key to verify against
+     * @returns The verified envelope
+     * @throws {EnvelopeError} If no valid signature is found
+     */
+    verifySignatureFrom(verifier: Verifier): Envelope;
+
+    /**
+     * Returns all signature assertions in this envelope.
+     *
+     * @returns Array of signature envelopes
+     */
+    signatures(): Envelope[];
+  }
+}
+
+// Implementation
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (Envelope?.prototype) {
+  Envelope.prototype.addSignature = function (this: Envelope, signer: Signer): Envelope {
+    return this.addSignatureWithMetadata(signer, undefined);
+  };
+
+  Envelope.prototype.addSignatureWithMetadata = function (
+    this: Envelope,
+    signer: Signer,
+    metadata?: SignatureMetadata,
+  ): Envelope {
+    const digest = this.subject().digest();
+    const signature = signer.sign(digest.data());
+    let signatureEnvelope = Envelope.new(signature.data());
+
+    if (metadata?.hasAssertions() === true) {
+      // Add metadata assertions to the signature
+      for (const [predicate, object] of metadata.assertions()) {
+        signatureEnvelope = signatureEnvelope.addAssertion(
+          predicate,
+          object as string | number | boolean,
+        );
+      }
+
+      // Wrap the signature with metadata
+      signatureEnvelope = signatureEnvelope.wrap();
+
+      // Sign the wrapped envelope
+      const outerSignature = signer.sign(signatureEnvelope.digest().data());
+      signatureEnvelope = signatureEnvelope.addAssertion(SIGNED, outerSignature.data());
+    }
+
+    return this.addAssertion(SIGNED, signatureEnvelope);
+  };
+
+  Envelope.prototype.addSignatures = function (this: Envelope, signers: Signer[]): Envelope {
+    return signers.reduce((envelope, signer) => envelope.addSignature(signer), this);
+  };
+
+  Envelope.prototype.hasSignatureFrom = function (this: Envelope, verifier: Verifier): boolean {
+    const subjectDigest = this.subject().digest();
+    const signatures = this.signatures();
+
+    for (const sigEnvelope of signatures) {
+      const c = sigEnvelope.case();
+
+      if (c.type === "leaf") {
+        // Simple signature - verify directly
+        try {
+          const sigData = sigEnvelope.asByteString();
+          if (sigData !== undefined) {
+            const signature = new Signature(sigData);
+            if (verifier.verify(subjectDigest.data(), signature)) {
+              return true;
+            }
+          }
+        } catch {
+          continue;
+        }
+      } else if (c.type === "node") {
+        // Signature with metadata - it's a node with 'signed' assertion
+        // The structure is: { wrapped_signature [signed: outer_signature] }
+        // Check if this node has a 'signed' assertion
+        const outerSigs = sigEnvelope.assertions().filter((a) => {
+          const aC = a.case();
+          if (aC.type === "assertion") {
+            const pred = aC.assertion.predicate();
+            try {
+              return pred.asText() === SIGNED;
+            } catch {
+              return false;
+            }
+          }
+          return false;
+        });
+
+        for (const outerSig of outerSigs) {
+          const outerSigCase = outerSig.case();
+          if (outerSigCase.type === "assertion") {
+            const outerSigObj = outerSigCase.assertion.object();
+            try {
+              const outerSigData = outerSigObj.asByteString();
+              if (outerSigData !== undefined) {
+                const outerSignature = new Signature(outerSigData);
+
+                // The subject of this node should be a wrapped envelope
+                const nodeSubject = c.subject;
+                const nodeSubjectCase = nodeSubject.case();
+
+                // Verify outer signature against the wrapped envelope
+                if (
+                  nodeSubjectCase.type === "wrapped" &&
+                  verifier.verify(nodeSubject.digest().data(), outerSignature)
+                ) {
+                  // Now verify inner signature
+                  const wrapped = nodeSubjectCase.envelope;
+                  const innerSig = wrapped.subject();
+                  const innerSigData = innerSig.asByteString();
+                  if (innerSigData !== undefined) {
+                    const innerSignature = new Signature(innerSigData);
+                    if (verifier.verify(subjectDigest.data(), innerSignature)) {
+                      return true;
+                    }
+                  }
+                }
+              }
+            } catch {
+              continue;
+            }
+          }
+        }
+      }
+    }
+
+    return false;
+  };
+
+  Envelope.prototype.verifySignatureFrom = function (this: Envelope, verifier: Verifier): Envelope {
+    if (this.hasSignatureFrom(verifier)) {
+      return this;
+    }
+    throw EnvelopeError.general("No valid signature found from the given verifier");
+  };
+
+  Envelope.prototype.signatures = function (this: Envelope): Envelope[] {
+    const assertions = this.assertions();
+    return assertions
+      .filter((a) => {
+        const c = a.case();
+        if (c.type === "assertion") {
+          const pred = c.assertion.predicate();
+          try {
+            return pred.asText() === SIGNED;
+          } catch {
+            return false;
+          }
+        }
+        return false;
+      })
+      .map((a) => {
+        const c = a.case();
+        if (c.type === "assertion") {
+          return c.assertion.object();
+        }
+        throw EnvelopeError.general("Invalid signature assertion");
+      });
+  };
+}