@did-btcr2/method 0.56.0 → 0.58.0

package/dist/types/utils/appendix.d.ts

@@ -8,11 +8,37 @@ import type { RootCapability } from '../core/interfaces.js';
  */
 export declare class Appendix {
     /**
-     * Extracts a DID fragment from a given input
-     * @param {unknown} input The input to extract the DID fragment from
-     * @returns {string | undefined} The extracted DID fragment or undefined if not found
+     * Resolves a DID URL that may be written as a relative reference against the
+     * DID it appears under. DID Core permits the `id` of a verification method or
+     * service, and the entries of a verification relationship, to be a relative
+     * DID URL such as `#initialKey`; it denotes that fragment of `did`. Absolute
+     * DID URLs are returned unchanged, so both spellings of the same reference
+     * compare equal without discarding the DID being compared.
+     *
+     * @param {unknown} input The DID URL to resolve. Non-strings yield `undefined`.
+     * @param {string} did The DID the relative reference is resolved against.
+     * @returns {string | undefined} The absolute DID URL, or `undefined` if `input` is not a usable string.
+     */
+    static absoluteDidUrl(input: unknown, did: string): string | undefined;
+    /**
+     * Resolves a verification relationship entry to the absolute DID URL of the method it
+     * names. A relationship entry is either a reference to a method defined elsewhere in the
+     * document, or a method embedded inline, which names itself with its own `id`; either
+     * spelling may be a relative DID URL.
+     *
+     * Every comparison of a relationship entry against a method id goes through this helper,
+     * on both the read path and the write path, so the two admit exactly the same spellings.
+     *
+     * Malformed entries yield `undefined` rather than a placeholder string, so two unusable
+     * values never compare equal to each other. Callers comparing a resolved entry must still
+     * reject an `undefined` target before comparing, or an unusable target matches an
+     * unusable entry.
+     *
+     * @param {unknown} entry The relationship entry: a reference, or an embedded method.
+     * @param {string} did The DID the relative reference is resolved against.
+     * @returns {string | undefined} The absolute DID URL, or `undefined` if unusable.
      */
-    static extractDidFragment(input: unknown): string | undefined;
+    static relationshipMethodId(entry: unknown, did: string): string | undefined;
     /**
      * Validates that the given object is a DidVerificationMethod
      * @param {unknown} obj The object to validate

package/dist/types/utils/appendix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appendix.d.ts","sourceRoot":"","sources":["../../../src/utils/appendix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EAAC,MAAM,YAAY,CAAC;AAO3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB;;;;OAIG;WACW,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAMpE;;;;OAIG;WACW,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB;IAcjF;;;;OAIG;WACW,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU;IAW3D;;;;;OAKG;WACW,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,qBAAqB,EAAE;IAgBvF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc;IAU/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;WACW,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;CA8CtE"}
+{"version":3,"file":"appendix.d.ts","sourceRoot":"","sources":["../../../src/utils/appendix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EAAC,MAAM,YAAY,CAAC;AAO3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB;;;;;;;;;;;OAWG;WACW,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM7E;;;;;;;;;;;;;;;;;OAiBG;WACW,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOnF;;;;OAIG;WACW,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB;IAcjF;;;;OAIG;WACW,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU;IAW3D;;;;;OAKG;WACW,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,qBAAqB,EAAE;IAgBvF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc;IAU/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;WACW,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;CA8CtE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.56.0",
+  "version": "0.58.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",
@@ -69,11 +69,11 @@
     "@scure/base": "^1.2.6",
     "@scure/btc-signer": "^1.8.1",
     "@web5/dids": "^1.2.0",
-    "@did-btcr2/common": "^9.3.0",
     "@did-btcr2/bitcoin": "^0.10.0",
     "@did-btcr2/smt": "^0.3.0",
     "@did-btcr2/cryptosuite": "^10.0.0",
-    "@did-btcr2/keypair": "^0.13.1"
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/common": "^9.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/beacon/beacon.ts

@@ -544,8 +544,19 @@ export abstract class SinglePartyBeacon {
    */
   readonly service: BeaconService;
 
-  constructor(service: BeaconService) {
+  /**
+   * The absolute did:btcr2 identifier this beacon instance serves.
+   *
+   * Injected by the caller rather than recovered from {@link service}. A beacon
+   * service `id` is permitted to be a relative DID URL (`#beacon-1`), which
+   * carries no DID to strip a fragment from, so deriving the subject from it is
+   * only correct for the absolute spelling.
+   */
+  readonly did: string;
+
+  constructor(service: BeaconService, did: string) {
     this.service = service;
+    this.did = did;
   }
 
   /**

package/src/core/beacon/cas-beacon.ts

@@ -57,9 +57,10 @@ export class CASBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of CASBeacon.
    * @param {BeaconService} service The service of the Beacon.
+   * @param {string} did The absolute did:btcr2 identifier this beacon serves.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'CASBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'CASBeacon' }, did);
   }
 
   /**
@@ -82,8 +83,8 @@ export class CASBeacon extends SinglePartyBeacon {
     const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
     const needs = new Array<DataNeed>();
 
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID under resolution keys this beacon's announcement entry.
+    const did = this.did;
 
     for(const signal of signals) {
       // Signal bytes are hex, matches hex-keyed sidecar maps directly
@@ -160,8 +161,8 @@ export class CASBeacon extends SinglePartyBeacon {
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
   ): Promise<BroadcastResult> {
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID this beacon serves keys its announcement entry.
+    const did = this.did;
 
     // Hash the signed update (base64urlnopad for the CAS Announcement entry per spec)
     const updateHash = canonicalHash(signedUpdate);

package/src/core/beacon/factory.ts

@@ -14,16 +14,18 @@ export class BeaconFactory {
   /**
    * Establish a Beacon instance based on the provided service and optional sidecar data.
    * @param {BeaconService} service The beacon service configuration.
+   * @param {string} did The absolute did:btcr2 identifier the beacon serves. Supplied
+   *   by the caller because a beacon service `id` may be a relative DID URL.
    * @returns {SinglePartyBeacon} The established Beacon instance.
    */
-  static establish(service: BeaconService): SinglePartyBeacon {
+  static establish(service: BeaconService, did: string): SinglePartyBeacon {
     switch (service.type) {
       case 'SingletonBeacon':
-        return new SingletonBeacon(service);
+        return new SingletonBeacon(service, did);
       case 'CASBeacon':
-        return new CASBeacon(service);
+        return new CASBeacon(service, did);
       case 'SMTBeacon':
-        return new SMTBeacon(service);
+        return new SMTBeacon(service, did);
       default:
         throw new MethodError('Invalid Beacon Type', 'INVALID_BEACON_ERROR', service);
     }

package/src/core/beacon/interfaces.ts

@@ -76,4 +76,4 @@ export interface BeaconSignal {
  *
  * @param announcement The CAS Announcement object (DID to update hash mapping).
  */
-export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;
+export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;

package/src/core/beacon/singleton-beacon.ts

@@ -20,8 +20,8 @@ export class SingletonBeacon extends SinglePartyBeacon {
    * Creates an instance of SingletonBeacon.
    * @param {BeaconService} service The BeaconService object representing the funded beacon to announce the update to.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'SingletonBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'SingletonBeacon' }, did);
   }
 
   /**

package/src/core/beacon/smt-beacon.ts

@@ -27,9 +27,10 @@ export class SMTBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
    * @param {BeaconService} service The Beacon service.
+   * @param {string} did The absolute did:btcr2 identifier this beacon serves.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'SMTBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'SMTBeacon' }, did);
   }
 
   /**
@@ -52,8 +53,8 @@ export class SMTBeacon extends SinglePartyBeacon {
     const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
     const needs = new Array<DataNeed>();
 
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID under resolution keys this beacon's leaf index.
+    const did = this.did;
 
     for(const signal of signals) {
       // Signal bytes are the hex-encoded SMT root hash; smtMap is keyed by proof.id (also hex)
@@ -144,8 +145,8 @@ export class SMTBeacon extends SinglePartyBeacon {
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<BroadcastResult> {
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID keys this beacon's leaf index in the tree.
+    const did = this.did;
 
     // Build a single-entry SMT from the signed update
     const canonicalBytes = new TextEncoder().encode(canonicalize(signedUpdate));

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

@@ -1,6 +1,7 @@
 import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
 import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import { Appendix } from '../utils/appendix.js';
 import type { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
 import { Identifier } from './identifier.js';
 import { Resolver } from './resolver.js';
@@ -40,9 +41,16 @@ export function getAggregationCommunicationKey(
   // 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.
+  // and does not resolve embedded methods. Reference and method id are each resolved to an
+  // absolute DID URL first, because either may be spelled as a relative DID URL; an
+  // unusable reference resolves to nothing rather than to the first unusable method id.
+  const invocationId = Appendix.absoluteDidUrl(invocation, document.id);
   const vm: DidVerificationMethod | undefined = typeof invocation === 'string'
-    ? document.verificationMethod?.find(method => method.id === invocation)
+    ? (invocationId === undefined
+      ? undefined
+      : document.verificationMethod?.find(
+        method => Appendix.absoluteDidUrl(method.id, document.id) === invocationId
+      ))
     : invocation;
 
   if(!vm) {

package/src/core/interfaces.ts

@@ -46,6 +46,7 @@ export interface ResolutionOptions extends DidResolutionOptions {
    * document is well-formed, the resolver simply stopped at the caller's limit.
    */
   maxDiscoveryRounds?: number;
+
 }
 
 /**

package/src/core/resolver.ts

@@ -149,32 +149,6 @@ function isSMTProof(value: unknown): value is SMTProof {
     && Array.isArray(value.hashes);
 }
 
-// ─── verification relationship membership ────────────────────────────────────
-
-/**
- * Resolves a verification relationship entry to the absolute DID URL of the
- * method it names, or `undefined` when the entry names no method.
- *
- * An entry is either a reference (a bare fragment such as `#key-0`, or an
- * absolute DID URL) or an embedded verification method object. A bare fragment
- * is relative to the document that carries it, so it is resolved against
- * `documentId` before comparison; every other string is returned unchanged, so
- * a reference naming a different DID can never collapse onto this document's.
- *
- * Malformed entries yield `undefined` rather than a placeholder string, so two
- * unusable values never compare equal to each other.
- *
- * @param {string} documentId The `id` of the DID document carrying the entry.
- * @param {unknown} entry The relationship entry: a reference or an embedded method.
- * @returns {string | undefined} The absolute DID URL, or undefined if unusable.
- */
-function relationshipMethodId(documentId: string, entry: unknown): string | undefined {
-  // An embedded method names itself with its `id`; a reference is the id itself.
-  const id = isRecord(entry) ? entry.id : entry;
-  if(typeof id !== 'string' || id.length === 0) return undefined;
-  return id.startsWith('#') ? `${documentId}${id}` : id;
-}
-
 /**
  * Different possible Resolver states representing phases in the resolution process.
  */
@@ -251,6 +225,7 @@ export class Resolver {
   /** Count of beacon-discovery passes driven by updates adding new beacon services. */
   #discoveryRounds = 0;
 
+
   /**
    * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
@@ -258,7 +233,12 @@ export class Resolver {
     didComponents: DidComponents,
     sidecarData: SidecarData,
     currentDocument: DidDocument | null,
-    options?: { versionId?: string; versionTime?: string; genesisDocument?: object; maxDiscoveryRounds?: number }
+    options?: {
+      versionId?: string;
+      versionTime?: string;
+      genesisDocument?: object;
+      maxDiscoveryRounds?: number;
+    }
   ) {
     this.#didComponents = didComponents;
     this.#sidecarData = sidecarData;
@@ -636,9 +616,9 @@ export class Resolver {
     // without it here the read path applies an update signed by any key in the document.
     // Checked before the method is located so an unauthorized method always fails with
     // this typed error, whether or not it also appears in verificationMethod[].
-    const authorizedMethodId = relationshipMethodId(currentDocument.id, verificationMethodId);
+    const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, currentDocument.id);
     const authorized = authorizedMethodId !== undefined && currentDocument.capabilityInvocation?.some(
-      entry => relationshipMethodId(currentDocument.id, entry) === authorizedMethodId
+      entry => Appendix.relationshipMethodId(entry, currentDocument.id) === authorizedMethodId
     );
     if(!authorized) {
       throw new ResolveError(
@@ -773,7 +753,9 @@ export class Resolver {
             if(this.#processedServices.has(service.id) || !signals.length) continue;
 
             // Establish a typed beacon and process its signals
-            const beacon = BeaconFactory.establish(service);
+            // The beacon is bound to the DID under resolution: a beacon service
+            // `id` may be a relative DID URL, so it cannot supply the subject.
+            const beacon = BeaconFactory.establish(service, this.#currentDocument!.id);
             const result = beacon.processSignals(signals, this.#sidecarData);
 
             if(result.needs.length > 0) {

package/src/core/updater.ts

@@ -58,8 +58,8 @@ export interface FundingProof {
  * The updater needs the caller to broadcast the signed update via the beacon.
  *
  * The caller decides how: for single-party beacons, call
- * `Updater.announce(beaconService, signedUpdate, signer, bitcoin, options?)` or
- * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
+ * `Updater.announce(beaconService, did, signedUpdate, signer, bitcoin, options?)` or
+ * `BeaconFactory.establish(beaconService, did).broadcastSignal(...)`. For multi-party
  * aggregate beacons, hand off to the aggregation protocol.
  *
  * Both single-party paths return a `BroadcastResult`; capture it. Beyond the txid,
@@ -76,6 +76,11 @@ export interface NeedBroadcast {
   readonly beaconService: BeaconService;
   /** The signed update ready for broadcast. */
   readonly signedUpdate: SignedBTCR2Update;
+  /**
+   * The DID being updated. Supplied because a beacon service `id` may be a
+   * relative DID URL and so cannot be used to recover the subject.
+   */
+  readonly did: string;
 }
 
 /** Discriminated union of all data needs the updater may request from the caller. */
@@ -148,7 +153,7 @@ export interface UpdaterParams {
  *         // Capture the BroadcastResult: broadcast.txid, plus broadcast.announcement
  *         // (CAS beacons) and broadcast.proof (SMT beacons; must be retained, the
  *         // proof's nonce exists nowhere else).
- *         const broadcast = await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
+ *         const broadcast = await Updater.announce(need.beaconService, need.did, need.signedUpdate, signer, bitcoin);
  *         updater.provide(need);
  *         break;
  *       }
@@ -278,6 +283,12 @@ export class Updater {
     const id = verificationMethod.id.slice(hashIdx);
     const multikey = SchnorrMultikey.fromSigner(id, controller, signer);
 
+    // The absolute spelling of the method id, for the proof to name it by. `hashIdx === 0`
+    // means the document writes this method's own id as a relative DID URL, which per DID
+    // Core denotes that fragment of the document's `id`: the same rule as
+    // Appendix.absoluteDidUrl, whose `undefined` case the fragment check above excludes.
+    const absoluteMethodId = hashIdx === 0 ? `${did}${id}` : verificationMethod.id;
+
     // Fail fast if the signer's public key is not the key published in the named
     // verification method. Signing with the wrong key yields a Data Integrity
     // proof that cannot verify against the method, so the resulting on-chain
@@ -308,7 +319,12 @@ export class Updater {
       ],
       cryptosuite        : 'bip340-jcs-2025',
       type               : 'DataIntegrityProof',
-      verificationMethod : verificationMethod.id,
+      // The proof names the signing method by absolute DID URL, even when the document
+      // spells that method's own id relatively: a proof travels apart from the document
+      // that defines the method, so a bare `#initialKey` in it resolves against nothing.
+      // For a document that already spells its ids absolutely this is the id unchanged,
+      // so proofs over such documents are byte-identical to before.
+      verificationMethod : absoluteMethodId,
       proofPurpose       : 'capabilityInvocation',
       capability         : `urn:zcap:root:${encodeURIComponent(did)}`,
       capabilityAction   : 'Write',
@@ -323,6 +339,8 @@ export class Updater {
    * Announces a signed update to the Bitcoin blockchain via the specified beacon.
    *
    * @param {BeaconService} beaconService The beacon service to broadcast through.
+   * @param {string} did The DID being updated. Required because a beacon service
+   *   `id` may be a relative DID URL and so cannot supply the subject.
    * @param {SignedBTCR2Update} update The signed update to announce.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
@@ -334,12 +352,13 @@ export class Updater {
    */
   static async announce(
     beaconService: BeaconService,
+    did: string,
     update: SignedBTCR2Update,
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
   ): Promise<BroadcastResult> {
-    const beacon = BeaconFactory.establish(beaconService);
+    const beacon = BeaconFactory.establish(beaconService, did);
     return beacon.broadcastSignal(update, signer, bitcoin, options);
   }
 
@@ -406,6 +425,7 @@ export class Updater {
               kind          : 'NeedBroadcast',
               beaconService : this.#beaconService,
               signedUpdate  : this.#state.signedUpdate,
+              did           : this.#sourceDocument.id,
             }],
           };
         }

package/src/did-btcr2.ts

@@ -171,8 +171,16 @@ export class DidBtcr2 implements DidMethod {
     verificationMethodId: string;
     beaconId: string;
   }): Updater {
-    // Validate that the verificationMethodId is authorized for capabilityInvocation
-    if(!sourceDocument.capabilityInvocation?.some(vr => vr === verificationMethodId)) {
+    // Validate that the verificationMethodId is authorized for capabilityInvocation.
+    // Both sides are resolved to absolute DID URLs first, so the caller's spelling of the
+    // reference and the document's spelling of the entry may differ: either is legal per
+    // DID Core. This is the same rule the read path applies to an update's proof, so an
+    // update this factory authorizes is one the resolver will also accept.
+    const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, sourceDocument.id);
+    const authorized = authorizedMethodId !== undefined && sourceDocument.capabilityInvocation?.some(
+      entry => Appendix.relationshipMethodId(entry, sourceDocument.id) === authorizedMethodId
+    );
+    if(!authorized) {
       throw new UpdateError(
         'Invalid verificationMethodId: not authorized for capabilityInvocation',
         INVALID_DID_DOCUMENT, sourceDocument
@@ -206,9 +214,14 @@ export class DidBtcr2 implements DidMethod {
       );
     }
 
-    // Find the beacon service matching the given beaconId
+    // Find the beacon service matching the given beaconId. A service `id` may be a relative
+    // DID URL, so both sides are resolved against the document before comparison; an
+    // unusable beaconId matches nothing rather than matching an unusable service id.
+    const targetBeaconId = Appendix.absoluteDidUrl(beaconId, sourceDocument.id);
     const beaconService = sourceDocument.service
-      .filter((service: BeaconService) => service.id === beaconId)
+      .filter((service: BeaconService) =>
+        targetBeaconId !== undefined
+        && Appendix.absoluteDidUrl(service.id, sourceDocument.id) === targetBeaconId)
       .filter((service: BeaconService): service is BeaconService => !!service)
       .shift();
 
@@ -250,10 +263,17 @@ export class DidBtcr2 implements DidMethod {
     }
 
     // Attempt to find a verification method that matches the given method ID, or if not given,
-    // find the first verification method intended for signing claims.
-    const verificationMethod = didDocument.verificationMethod?.find(
-      (vm: DidVerificationMethod) => Appendix.extractDidFragment(vm.id) === (Appendix.extractDidFragment(methodId)
-        ?? Appendix.extractDidFragment(didDocument.assertionMethod?.[0]))
+    // find the first verification method intended for signing claims. Both sides are resolved
+    // to absolute DID URLs first: a document may spell either the verification method `id` or
+    // the reference to it as a relative DID URL (`#initialKey`), and the two must still match.
+    const targetId = Appendix.absoluteDidUrl(methodId, didDocument.id)
+      ?? Appendix.relationshipMethodId(didDocument.assertionMethod?.[0], didDocument.id);
+
+    // An unusable target matches nothing: without this guard it compares equal to every
+    // method whose own id is unusable, and the document's first malformed method is
+    // returned as the signing method.
+    const verificationMethod = targetId === undefined ? undefined : didDocument.verificationMethod?.find(
+      (vm: DidVerificationMethod) => Appendix.absoluteDidUrl(vm.id, didDocument.id) === targetId
     );
 
     // If no verification method is found, throw an error

package/src/utils/appendix.ts

@@ -18,14 +18,46 @@ import type { RootCapability } from '../core/interfaces.js';
  */
 export class Appendix {
   /**
-   * Extracts a DID fragment from a given input
-   * @param {unknown} input The input to extract the DID fragment from
-   * @returns {string | undefined} The extracted DID fragment or undefined if not found
+   * Resolves a DID URL that may be written as a relative reference against the
+   * DID it appears under. DID Core permits the `id` of a verification method or
+   * service, and the entries of a verification relationship, to be a relative
+   * DID URL such as `#initialKey`; it denotes that fragment of `did`. Absolute
+   * DID URLs are returned unchanged, so both spellings of the same reference
+   * compare equal without discarding the DID being compared.
+   *
+   * @param {unknown} input The DID URL to resolve. Non-strings yield `undefined`.
+   * @param {string} did The DID the relative reference is resolved against.
+   * @returns {string | undefined} The absolute DID URL, or `undefined` if `input` is not a usable string.
    */
-  public static extractDidFragment(input: unknown): string | undefined {
+  public static absoluteDidUrl(input: unknown, did: string): string | undefined {
     if (typeof input !== 'string') return undefined;
     if (input.length === 0) return undefined;
-    return input;
+    return input.startsWith('#') ? `${did}${input}` : input;
+  }
+
+  /**
+   * Resolves a verification relationship entry to the absolute DID URL of the method it
+   * names. A relationship entry is either a reference to a method defined elsewhere in the
+   * document, or a method embedded inline, which names itself with its own `id`; either
+   * spelling may be a relative DID URL.
+   *
+   * Every comparison of a relationship entry against a method id goes through this helper,
+   * on both the read path and the write path, so the two admit exactly the same spellings.
+   *
+   * Malformed entries yield `undefined` rather than a placeholder string, so two unusable
+   * values never compare equal to each other. Callers comparing a resolved entry must still
+   * reject an `undefined` target before comparing, or an unusable target matches an
+   * unusable entry.
+   *
+   * @param {unknown} entry The relationship entry: a reference, or an embedded method.
+   * @param {string} did The DID the relative reference is resolved against.
+   * @returns {string | undefined} The absolute DID URL, or `undefined` if unusable.
+   */
+  public static relationshipMethodId(entry: unknown, did: string): string | undefined {
+    const id = (typeof entry === 'object' && entry !== null && !Array.isArray(entry))
+      ? (entry as { id?: unknown }).id
+      : entry;
+    return Appendix.absoluteDidUrl(id, did);
   }
 
   /**