@bcts/envelope 1.0.0-alpha.10

package/src/extension/signature.ts

@@ -0,0 +1,398 @@
+/**
+ * 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;
+  }
+}
+
+// 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");
+      });
+  };
+}

package/src/extension/types.ts

@@ -0,0 +1,92 @@
+import { Envelope } from "../base/envelope";
+import { type EnvelopeEncodableValue } from "../base/envelope-encodable";
+import { EnvelopeError } from "../base/error";
+
+/// Type system for Gordian Envelopes.
+///
+/// This module provides functionality for adding, querying, and verifying types
+/// within envelopes. In Gordian Envelope, types are implemented using the
+/// special `'isA'` predicate (the string "isA"), which is semantically
+/// equivalent to the RDF `rdf:type` concept.
+///
+/// Type information enables:
+/// - Semantic classification of envelopes
+/// - Type verification before processing content
+/// - Conversion between domain objects and envelopes
+/// - Schema validation
+///
+/// ## Type Representation
+///
+/// Types are represented as assertions with the `'isA'` predicate and an object
+/// that specifies the type. The type object is typically a string or an envelope.
+///
+/// ## Usage Patterns
+///
+/// The type system is commonly used in two ways:
+///
+/// 1. **Type Tagging**: Adding type information to envelopes to indicate their
+///    semantic meaning
+///
+///    ```typescript
+///    // Create an envelope representing a person
+///    const person = Envelope.new("Alice")
+///      .addType("Person")
+///      .addAssertion("age", 30);
+///    ```
+///
+/// 2. **Type Checking**: Verifying that an envelope has the expected type
+///    before processing
+///
+///    ```typescript
+///    function processPerson(envelope: Envelope): void {
+///      // Verify this is a person before processing
+///      envelope.checkType("Person");
+///
+///      // Now we can safely extract person-specific information
+///      const name = envelope.subject().extractString();
+///      const age = envelope.objectForPredicate("age").extractNumber();
+///
+///      console.log(`${name} is ${age} years old`);
+///    }
+///    ```
+
+/// The standard predicate for type assertions
+export const IS_A = "isA";
+
+/// Implementation of addType()
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (Envelope?.prototype) {
+  Envelope.prototype.addType = function (this: Envelope, object: EnvelopeEncodableValue): Envelope {
+    return this.addAssertion(IS_A, object);
+  };
+
+  /// Implementation of types()
+  Envelope.prototype.types = function (this: Envelope): Envelope[] {
+    return this.objectsForPredicate(IS_A);
+  };
+
+  /// Implementation of getType()
+  Envelope.prototype.getType = function (this: Envelope): Envelope {
+    const t = this.types();
+    if (t.length === 0) {
+      throw EnvelopeError.invalidType();
+    }
+    if (t.length === 1) {
+      return t[0];
+    }
+    throw EnvelopeError.ambiguousType();
+  };
+
+  /// Implementation of hasType()
+  Envelope.prototype.hasType = function (this: Envelope, t: EnvelopeEncodableValue): boolean {
+    const e = Envelope.new(t);
+    return this.types().some((x) => x.digest().equals(e.digest()));
+  };
+
+  /// Implementation of checkType()
+  Envelope.prototype.checkType = function (this: Envelope, t: EnvelopeEncodableValue): void {
+    if (!this.hasType(t)) {
+      throw EnvelopeError.invalidType();
+    }
+  };
+}

package/src/format/diagnostic.ts

@@ -0,0 +1,116 @@
+import { Envelope } from "../base/envelope";
+
+// Type for CBOR values that can appear in diagnostic notation
+type CborValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Uint8Array
+  | CborValue[]
+  | Map<CborValue, CborValue>
+  | { tag: number; value: CborValue }
+  | { type: number; value: unknown };
+
+/// Diagnostic notation formatting for Gordian Envelopes.
+///
+/// This module provides methods for converting envelopes to CBOR diagnostic
+/// notation, a human-readable text format defined in RFC 8949 §8.
+///
+/// See [RFC-8949 §8](https://www.rfc-editor.org/rfc/rfc8949.html#name-diagnostic-notation)
+/// for information on CBOR diagnostic notation.
+
+// Note: Method declarations are in the base Envelope class.
+// This module provides the prototype implementations.
+
+/// Converts a CBOR value to diagnostic notation
+function cborToDiagnostic(cbor: CborValue, indent = 0): string {
+  // Handle tagged values (CBOR tags)
+  if (typeof cbor === "object" && cbor !== null && "tag" in cbor && "value" in cbor) {
+    const tagged = cbor as { tag: number; value: CborValue };
+    return `${tagged.tag}(${cborToDiagnostic(tagged.value, indent)})`;
+  }
+
+  // Handle arrays
+  if (Array.isArray(cbor)) {
+    if (cbor.length === 0) {
+      return "[]";
+    }
+    const items = cbor.map((item) => cborToDiagnostic(item, indent + 2));
+    return `[${items.join(", ")}]`;
+  }
+
+  // Handle Maps
+  if (cbor instanceof Map) {
+    if (cbor.size === 0) {
+      return "{}";
+    }
+    const entries: string[] = [];
+    for (const [key, value] of cbor) {
+      const keyStr = cborToDiagnostic(key, indent + 2);
+      const valueStr = cborToDiagnostic(value, indent + 2);
+      entries.push(`${keyStr}: ${valueStr}`);
+    }
+    return `{${entries.join(", ")}}`;
+  }
+
+  // Handle Uint8Array (byte strings)
+  if (cbor instanceof Uint8Array) {
+    const hex = Array.from(cbor)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+    return `h'${hex}'`;
+  }
+
+  // Handle strings
+  if (typeof cbor === "string") {
+    return JSON.stringify(cbor);
+  }
+
+  // Handle CBOR objects with type information
+  if (typeof cbor === "object" && cbor !== null && "type" in cbor) {
+    const typed = cbor as { type: number; value: unknown };
+    switch (typed.type) {
+      case 0: // Unsigned
+        return String(typed.value);
+      case 1: // Negative
+        return String(-1 - Number(typed.value));
+      case 7: {
+        // Simple
+        const simpleValue = typed.value;
+        if (simpleValue !== null && typeof simpleValue === "object" && "type" in simpleValue) {
+          const floatValue = simpleValue as { type: string; value: unknown };
+          if (floatValue.type === "Float") {
+            return String(floatValue.value);
+          }
+        }
+        if (simpleValue === 20) return "false";
+        if (simpleValue === 21) return "true";
+        if (simpleValue === 22) return "null";
+        if (simpleValue === 23) return "undefined";
+        return `simple(${String(simpleValue)})`;
+      }
+    }
+  }
+
+  // Fallback for primitives
+  if (typeof cbor === "boolean") return String(cbor);
+  if (typeof cbor === "number") return String(cbor);
+  if (typeof cbor === "bigint") return String(cbor);
+  if (cbor === null) return "null";
+  if (cbor === undefined) return "undefined";
+
+  // Unknown type - try JSON stringify
+  try {
+    return JSON.stringify(cbor);
+  } catch {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    return String(cbor);
+  }
+}
+
+/// Implementation of diagnostic()
+Envelope.prototype.diagnostic = function (this: Envelope): string {
+  const cbor = this.taggedCbor();
+  return cborToDiagnostic(cbor);
+};

package/src/format/hex.ts

@@ -0,0 +1,25 @@
+import { Envelope } from "../base/envelope";
+import { cborData } from "@bcts/dcbor";
+
+/// Hex formatting for Gordian Envelopes.
+///
+/// This module provides methods for converting envelopes to hexadecimal
+/// representations of their CBOR encoding, useful for debugging and
+/// low-level inspection.
+
+// Note: Method declarations are in the base Envelope class.
+// This module provides the prototype implementations.
+
+/// Implementation of hex()
+Envelope.prototype.hex = function (this: Envelope): string {
+  const bytes = this.cborBytes();
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+/// Implementation of cborBytes()
+Envelope.prototype.cborBytes = function (this: Envelope): Uint8Array {
+  const cbor = this.taggedCbor();
+  return cborData(cbor);
+};

package/src/format/index.ts

@@ -0,0 +1,13 @@
+/// Format module exports for Gordian Envelope.
+///
+/// This module provides various formatting options for displaying and
+/// serializing envelopes, including hex, diagnostic, notation, tree,
+/// and mermaid diagram formats.
+
+// Export types
+export type { TreeFormatOptions } from "./tree";
+
+// Import side-effect modules to register prototype extensions
+import "./hex";
+import "./diagnostic";
+import "./tree";