@did-btcr2/method 0.50.0 → 0.51.0

package/dist/cjs/index.js

@@ -61,6 +61,7 @@ __export(index_exports, {
   deriveSingletonAddress: () => deriveSingletonAddress,
   detectSingletonScriptKind: () => detectSingletonScriptKind,
   extractOpReturnSignal: () => extractOpReturnSignal,
+  getAggregationCommunicationKey: () => getAggregationCommunicationKey,
   isMultikeyVerificationMethod: () => isMultikeyVerificationMethod,
   opReturnScript: () => opReturnScript,
   resolveBtcr2SenderPk: () => resolveBtcr2SenderPk,
@@ -1285,23 +1286,15 @@ var BeaconSignalDiscovery = class {
 };
 
 // src/core/did-sender-resolver.ts
-var import_keypair2 = require("@did-btcr2/keypair");
-function resolveBtcr2SenderPk(did) {
-  try {
-    const components = Identifier.decode(did);
-    if (components.idType === "KEY") {
-      return new import_keypair2.CompressedSecp256k1PublicKey(components.genesisBytes);
-    }
-  } catch {
-  }
-  return void 0;
-}
+var import_common13 = require("@did-btcr2/common");
+var import_cryptosuite3 = require("@did-btcr2/cryptosuite");
+var import_keypair4 = require("@did-btcr2/keypair");
 
 // src/core/resolver.ts
 var import_bitcoin5 = require("@did-btcr2/bitcoin");
 var import_common12 = require("@did-btcr2/common");
 var import_cryptosuite2 = require("@did-btcr2/cryptosuite");
-var import_keypair4 = require("@did-btcr2/keypair");
+var import_keypair3 = require("@did-btcr2/keypair");
 
 // src/did-btcr2.ts
 var import_common11 = require("@did-btcr2/common");
@@ -1314,7 +1307,7 @@ var import_cryptosuite = require("@did-btcr2/cryptosuite");
 // src/utils/did-document.ts
 var import_bitcoin4 = require("@did-btcr2/bitcoin");
 var import_common9 = require("@did-btcr2/common");
-var import_keypair3 = require("@did-btcr2/keypair");
+var import_keypair2 = require("@did-btcr2/keypair");
 var import_utils4 = require("@web5/dids/utils");
 var import_btc_signer3 = require("@scure/btc-signer");
 var BTCR2_DID_DOCUMENT_CONTEXT = [
@@ -1652,7 +1645,7 @@ var GenesisDocument = class _GenesisDocument extends DidDocument {
    * @returns {GenesisDocument} A new GenesisDocument with the placeholder ID.
    */
   static fromPublicKey(publicKey, network) {
-    const pk = new import_keypair3.CompressedSecp256k1PublicKey(publicKey);
+    const pk = new import_keypair2.CompressedSecp256k1PublicKey(publicKey);
     const id = ID_PLACEHOLDER_VALUE;
     const address = (0, import_btc_signer3.p2pkh)(pk.compressed, (0, import_bitcoin4.getNetwork)(network)).address;
     const services = [{
@@ -2212,7 +2205,7 @@ var Resolver = class _Resolver {
   static deterministic(didComponents) {
     const genesisBytes = didComponents.genesisBytes;
     const did = Identifier.encode(genesisBytes, didComponents);
-    const { multibase } = new import_keypair4.CompressedSecp256k1PublicKey(genesisBytes);
+    const { multibase } = new import_keypair3.CompressedSecp256k1PublicKey(genesisBytes);
     const service = BeaconUtils.generateBeaconServices({
       id: did,
       publicKey: genesisBytes,
@@ -2635,13 +2628,48 @@ var Resolver = class _Resolver {
   }
 };
 
+// src/core/did-sender-resolver.ts
+function getAggregationCommunicationKey(document) {
+  const invocation = document.capabilityInvocation?.[0];
+  if (invocation === void 0) {
+    throw new import_common13.DidDocumentError(
+      "Cannot derive aggregation communication key: capabilityInvocation is absent",
+      import_common13.INVALID_DID_DOCUMENT,
+      { id: document.id }
+    );
+  }
+  const vm = typeof invocation === "string" ? document.verificationMethod?.find((method) => method.id === invocation) : invocation;
+  if (!vm) {
+    throw new import_common13.DidDocumentError(
+      `Cannot derive aggregation communication key: capabilityInvocation[0] "${invocation}" does not resolve to a verification method`,
+      import_common13.INVALID_DID_DOCUMENT,
+      { id: document.id, invocation }
+    );
+  }
+  return import_cryptosuite3.SchnorrMultikey.fromVerificationMethod(vm).publicKey;
+}
+function resolveBtcr2SenderPk(did, opts) {
+  try {
+    const components = Identifier.decode(did);
+    if (components.idType === "KEY") {
+      return new import_keypair4.CompressedSecp256k1PublicKey(components.genesisBytes);
+    }
+    if (opts?.genesisDocument) {
+      const document = Resolver.external(components, opts.genesisDocument);
+      return getAggregationCommunicationKey(document);
+    }
+  } catch {
+  }
+  return void 0;
+}
+
 // src/utils/did-document-builder.ts
-var import_common13 = require("@did-btcr2/common");
+var import_common14 = require("@did-btcr2/common");
 var DidDocumentBuilder = class {
   document = {};
   constructor(initialDocument) {
     if (!initialDocument.id) {
-      throw new import_common13.DidDocumentError('Missing required "id" property', import_common13.INVALID_DID_DOCUMENT, initialDocument);
+      throw new import_common14.DidDocumentError('Missing required "id" property', import_common14.INVALID_DID_DOCUMENT, initialDocument);
     }
     this.document.id = initialDocument.id;
     this.document.verificationMethod = initialDocument.verificationMethod ?? [];
@@ -2732,6 +2760,7 @@ var DidDocumentBuilder = class {
   deriveSingletonAddress,
   detectSingletonScriptKind,
   extractOpReturnSignal,
+  getAggregationCommunicationKey,
   isMultikeyVerificationMethod,
   opReturnScript,
   resolveBtcr2SenderPk,

package/dist/esm/core/did-sender-resolver.js

@@ -1,25 +1,90 @@
+import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
+import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
 import { Identifier } from './identifier.js';
+import { Resolver } from './resolver.js';
+/**
+ * Derive the aggregation communication public key from a resolved did:btcr2 DID Document.
+ *
+ * The communication key is the verification method referenced by
+ * `capabilityInvocation[0]`, resolved to its public key. This is the exact relationship
+ * the method already enforces for DID updates (construct and sign require the signing
+ * method to be in `capabilityInvocation`, the update proof is built and verified with
+ * `proofPurpose: 'capabilityInvocation'`), so binding the transport communication key to
+ * it yields the invariant "transport-authenticated as D implies authorized to update D."
+ * For a KEY (`k1`) document the single deterministic key is already the sole
+ * `capabilityInvocation` entry, so this is a no-op for KEY DIDs.
+ *
+ * There is deliberately no `verificationMethod[0]` fallback: a document without
+ * `capabilityInvocation` cannot be updated at all, so it is useless for aggregation and is
+ * rejected here rather than bound to an unrelated key.
+ *
+ * @param {DidDocument} document The resolved DID Document (placeholder id already replaced).
+ * @returns {CompressedSecp256k1PublicKey} The compressed public key of the communication method.
+ * @throws {DidDocumentError} If `capabilityInvocation` is absent or its first entry does not
+ *   resolve to a verification method in the document.
+ */
+export function getAggregationCommunicationKey(document) {
+    const invocation = document.capabilityInvocation?.[0];
+    if (invocation === undefined) {
+        throw new DidDocumentError('Cannot derive aggregation communication key: capabilityInvocation is absent', INVALID_DID_DOCUMENT, { id: document.id });
+    }
+    // Resolve capabilityInvocation[0] to a verification method: a string reference is
+    // dereferenced by id against verificationMethod; an embedded method is used directly.
+    // A local id lookup is used rather than getSigningMethod, which defaults to #initialKey
+    // and does not resolve embedded methods.
+    const vm = typeof invocation === 'string'
+        ? document.verificationMethod?.find(method => method.id === invocation)
+        : invocation;
+    if (!vm) {
+        throw new DidDocumentError(`Cannot derive aggregation communication key: capabilityInvocation[0] "${invocation}" `
+            + 'does not resolve to a verification method', INVALID_DID_DOCUMENT, { id: document.id, invocation });
+    }
+    return SchnorrMultikey.fromVerificationMethod(vm).publicKey;
+}
 /**
  * Resolve a did:btcr2 sender's communication public key from its DID, for the
- * aggregation HTTP transport's `resolveSenderPk` option: a KEY identifier decodes to
- * its genesis public key. The aggregation transport is DID-method-agnostic and does
- * not name `Identifier`; method supplies this resolver when it wires the transport so
- * a sender that is not a pre-registered peer can still be authenticated from its DID.
+ * aggregation HTTP transport's `resolveSenderPk` option.
+ *
+ * A KEY (`k1`) identifier decodes directly to its genesis public key: the DID string is
+ * the key. An EXTERNAL (`x1`) identifier is a commitment to the hash of a genesis
+ * document, so there is no key in the DID string. When the genesis document is supplied
+ * in-band (via `opts.genesisDocument`), it is self-verifying against the DID: `Resolver`'s
+ * external path recomputes its canonical hash, compares it to the identifier's genesis
+ * bytes (throwing on mismatch), and resolves it, after which the communication key is
+ * derived from `capabilityInvocation[0]` ({@link getAggregationCommunicationKey}). Without
+ * a genesis document, an `x1` DID still resolves to `undefined`, so callers that pass no
+ * second argument behave exactly as before.
  *
- * @param did The sender's DID.
- * @returns The sender's compressed public key, or `undefined` when the DID is not a
- *   decodable did:btcr2 KEY identifier (resolution then falls back to registered peers).
+ * The aggregation transport is DID-method-agnostic and does not name `Identifier`; method
+ * supplies this resolver when it wires the transport so a sender that is not a
+ * pre-registered peer can still be authenticated from its DID.
+ *
+ * @param {string} did The sender's DID.
+ * @param {object} [opts] Optional resolution inputs.
+ * @param {object} [opts.genesisDocument] The `x1` sender's genesis document, carried in-band
+ *   on the bootstrap opt-in. Ignored for KEY identifiers.
+ * @returns {CompressedSecp256k1PublicKey | undefined} The sender's compressed public key, or
+ *   `undefined` when the DID is not a decodable did:btcr2 identifier, is an `x1` identifier
+ *   with no (or a non-matching) genesis document, or has no usable communication key.
  */
-export function resolveBtcr2SenderPk(did) {
+export function resolveBtcr2SenderPk(did, opts) {
     try {
         const components = Identifier.decode(did);
         if (components.idType === 'KEY') {
             return new CompressedSecp256k1PublicKey(components.genesisBytes);
         }
+        // EXTERNAL (x1): the DID commits to the hash of a genesis document. With the genesis
+        // supplied in-band, verify it hashes to the DID and derive the communication key from
+        // it; without it, there is no key to return.
+        if (opts?.genesisDocument) {
+            const document = Resolver.external(components, opts.genesisDocument);
+            return getAggregationCommunicationKey(document);
+        }
     }
     catch {
-        // Not a decodable did:btcr2 KEY identifier.
+        // Not a decodable did:btcr2 identifier, the genesis does not hash to the DID, or the
+        // document has no usable capabilityInvocation communication key.
     }
     return undefined;
 }

package/dist/esm/core/did-sender-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"did-sender-resolver.js","sourceRoot":"","sources":["../../../src/core/did-sender-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAG,UAAU,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC/B,OAAO,IAAI,4BAA4B,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"did-sender-resolver.js","sourceRoot":"","sources":["../../../src/core/did-sender-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAqB;IAErB,MAAM,UAAU,GAAG,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,CAAC;IACtD,IAAG,UAAU,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,gBAAgB,CACxB,6EAA6E,EAC7E,oBAAoB,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAC1C,CAAC;IACJ,CAAC;IAED,kFAAkF;IAClF,sFAAsF;IACtF,wFAAwF;IACxF,yCAAyC;IACzC,MAAM,EAAE,GAAsC,OAAO,UAAU,KAAK,QAAQ;QAC1E,CAAC,CAAC,QAAQ,CAAC,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,UAAU,CAAC;QACvE,CAAC,CAAC,UAAU,CAAC;IAEf,IAAG,CAAC,EAAE,EAAE,CAAC;QACP,MAAM,IAAI,gBAAgB,CACxB,yEAAyE,UAAU,IAAI;cACnF,2CAA2C,EAC/C,oBAAoB,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,OAAO,eAAe,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,IAAmC;IAEnC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAG,UAAU,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC/B,OAAO,IAAI,4BAA4B,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;QACnE,CAAC;QACD,qFAAqF;QACrF,sFAAsF;QACtF,6CAA6C;QAC7C,IAAG,IAAI,EAAE,eAAe,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;YACrE,OAAO,8BAA8B,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qFAAqF;QACrF,iEAAiE;IACnE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types/core/did-sender-resolver.d.ts

@@ -1,14 +1,54 @@
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import type { DidDocument } from '../utils/did-document.js';
+/**
+ * Derive the aggregation communication public key from a resolved did:btcr2 DID Document.
+ *
+ * The communication key is the verification method referenced by
+ * `capabilityInvocation[0]`, resolved to its public key. This is the exact relationship
+ * the method already enforces for DID updates (construct and sign require the signing
+ * method to be in `capabilityInvocation`, the update proof is built and verified with
+ * `proofPurpose: 'capabilityInvocation'`), so binding the transport communication key to
+ * it yields the invariant "transport-authenticated as D implies authorized to update D."
+ * For a KEY (`k1`) document the single deterministic key is already the sole
+ * `capabilityInvocation` entry, so this is a no-op for KEY DIDs.
+ *
+ * There is deliberately no `verificationMethod[0]` fallback: a document without
+ * `capabilityInvocation` cannot be updated at all, so it is useless for aggregation and is
+ * rejected here rather than bound to an unrelated key.
+ *
+ * @param {DidDocument} document The resolved DID Document (placeholder id already replaced).
+ * @returns {CompressedSecp256k1PublicKey} The compressed public key of the communication method.
+ * @throws {DidDocumentError} If `capabilityInvocation` is absent or its first entry does not
+ *   resolve to a verification method in the document.
+ */
+export declare function getAggregationCommunicationKey(document: DidDocument): CompressedSecp256k1PublicKey;
 /**
  * Resolve a did:btcr2 sender's communication public key from its DID, for the
- * aggregation HTTP transport's `resolveSenderPk` option: a KEY identifier decodes to
- * its genesis public key. The aggregation transport is DID-method-agnostic and does
- * not name `Identifier`; method supplies this resolver when it wires the transport so
- * a sender that is not a pre-registered peer can still be authenticated from its DID.
- *
- * @param did The sender's DID.
- * @returns The sender's compressed public key, or `undefined` when the DID is not a
- *   decodable did:btcr2 KEY identifier (resolution then falls back to registered peers).
+ * aggregation HTTP transport's `resolveSenderPk` option.
+ *
+ * A KEY (`k1`) identifier decodes directly to its genesis public key: the DID string is
+ * the key. An EXTERNAL (`x1`) identifier is a commitment to the hash of a genesis
+ * document, so there is no key in the DID string. When the genesis document is supplied
+ * in-band (via `opts.genesisDocument`), it is self-verifying against the DID: `Resolver`'s
+ * external path recomputes its canonical hash, compares it to the identifier's genesis
+ * bytes (throwing on mismatch), and resolves it, after which the communication key is
+ * derived from `capabilityInvocation[0]` ({@link getAggregationCommunicationKey}). Without
+ * a genesis document, an `x1` DID still resolves to `undefined`, so callers that pass no
+ * second argument behave exactly as before.
+ *
+ * The aggregation transport is DID-method-agnostic and does not name `Identifier`; method
+ * supplies this resolver when it wires the transport so a sender that is not a
+ * pre-registered peer can still be authenticated from its DID.
+ *
+ * @param {string} did The sender's DID.
+ * @param {object} [opts] Optional resolution inputs.
+ * @param {object} [opts.genesisDocument] The `x1` sender's genesis document, carried in-band
+ *   on the bootstrap opt-in. Ignored for KEY identifiers.
+ * @returns {CompressedSecp256k1PublicKey | undefined} The sender's compressed public key, or
+ *   `undefined` when the DID is not a decodable did:btcr2 identifier, is an `x1` identifier
+ *   with no (or a non-matching) genesis document, or has no usable communication key.
  */
-export declare function resolveBtcr2SenderPk(did: string): CompressedSecp256k1PublicKey | undefined;
+export declare function resolveBtcr2SenderPk(did: string, opts?: {
+    genesisDocument?: object;
+}): CompressedSecp256k1PublicKey | undefined;
 //# sourceMappingURL=did-sender-resolver.d.ts.map

package/dist/types/core/did-sender-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"did-sender-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/did-sender-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAGlE;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,4BAA4B,GAAG,SAAS,CAU1F"}
+{"version":3,"file":"did-sender-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/did-sender-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,0BAA0B,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,WAAW,GACpB,4BAA4B,CA0B9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,4BAA4B,GAAG,SAAS,CAkB1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "type": "module",
   "description": "Reference implementation for the did:btcr2 DID method written in TypeScript and JavaScript. did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. This is the core method implementation for the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -66,49 +66,35 @@
   "dependencies": {
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
-    "@noble/secp256k1": "^2.3.0",
     "@scure/base": "^1.2.6",
-    "@scure/bip32": "^1.7.0",
-    "@scure/bip39": "^1.6.0",
     "@scure/btc-signer": "^1.8.1",
-    "@web5/common": "^1.1.0",
-    "@web5/crypto": "^1.0.6",
     "@web5/dids": "^1.2.0",
-    "canonicalize": "^2.1.0",
-    "dotenv": "^16.6.1",
-    "nostr-tools": "^2.23.3",
-    "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/bitcoin": "^0.8.0",
     "@did-btcr2/smt": "^0.3.0",
-    "@did-btcr2/cryptosuite": "^9.0.0",
-    "@did-btcr2/bitcoin": "^0.8.0"
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/cryptosuite": "^9.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/chai": "^5.2.3",
-    "@types/chai-as-promised": "^8.0.2",
-    "@types/eslint": "^9.6.1",
     "@types/mocha": "^10.0.10",
     "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "c8": "^10.1.3",
     "chai": "^5.3.3",
-    "chai-as-promised": "^8.0.2",
     "commander": "^13.1.0",
     "esbuild": "^0.24.2",
     "eslint": "^9.39.4",
     "eslint-plugin-mocha": "^10.5.0",
     "globals": "^15.15.0",
     "mocha": "^10.8.2",
-    "mocha-junit-reporter": "^2.2.1",
     "multiformats": "^13.4.2",
     "node-stdlib-browser": "^1.3.1",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.0"
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "clean": "rimraf dist coverage tests/compiled",

package/src/core/did-sender-resolver.ts

@@ -1,25 +1,106 @@
+import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
+import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import type { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
 import { Identifier } from './identifier.js';
+import { Resolver } from './resolver.js';
+
+/**
+ * Derive the aggregation communication public key from a resolved did:btcr2 DID Document.
+ *
+ * The communication key is the verification method referenced by
+ * `capabilityInvocation[0]`, resolved to its public key. This is the exact relationship
+ * the method already enforces for DID updates (construct and sign require the signing
+ * method to be in `capabilityInvocation`, the update proof is built and verified with
+ * `proofPurpose: 'capabilityInvocation'`), so binding the transport communication key to
+ * it yields the invariant "transport-authenticated as D implies authorized to update D."
+ * For a KEY (`k1`) document the single deterministic key is already the sole
+ * `capabilityInvocation` entry, so this is a no-op for KEY DIDs.
+ *
+ * There is deliberately no `verificationMethod[0]` fallback: a document without
+ * `capabilityInvocation` cannot be updated at all, so it is useless for aggregation and is
+ * rejected here rather than bound to an unrelated key.
+ *
+ * @param {DidDocument} document The resolved DID Document (placeholder id already replaced).
+ * @returns {CompressedSecp256k1PublicKey} The compressed public key of the communication method.
+ * @throws {DidDocumentError} If `capabilityInvocation` is absent or its first entry does not
+ *   resolve to a verification method in the document.
+ */
+export function getAggregationCommunicationKey(
+  document: DidDocument,
+): CompressedSecp256k1PublicKey {
+  const invocation = document.capabilityInvocation?.[0];
+  if(invocation === undefined) {
+    throw new DidDocumentError(
+      'Cannot derive aggregation communication key: capabilityInvocation is absent',
+      INVALID_DID_DOCUMENT, { id: document.id }
+    );
+  }
+
+  // Resolve capabilityInvocation[0] to a verification method: a string reference is
+  // dereferenced by id against verificationMethod; an embedded method is used directly.
+  // A local id lookup is used rather than getSigningMethod, which defaults to #initialKey
+  // and does not resolve embedded methods.
+  const vm: DidVerificationMethod | undefined = typeof invocation === 'string'
+    ? document.verificationMethod?.find(method => method.id === invocation)
+    : invocation;
+
+  if(!vm) {
+    throw new DidDocumentError(
+      `Cannot derive aggregation communication key: capabilityInvocation[0] "${invocation}" `
+        + 'does not resolve to a verification method',
+      INVALID_DID_DOCUMENT, { id: document.id, invocation }
+    );
+  }
+
+  return SchnorrMultikey.fromVerificationMethod(vm).publicKey;
+}
 
 /**
  * Resolve a did:btcr2 sender's communication public key from its DID, for the
- * aggregation HTTP transport's `resolveSenderPk` option: a KEY identifier decodes to
- * its genesis public key. The aggregation transport is DID-method-agnostic and does
- * not name `Identifier`; method supplies this resolver when it wires the transport so
- * a sender that is not a pre-registered peer can still be authenticated from its DID.
+ * aggregation HTTP transport's `resolveSenderPk` option.
  *
- * @param did The sender's DID.
- * @returns The sender's compressed public key, or `undefined` when the DID is not a
- *   decodable did:btcr2 KEY identifier (resolution then falls back to registered peers).
+ * A KEY (`k1`) identifier decodes directly to its genesis public key: the DID string is
+ * the key. An EXTERNAL (`x1`) identifier is a commitment to the hash of a genesis
+ * document, so there is no key in the DID string. When the genesis document is supplied
+ * in-band (via `opts.genesisDocument`), it is self-verifying against the DID: `Resolver`'s
+ * external path recomputes its canonical hash, compares it to the identifier's genesis
+ * bytes (throwing on mismatch), and resolves it, after which the communication key is
+ * derived from `capabilityInvocation[0]` ({@link getAggregationCommunicationKey}). Without
+ * a genesis document, an `x1` DID still resolves to `undefined`, so callers that pass no
+ * second argument behave exactly as before.
+ *
+ * The aggregation transport is DID-method-agnostic and does not name `Identifier`; method
+ * supplies this resolver when it wires the transport so a sender that is not a
+ * pre-registered peer can still be authenticated from its DID.
+ *
+ * @param {string} did The sender's DID.
+ * @param {object} [opts] Optional resolution inputs.
+ * @param {object} [opts.genesisDocument] The `x1` sender's genesis document, carried in-band
+ *   on the bootstrap opt-in. Ignored for KEY identifiers.
+ * @returns {CompressedSecp256k1PublicKey | undefined} The sender's compressed public key, or
+ *   `undefined` when the DID is not a decodable did:btcr2 identifier, is an `x1` identifier
+ *   with no (or a non-matching) genesis document, or has no usable communication key.
  */
-export function resolveBtcr2SenderPk(did: string): CompressedSecp256k1PublicKey | undefined {
+export function resolveBtcr2SenderPk(
+  did: string,
+  opts?: { genesisDocument?: object },
+): CompressedSecp256k1PublicKey | undefined {
   try {
     const components = Identifier.decode(did);
     if(components.idType === 'KEY') {
       return new CompressedSecp256k1PublicKey(components.genesisBytes);
     }
+    // EXTERNAL (x1): the DID commits to the hash of a genesis document. With the genesis
+    // supplied in-band, verify it hashes to the DID and derive the communication key from
+    // it; without it, there is no key to return.
+    if(opts?.genesisDocument) {
+      const document = Resolver.external(components, opts.genesisDocument);
+      return getAggregationCommunicationKey(document);
+    }
   } catch {
-    // Not a decodable did:btcr2 KEY identifier.
+    // Not a decodable did:btcr2 identifier, the genesis does not hash to the DID, or the
+    // document has no usable capabilityInvocation communication key.
   }
   return undefined;
 }