@did-btcr2/api 0.2.2 → 0.3.1

package/src/crypto.ts

@@ -0,0 +1,525 @@
+import type { Bytes, Entropy, HexString, KeyBytes, SchnorrKeyPairObject, SignatureBytes } from '@did-btcr2/common';
+import {
+  BIP340Cryptosuite,
+  BIP340DataIntegrityProof,
+  BTCR2Update,
+  DataIntegrityConfig,
+  DataIntegrityProofObject,
+  type FromPublicKey,
+  type Multikey,
+  SchnorrMultikey,
+  SignedBTCR2Update,
+  UnsignedBTCR2Update,
+  VerificationResult
+} from '@did-btcr2/cryptosuite';
+import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
+import { KeyIdentifier } from '@did-btcr2/kms';
+import type { DidVerificationMethod } from '@web5/dids';
+import { KeyManagerApi } from './kms.js';
+
+/**
+ * Schnorr keypair operations.
+ * @public
+ */
+export class KeyPairApi {
+  /**
+   * Generate a new Schnorr keypair.
+   * @returns The generated Schnorr keypair.
+   */
+  generate(): SchnorrKeyPair {
+    return SchnorrKeyPair.generate();
+  }
+
+  /**
+   * Create a Schnorr keypair from secret key bytes or hex string.
+   * @param data The secret key bytes or hex string.
+   * @returns The created Schnorr keypair.
+   */
+  fromSecret(data: KeyBytes | HexString): SchnorrKeyPair {
+    return SchnorrKeyPair.fromSecret(data);
+  }
+
+  /** Create a secret key from entropy (bytes or bigint). */
+  secretKeyFrom(ent: Entropy): Secp256k1SecretKey {
+    return new Secp256k1SecretKey(ent);
+  }
+
+  /** Create a compressed public key from bytes. */
+  publicKeyFrom(byt: Bytes): CompressedSecp256k1PublicKey {
+    return new CompressedSecp256k1PublicKey(byt);
+  }
+
+  /** Deserialize a keypair from a JSON object. */
+  fromJSON(obj: SchnorrKeyPairObject): SchnorrKeyPair {
+    return SchnorrKeyPair.fromJSON(obj);
+  }
+
+  /** Serialize a keypair to a JSON object. */
+  toJSON(kp: SchnorrKeyPair): SchnorrKeyPairObject {
+    return kp.exportJSON();
+  }
+
+  /** Compare two keypairs for equality. */
+  equals(kp1: SchnorrKeyPair, kp2: SchnorrKeyPair): boolean {
+    return SchnorrKeyPair.equals(kp1, kp2);
+  }
+}
+
+/**
+ * Schnorr cryptosuite operations.
+ *
+ * Optionally stateful: call {@link use} to set a current cryptosuite, then
+ * call {@link createProof}, {@link verifyProof}, or {@link toDataIntegrityProof}
+ * without passing an explicit instance. Pass an explicit instance to any
+ * method to override the current one for that call.
+ * @public
+ */
+export class CryptosuiteApi {
+  #current?: BIP340Cryptosuite;
+
+  /** The currently active cryptosuite, or `undefined` if none is set. */
+  get current(): BIP340Cryptosuite | undefined {
+    return this.#current;
+  }
+
+  /**
+   * Set the current cryptosuite for subsequent operations.
+   * @param cs The cryptosuite to activate.
+   * @returns `this` for chaining.
+   */
+  use(cs: BIP340Cryptosuite): this {
+    this.#current = cs;
+    return this;
+  }
+
+  /** Clear the current cryptosuite. */
+  clear(): void {
+    this.#current = undefined;
+  }
+
+  /**
+   * Create a new Schnorr cryptosuite from a multikey.
+   * @param multikey The Schnorr multikey to use.
+   * @returns The created Schnorr cryptosuite.
+   */
+  create(multikey: SchnorrMultikey): BIP340Cryptosuite {
+    return new BIP340Cryptosuite(multikey);
+  }
+
+  /**
+   * Convenience: resolve a key from the KMS and create a cryptosuite in one step.
+   * @param id The multikey ID (e.g. '#initialKey').
+   * @param controller The DID that controls this key.
+   * @param keyId The KMS key identifier to resolve.
+   * @param kms The KeyManagerApi instance holding the key.
+   * @returns The created Schnorr cryptosuite.
+   */
+  createFromKms(
+    id: string,
+    controller: string,
+    keyId: KeyIdentifier,
+    kms: KeyManagerApi
+  ): BIP340Cryptosuite {
+    const pubBytes = kms.getPublicKey(keyId);
+    const mk = SchnorrMultikey.fromPublicKey({ id, controller, publicKeyBytes: pubBytes });
+    return new BIP340Cryptosuite(mk as SchnorrMultikey);
+  }
+
+  /**
+   * Convert a cryptosuite to a Data Integrity Proof instance.
+   * Uses the current cryptosuite when `cryptosuite` is omitted.
+   * @param cryptosuite Optional explicit cryptosuite to convert.
+   * @returns The Data Integrity Proof instance.
+   */
+  toDataIntegrityProof(cryptosuite?: BIP340Cryptosuite): BIP340DataIntegrityProof {
+    const cs = cryptosuite ?? this.#requireCurrent();
+    return cs.toDataIntegrityProof();
+  }
+
+  /**
+   * Create a proof for a document.
+   * Uses the current cryptosuite when `cryptosuite` is omitted.
+   * @param document The document to create the proof for.
+   * @param config Configuration for the proof creation.
+   * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+   * @returns The created proof.
+   */
+  createProof(
+    document: BTCR2Update,
+    config: DataIntegrityConfig,
+    cryptosuite?: BIP340Cryptosuite
+  ): DataIntegrityProofObject {
+    const cs = cryptosuite ?? this.#requireCurrent();
+    return cs.createProof(document, config);
+  }
+
+  /**
+   * Verify a proof for a document.
+   * Uses the current cryptosuite when `cryptosuite` is omitted.
+   * @param document The document to verify the proof for.
+   * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+   * @returns The full verification result.
+   */
+  verifyProof(document: SignedBTCR2Update, cryptosuite?: BIP340Cryptosuite): VerificationResult {
+    const cs = cryptosuite ?? this.#requireCurrent();
+    return cs.verifyProof(document);
+  }
+
+  #requireCurrent(): BIP340Cryptosuite {
+    if (!this.#current) {
+      throw new Error(
+        'No current cryptosuite set. Call cryptosuite.use(cs) first, or pass an explicit instance.'
+      );
+    }
+    return this.#current;
+  }
+}
+
+/**
+ * Data Integrity Proof operations.
+ *
+ * Optionally stateful: call {@link use} to set a current proof instance, then
+ * call {@link addProof} or {@link verifyProof} without passing an explicit
+ * instance. Pass an explicit instance to override for that call.
+ * @public
+ */
+export class DataIntegrityProofApi {
+  #current?: BIP340DataIntegrityProof;
+
+  /** The currently active proof instance, or `undefined` if none is set. */
+  get current(): BIP340DataIntegrityProof | undefined {
+    return this.#current;
+  }
+
+  /**
+   * Set the current proof instance for subsequent operations.
+   * @param p The proof instance to activate.
+   * @returns `this` for chaining.
+   */
+  use(p: BIP340DataIntegrityProof): this {
+    this.#current = p;
+    return this;
+  }
+
+  /** Clear the current proof instance. */
+  clear(): void {
+    this.#current = undefined;
+  }
+
+  /**
+   * Create a BIP340DataIntegrityProof instance with the given cryptosuite.
+   * @param cryptosuite The cryptosuite to use for proof operations.
+   * @returns The created BIP340DataIntegrityProof instance.
+   */
+  create(cryptosuite: BIP340Cryptosuite): BIP340DataIntegrityProof {
+    return new BIP340DataIntegrityProof(cryptosuite);
+  }
+
+  /**
+   * Add a proof to a document.
+   * Uses the current proof instance when `proof` is omitted.
+   * @param document The document to add the proof to.
+   * @param config Configuration for adding the proof.
+   * @param proof Optional explicit proof instance; defaults to current.
+   * @returns A document with a proof added.
+   */
+  addProof(
+    document: UnsignedBTCR2Update,
+    config: DataIntegrityConfig,
+    proof?: BIP340DataIntegrityProof
+  ): SignedBTCR2Update {
+    const p = proof ?? this.#requireCurrent();
+    return p.addProof(document, config);
+  }
+
+  /**
+   * Convenience: create a cryptosuite, proof instance, and sign a document
+   * in one call. Requires a multikey with signing capability.
+   * @param multikey The Schnorr multikey (must include secret key).
+   * @param document The unsigned document to sign.
+   * @param config The Data Integrity proof configuration.
+   * @returns The signed document with proof attached.
+   */
+  signDocument(
+    multikey: SchnorrMultikey,
+    document: UnsignedBTCR2Update,
+    config: DataIntegrityConfig
+  ): SignedBTCR2Update {
+    const cs = new BIP340Cryptosuite(multikey);
+    const proofInst = new BIP340DataIntegrityProof(cs);
+    return proofInst.addProof(document, config);
+  }
+
+  /**
+   * Verify a proof using a BIP340DataIntegrityProof instance.
+   * Uses the current proof instance when `proof` is omitted.
+   * @param document The document to verify the proof for.
+   * @param expectedPurpose The expected proof purpose.
+   * @param mediaType The media type of the document.
+   * @param expectedDomain The expected domain for the proof.
+   * @param expectedChallenge The expected challenge for the proof.
+   * @param proof Optional explicit proof instance; defaults to current.
+   * @returns The result of verifying the proof.
+   */
+  verifyProof(
+    document: string,
+    expectedPurpose: string,
+    mediaType?: string,
+    expectedDomain?: string,
+    expectedChallenge?: string,
+    proof?: BIP340DataIntegrityProof,
+  ): VerificationResult {
+    const p = proof ?? this.#requireCurrent();
+    return p.verifyProof(
+      document,
+      expectedPurpose,
+      mediaType,
+      expectedDomain,
+      expectedChallenge
+    );
+  }
+
+  #requireCurrent(): BIP340DataIntegrityProof {
+    if (!this.#current) {
+      throw new Error(
+        'No current proof instance set. Call proof.use(p) first, or pass an explicit instance.'
+      );
+    }
+    return this.#current;
+  }
+}
+
+/**
+ * Schnorr multikey operations.
+ *
+ * Optionally stateful: call {@link use} to set a current multikey, then
+ * call {@link sign}, {@link verify}, or {@link toVerificationMethod} without
+ * passing an explicit instance. Pass an explicit instance to any method to
+ * override the current one for that call.
+ * @public
+ */
+export class MultikeyApi {
+  #current?: SchnorrMultikey;
+
+  /** The currently active multikey, or `undefined` if none is set. */
+  get current(): SchnorrMultikey | undefined {
+    return this.#current;
+  }
+
+  /**
+   * Set the current multikey for subsequent operations.
+   * @param mk The multikey to activate.
+   * @returns `this` for chaining.
+   */
+  use(mk: SchnorrMultikey): this {
+    this.#current = mk;
+    return this;
+  }
+
+  /** Clear the current multikey. */
+  clear(): void {
+    this.#current = undefined;
+  }
+
+  /**
+   * Create a new Schnorr multikey from a keypair.
+   * @param id The multikey ID.
+   * @param controller The multikey controller.
+   * @param keyPair The Schnorr keypair to use.
+   * @returns The created Schnorr multikey.
+   */
+  create(id: string, controller: string, keyPair: SchnorrKeyPair): SchnorrMultikey {
+    return new SchnorrMultikey({ id, controller, keyPair });
+  }
+
+  /**
+   * Create a Schnorr multikey from raw secret key bytes.
+   * @param id The multikey ID.
+   * @param controller The multikey controller.
+   * @param secretKeyBytes The secret key bytes.
+   * @returns The created Schnorr multikey.
+   */
+  fromSecretKey(id: string, controller: string, secretKeyBytes: Bytes): SchnorrMultikey {
+    return SchnorrMultikey.fromSecretKey(id, controller, secretKeyBytes);
+  }
+
+  /**
+   * Create a verification-only multikey from public key bytes.
+   * @param params The id, controller, and publicKeyBytes.
+   * @returns The created Multikey.
+   */
+  fromPublicKey(params: FromPublicKey): Multikey {
+    return SchnorrMultikey.fromPublicKey(params);
+  }
+
+  /**
+   * Convenience: resolve a key from the KMS and create a multikey in one step.
+   * @param id The multikey ID.
+   * @param controller The multikey controller DID.
+   * @param keyId The KMS key identifier to resolve.
+   * @param kms The KeyManagerApi instance holding the key.
+   * @returns The created Multikey (verification-only; public key from KMS).
+   */
+  fromKms(id: string, controller: string, keyId: KeyIdentifier, kms: KeyManagerApi): Multikey {
+    const pubBytes = kms.getPublicKey(keyId);
+    return SchnorrMultikey.fromPublicKey({ id, controller, publicKeyBytes: pubBytes });
+  }
+
+  /**
+   * Reconstruct a multikey from a DID document's verification method.
+   * @param verificationMethod The verification method to convert.
+   * @returns The reconstructed multikey.
+   */
+  fromVerificationMethod(verificationMethod: DidVerificationMethod): SchnorrMultikey {
+    return SchnorrMultikey.fromVerificationMethod(verificationMethod);
+  }
+
+  /**
+   * Produce a DID Verification Method JSON from a multikey.
+   * Uses the current multikey when `mk` is omitted.
+   * @param mk Optional explicit multikey; defaults to current.
+   */
+  toVerificationMethod(mk?: SchnorrMultikey): DidVerificationMethod {
+    const m = mk ?? this.#requireCurrent();
+    return m.toVerificationMethod();
+  }
+
+  /**
+   * Sign bytes via the multikey (requires secret).
+   * Uses the current multikey when `mk` is omitted.
+   * @param data The data to sign.
+   * @param mk Optional explicit multikey; defaults to current.
+   */
+  sign(data: Bytes, mk?: SchnorrMultikey): SignatureBytes {
+    const m = mk ?? this.#requireCurrent();
+    return m.sign(data);
+  }
+
+  /**
+   * Verify signature via multikey.
+   * Uses the current multikey when `mk` is omitted.
+   * @param data The data that was signed.
+   * @param signature The signature to verify.
+   * @param mk Optional explicit multikey; defaults to current.
+   */
+  verify(data: Bytes, signature: SignatureBytes, mk?: SchnorrMultikey): boolean {
+    const m = mk ?? this.#requireCurrent();
+    return m.verify(signature, data);
+  }
+
+  #requireCurrent(): SchnorrMultikey {
+    if (!this.#current) {
+      throw new Error(
+        'No current multikey set. Call multikey.use(mk) first, or pass an explicit instance.'
+      );
+    }
+    return this.#current;
+  }
+}
+
+/**
+ * Aggregated cryptographic operations sub-facade.
+ *
+ * Provides direct access to the four sub-facades ({@link keypair},
+ * {@link multikey}, {@link cryptosuite}, {@link proof}) plus top-level
+ * convenience methods that orchestrate the full signing/verification
+ * pipeline using their stateful defaults.
+ *
+ * @example Stateful pipeline
+ * ```ts
+ * const api = createApi();
+ * const kp  = api.crypto.keypair.generate();
+ * const mk  = api.crypto.multikey.create('#key-1', 'did:btcr2:test', kp);
+ *
+ * // Set the active multikey — flows through to cryptosuite and proof
+ * api.crypto.activate(mk);
+ *
+ * // Now sign without threading instances
+ * const signed = api.crypto.signDocument(unsignedDoc, proofConfig);
+ * ```
+ * @public
+ */
+export class CryptoApi {
+  /** Schnorr keypair operations. */
+  readonly keypair = new KeyPairApi();
+
+  /** Schnorr Multikey operations (optionally stateful). */
+  readonly multikey = new MultikeyApi();
+
+  /** Schnorr Cryptosuite operations (optionally stateful). */
+  readonly cryptosuite = new CryptosuiteApi();
+
+  /** Data Integrity Proof operations (optionally stateful). */
+  readonly proof = new DataIntegrityProofApi();
+
+  /**
+   * Activate a multikey and propagate through the full pipeline.
+   * Sets the current multikey, creates a cryptosuite from it, and creates
+   * a proof instance from the cryptosuite — all three sub-facades become
+   * ready for stateful operations.
+   * @param mk The multikey to activate (must include a secret key for signing).
+   * @returns `this` for chaining.
+   */
+  activate(mk: SchnorrMultikey): this {
+    this.multikey.use(mk);
+    const cs = this.cryptosuite.create(mk);
+    this.cryptosuite.use(cs);
+    const p = this.proof.create(cs);
+    this.proof.use(p);
+    return this;
+  }
+
+  /**
+   * Clear stateful defaults from all sub-facades.
+   */
+  deactivate(): void {
+    this.multikey.clear();
+    this.cryptosuite.clear();
+    this.proof.clear();
+  }
+
+  /**
+   * Sign data using the current multikey.
+   * Shorthand for `crypto.multikey.sign(data)`.
+   * @param data The data to sign.
+   * @returns The signature bytes.
+   */
+  sign(data: Bytes): SignatureBytes {
+    return this.multikey.sign(data);
+  }
+
+  /**
+   * Verify a signature using the current multikey.
+   * Shorthand for `crypto.multikey.verify(data, signature)`.
+   * @param data The data that was signed.
+   * @param signature The signature to verify.
+   * @returns `true` if the signature is valid.
+   */
+  verify(data: Bytes, signature: SignatureBytes): boolean {
+    return this.multikey.verify(data, signature);
+  }
+
+  /**
+   * Sign a BTCR2 update document using the current proof instance.
+   * Shorthand for `crypto.proof.addProof(document, config)`.
+   *
+   * Requires {@link activate} to have been called first, or the three
+   * sub-facades to have been configured individually.
+   * @param document The unsigned BTCR2 update document.
+   * @param config The Data Integrity proof configuration.
+   * @returns The signed document with proof attached.
+   */
+  signDocument(document: UnsignedBTCR2Update, config: DataIntegrityConfig): SignedBTCR2Update {
+    return this.proof.addProof(document, config);
+  }
+
+  /**
+   * Verify a signed BTCR2 update document using the current cryptosuite.
+   * Shorthand for `crypto.cryptosuite.verifyProof(document)`.
+   * @param document The signed document to verify.
+   * @returns The full verification result.
+   */
+  verifyDocument(document: SignedBTCR2Update): VerificationResult {
+    return this.cryptosuite.verifyProof(document);
+  }
+}

package/src/did.ts

@@ -0,0 +1,75 @@
+import type { NetworkName } from '@did-btcr2/bitcoin';
+import type { DocumentBytes } from '@did-btcr2/common';
+import { IdentifierTypes } from '@did-btcr2/common';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { SchnorrKeyPairObject } from '@did-btcr2/common';
+import type { DidCreateOptions } from '@did-btcr2/method';
+import { Identifier, IdentifierComponents } from '@did-btcr2/method';
+import { Did } from '@web5/dids';
+import { assertBytes, assertString } from './helpers.js';
+
+/**
+ * DID identifier operations sub-facade (encode, decode, generate, parse).
+ * @public
+ */
+export class DidApi {
+  /**
+   * Encode a DID from genesis bytes and options.
+   * @param genesisBytes The genesis document bytes.
+   * @param options The creation options.
+   * @returns The encoded DID string.
+   */
+  encode(genesisBytes: DocumentBytes, options: DidCreateOptions): string {
+    assertBytes(genesisBytes, 'genesisBytes');
+    return Identifier.encode(genesisBytes, options);
+  }
+
+  /**
+   * Decode a DID into its components.
+   * @param did The DID string to decode.
+   * @returns The decoded identifier components.
+   */
+  decode(did: string): IdentifierComponents {
+    assertString(did, 'did');
+    return Identifier.decode(did);
+  }
+
+  /**
+   * Generate a new DID along with its keypair.
+   *
+   * When no `network` is given, defaults to `'regtest'` (upstream default).
+   * Pass an explicit network to generate DIDs for other networks.
+   *
+   * @param network Optional network to generate the DID for.
+   * @returns The generated keypair and DID string.
+   */
+  generate(network?: NetworkName): { keyPair: SchnorrKeyPairObject; did: string } {
+    if (!network) return Identifier.generate();
+    const kp = SchnorrKeyPair.generate();
+    const did = Identifier.encode(kp.publicKey.compressed, {
+      idType : IdentifierTypes.KEY,
+      network,
+    });
+    return { keyPair: kp.exportJSON(), did };
+  }
+
+  /**
+   * Check if a DID string is valid.
+   * @param did The DID string to validate.
+   * @returns `true` if valid, `false` otherwise.
+   */
+  isValid(did: string): boolean {
+    if (typeof did !== 'string' || did.length === 0) return false;
+    return Identifier.isValid(did);
+  }
+
+  /**
+   * Parse a DID string into a Did instance.
+   * @param did The DID string to parse.
+   * @returns The parsed Did instance, or `null` if parsing failed.
+   */
+  parse(did: string): Did | null {
+    if (typeof did !== 'string' || did.length === 0) return null;
+    return Did.parse(did);
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,35 @@
+import type { Logger } from './types.js';
+
+const noopFn = () => {};
+
+/** @internal */
+export const NOOP_LOGGER: Logger = {
+  debug : noopFn,
+  info  : noopFn,
+  warn  : noopFn,
+  error : noopFn,
+};
+
+/** @internal */
+export function assertString(value: unknown, name: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string.`);
+  }
+}
+
+/** @internal */
+export function assertBytes(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array) || value.length === 0) {
+    throw new Error(`${name} must be a non-empty Uint8Array.`);
+  }
+}
+
+/** @internal */
+export function assertCompressedPubkey(value: unknown, name: string): asserts value is Uint8Array {
+  assertBytes(value, name);
+  if (value.length !== 33) {
+    throw new Error(
+      `${name} must be a 33-byte compressed public key, got ${value.length} bytes.`
+    );
+  }
+}

package/src/index.ts

@@ -1 +1,37 @@
-export * from './api.js';
+// Upstream re-exports
+export { DidDocument, DidDocumentBuilder, Identifier } from '@did-btcr2/method';
+export { IdentifierTypes } from '@did-btcr2/common';
+export type {
+  BlockV3,
+  HttpExecutor,
+  NetworkName,
+  RawTransactionV2,
+  RestConfig,
+  RpcConfig
+} from '@did-btcr2/bitcoin';
+export type {
+  Bytes,
+  CryptosuiteName,
+  DocumentBytes,
+  HashBytes,
+  Hex,
+  JSONObject,
+  KeyBytes,
+  PatchOperation,
+  ProofBytes,
+  SchnorrKeyPairObject,
+  SignatureBytes
+} from '@did-btcr2/common';
+export type { MultikeyObject } from '@did-btcr2/cryptosuite';
+export type { DidResolutionResult, DidService, DidVerificationMethod } from '@web5/dids';
+
+// Local modules
+export * from './types.js';
+export * from './helpers.js';
+export * from './bitcoin.js';
+export * from './cas.js';
+export * from './kms.js';
+export * from './crypto.js';
+export * from './did.js';
+export * from './method.js';
+export * from './api.js';