@enbox/dids 0.0.4 → 0.0.6

package/src/methods/did-key.ts

@@ -1,39 +1,30 @@
+import type { PortableDid } from '../types/portable-did.js';
+import type { DidCreateOptions, DidCreateVerificationMethod } from './did-method.js';
+import type {
+  DidDocument,
+  DidResolutionOptions,
+  DidResolutionResult,
+  DidVerificationMethod,
+} from '../types/did-core.js';
 import type {
-  AsymmetricKeyConverter,
   InferKeyGeneratorAlgorithm,
-  Jwk,
-  KeyCompressor,
   KeyIdentifier,
   KeyImporterExporter,
   KeyManager,
   KmsExportKeyParams,
   KmsImportKeyParams,
 } from '@enbox/crypto';
-import type { MulticodecCode, MulticodecDefinition } from '@enbox/common';
 
-import {
-  Ed25519,
-  LocalKeyManager,
-  Secp256k1,
-  Secp256r1,
-} from '@enbox/crypto';
-import { Multicodec, universalTypeOf } from '@enbox/common';
-
-import type { PortableDid } from '../types/portable-did.js';
-import type { DidCreateOptions, DidCreateVerificationMethod } from './did-method.js';
-import type {
-  DidDocument,
-  DidResolutionOptions,
-  DidResolutionResult,
-  DidVerificationMethod,
-} from '../types/did-core.js';
+import { universalTypeOf } from '@enbox/common';
+import { Ed25519, LocalKeyManager, Secp256k1 } from '@enbox/crypto';
 
 import { BearerDid } from '../bearer-did.js';
 import { Did } from '../did.js';
+import { DidKeyUtils } from './did-key-utils.js';
 import { DidMethod } from './did-method.js';
 import { EMPTY_DID_RESOLUTION_RESULT } from '../types/did-resolution.js';
 import { DidError, DidErrorCode } from '../did-error.js';
-import { getVerificationMethodTypes, keyBytesToMultibaseId, multibaseIdToKeyBytes } from '../utils.js';
+import { getVerificationMethodTypes, multibaseIdToKeyBytes } from '../utils.js';
 
 /**
  * Defines the set of options available when creating a new Decentralized Identifier (DID) with the
@@ -165,19 +156,6 @@ export const DidKeyVerificationMethodType = {
   JsonWebKey2020: 'https://w3id.org/security/suites/jws-2020/v1',
 } as const;
 
-/**
- * Private helper that maps algorithm identifiers to their corresponding DID Key
- * {@link DidKeyRegisteredKeyType | registered key type}.
- */
-const AlgorithmToKeyTypeMap = {
-  Ed25519   : DidKeyRegisteredKeyType.Ed25519,
-  ES256K    : DidKeyRegisteredKeyType.secp256k1,
-  ES256     : DidKeyRegisteredKeyType.secp256r1,
-  'P-256'   : DidKeyRegisteredKeyType.secp256r1,
-  secp256k1 : DidKeyRegisteredKeyType.secp256k1,
-  secp256r1 : DidKeyRegisteredKeyType.secp256r1,
-} as const;
-
 /**
  * The `DidKey` class provides an implementation of the 'did:key' DID method.
  *
@@ -733,235 +711,5 @@ export class DidKey extends DidMethod {
   }
 }
 
-/**
- * The `DidKeyUtils` class provides utility functions to support operations in the DID Key method.
- */
-export class DidKeyUtils {
-  /**
-   * A mapping from JSON Web Key (JWK) property descriptors to multicodec names.
-   *
-   * This mapping is used to convert keys in JWK (JSON Web Key) format to multicodec format.
-   *
-   * @remarks
-   * The keys of this object are strings that describe the JOSE key type and usage,
-   * such as 'Ed25519:public', 'Ed25519:private', etc. The values are the corresponding multicodec
-   * names used to represent these key types.
-   *
-   * @example
-   * ```ts
-   * const multicodecName = JWK_TO_MULTICODEC['Ed25519:public'];
-   * // Returns 'ed25519-pub', the multicodec name for an Ed25519 public key
-   * ```
-   */
-  private static JWK_TO_MULTICODEC: { [key: string]: string } = {
-    'Ed25519:public'    : 'ed25519-pub',
-    'Ed25519:private'   : 'ed25519-priv',
-    'secp256k1:public'  : 'secp256k1-pub',
-    'secp256k1:private' : 'secp256k1-priv',
-  };
-
-  /**
-   * Defines the expected byte lengths for public keys associated with different cryptographic
-   * algorithms, indexed by their multicodec code values.
-   */
-  public static MULTICODEC_PUBLIC_KEY_LENGTH: Record<number, number> = {
-    // secp256k1-pub - Secp256k1 public key (compressed) - 33 bytes
-    0xe7: 33,
-
-    // ed25519-pub - Ed25519 public key - 32 bytes
-    0xed: 32
-  };
-
-  /**
-   * A mapping from multicodec names to their corresponding JOSE (JSON Object Signing and Encryption)
-   * representations. This mapping facilitates the conversion of multicodec key formats to
-   * JWK (JSON Web Key) formats.
-   *
-   * @remarks
-   * The keys of this object are multicodec names, such as 'ed25519-pub', 'ed25519-priv', etc.
-   * The values are objects representing the corresponding JWK properties for that key type.
-   *
-   * @example
-   * ```ts
-   * const joseKey = MULTICODEC_TO_JWK['ed25519-pub'];
-   * // Returns a partial JWK for an Ed25519 public key
-   * ```
-   */
-  private static MULTICODEC_TO_JWK: { [key: string]: Jwk } = {
-    'ed25519-pub'    : { crv: 'Ed25519', kty: 'OKP', x: '' },
-    'ed25519-priv'   : { crv: 'Ed25519', kty: 'OKP', x: '', d: '' },
-    'secp256k1-pub'  : { crv: 'secp256k1', kty: 'EC', x: '', y: '' },
-    'secp256k1-priv' : { crv: 'secp256k1', kty: 'EC', x: '', y: '', d: '' },
-  };
-
-  /**
-   * Converts a JWK (JSON Web Key) to a Multicodec code and name.
-   *
-   * @example
-   * ```ts
-   * const jwk: Jwk = { crv: 'Ed25519', kty: 'OKP', x: '...' };
-   * const { code, name } = await DidKeyUtils.jwkToMulticodec({ jwk });
-   * ```
-   *
-   * @param params - The parameters for the conversion.
-   * @param params.jwk - The JSON Web Key to be converted.
-   * @returns A promise that resolves to a Multicodec definition.
-   */
-  public static async jwkToMulticodec({ jwk }: {
-    jwk: Jwk
-  }): Promise<MulticodecDefinition<MulticodecCode>> {
-    const params: string[] = [];
-
-    if (jwk.crv) {
-      params.push(jwk.crv);
-      if (jwk.d) {
-        params.push('private');
-      } else {
-        params.push('public');
-      }
-    }
-
-    const lookupKey = params.join(':');
-    const name = DidKeyUtils.JWK_TO_MULTICODEC[lookupKey];
-
-    if (name === undefined) {
-      throw new Error(`Unsupported JWK to Multicodec conversion: '${lookupKey}'`);
-    }
-
-    const code = Multicodec.getCodeFromName({ name });
-
-    return { code, name };
-  }
-
-  /**
-   * Returns the appropriate public key compressor for the specified cryptographic curve.
-   *
-   * @param curve - The cryptographic curve to use for the key conversion.
-   * @returns A public key compressor for the specified curve.
-   */
-  public static keyCompressor(
-    curve: string
-  ): KeyCompressor['compressPublicKey'] {
-  // ): ({ publicKeyBytes }: { publicKeyBytes: Uint8Array }) => Promise<Uint8Array> {
-    const compressors = {
-      'P-256'     : Secp256r1.compressPublicKey,
-      'secp256k1' : Secp256k1.compressPublicKey
-    } as Record<string, KeyCompressor['compressPublicKey']>;
-
-    const compressor = compressors[curve];
-
-    if (!compressor) {throw new DidError(DidErrorCode.InvalidPublicKeyType, `Unsupported curve: ${curve}`);}
-
-    return compressor;
-  }
-
-  /**
-   * Returns the appropriate key converter for the specified cryptographic curve.
-   *
-   * @param curve - The cryptographic curve to use for the key conversion.
-   * @returns An `AsymmetricKeyConverter` for the specified curve.
-   */
-  public static keyConverter(curve: string): AsymmetricKeyConverter {
-    const converters: Record<string, AsymmetricKeyConverter> = {
-      'Ed25519'   : Ed25519,
-      'P-256'     : Secp256r1,
-      'secp256k1' : Secp256k1,
-    };
-
-    const converter = converters[curve];
-
-    if (!converter) {throw new DidError(DidErrorCode.InvalidPublicKeyType, `Unsupported curve: ${curve}`);}
-
-    return converter;
-  }
-
-  /**
-   * Converts a Multicodec code or name to parial JWK (JSON Web Key).
-   *
-   * @example
-   * ```ts
-   * const partialJwk = await DidKeyUtils.multicodecToJwk({ name: 'ed25519-pub' });
-   * ```
-   *
-   * @param params - The parameters for the conversion.
-   * @param params.code - Optional Multicodec code to convert.
-   * @param params.name - Optional Multicodec name to convert.
-   * @returns A promise that resolves to a JOSE format key.
-   */
-  public static async multicodecToJwk({ code, name }: {
-    code?: MulticodecCode,
-    name?: string
-  }): Promise<Jwk> {
-    // Either code or name must be specified, but not both.
-    if (!(name ? !code : code)) {
-      throw new Error(`Either 'name' or 'code' must be defined, but not both.`);
-    }
-
-    // If name is undefined, lookup by code.
-    name = (name === undefined ) ? Multicodec.getNameFromCode({ code: code! }) : name;
-
-    const lookupKey = name;
-    const jose = DidKeyUtils.MULTICODEC_TO_JWK[lookupKey];
-
-    if (jose === undefined) {
-      throw new Error(`Unsupported Multicodec to JWK conversion`);
-    }
-
-    return { ...jose };
-  }
-
-  /**
-   * Converts a public key in JWK (JSON Web Key) format to a multibase identifier.
-   *
-   * @remarks
-   * Note: All secp public keys are converted to compressed point encoding
-   *       before the multibase identifier is computed.
-   *
-   * Per {@link https://github.com/multiformats/multicodec/blob/master/table.csv | Multicodec table}:
-   *    Public keys for Elliptic Curve cryptography algorithms (e.g., secp256k1,
-   *    secp256k1r1, secp384r1, etc.) are always represented with compressed point
-   *    encoding (e.g., secp256k1-pub, p256-pub, p384-pub, etc.).
-   *
-   * Per {@link https://datatracker.ietf.org/doc/html/rfc8812#name-jose-and-cose-secp256k1-cur | RFC 8812}:
-   *    "As a compressed point encoding representation is not defined for JWK
-   *    elliptic curve points, the uncompressed point encoding defined there
-   *    MUST be used. The x and y values represented MUST both be exactly
-   *    256 bits, with any leading zeros preserved."
-   *
-   * @example
-   * ```ts
-   * const publicKey = { crv: 'Ed25519', kty: 'OKP', x: '...' };
-   * const multibaseId = await DidKeyUtils.publicKeyToMultibaseId({ publicKey });
-   * ```
-   *
-   * @param params - The parameters for the conversion.
-   * @param params.publicKey - The public key in JWK format.
-   * @returns A promise that resolves to the multibase identifier.
-   */
-  public static async publicKeyToMultibaseId({ publicKey }: {
-    publicKey: Jwk
-  }): Promise<string> {
-    if (!(publicKey?.crv && publicKey.crv in AlgorithmToKeyTypeMap)) {
-      throw new DidError(DidErrorCode.InvalidPublicKeyType, `Public key contains an unsupported key type: ${publicKey?.crv ?? 'undefined'}`);
-    }
-
-    // Convert the public key from JWK format to a byte array.
-    let publicKeyBytes = await DidKeyUtils.keyConverter(publicKey.crv).publicKeyToBytes({ publicKey });
-
-    // Compress the public key if it is an elliptic curve key.
-    if (/^(secp256k1|P-256|P-384|P-521)$/.test(publicKey.crv)) {
-      publicKeyBytes = await DidKeyUtils.keyCompressor(publicKey.crv)({ publicKeyBytes });
-    }
-
-    // Convert the JSON Web Key (JWK) parameters to a Multicodec name.
-    const { name: multicodecName } = await DidKeyUtils.jwkToMulticodec({ jwk: publicKey });
-
-    // Compute the multibase identifier based on the provided key.
-    const multibaseId = keyBytesToMultibaseId({
-      keyBytes: publicKeyBytes,
-      multicodecName
-    });
-
-    return multibaseId;
-  }
-}
+// Re-export DidKeyUtils from its dedicated module for backward compatibility.
+export { DidKeyUtils } from './did-key-utils.js';

package/src/utils.ts

@@ -19,38 +19,44 @@ import { DidError, DidErrorCode } from './did-error.js';
  * Represents a Decentralized Web Node (DWN) service in a DID Document.
  *
  * A DWN DID service is a specialized type of DID service with the `type` set to
- * `DecentralizedWebNode`. It includes specific properties `enc` and `sig` that are used to identify
- * the public keys that can be used to interact with the DID Subject. The values of these properties
- * are strings or arrays of strings containing one or more verification method `id` values present in
- * the same DID document. If the `enc` and/or `sig` properties are an array of strings, an entity
- * interacting with the DID subject is expected to use the verification methods in the order they
- * are listed.
+ * `DecentralizedWebNode`. Encryption and signing keys are resolved from the DID document's
+ * verification methods, not from the service entry.
+ *
+ * The `enc` and `sig` properties are optional legacy fields that may be present on existing
+ * DID documents for backward compatibility. When present, they contain verification method `id`
+ * values that hint at which keys to use for encryption and signing. New implementations should
+ * resolve keys from the DID document's verification methods by purpose (`keyAgreement` for
+ * encryption, `authentication`/`assertionMethod` for signing).
  *
  * @example
  * ```ts
  * const service: DwnDidService = {
  *   id: 'did:example:123#dwn',
  *   type: 'DecentralizedWebNode',
- *   serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *   enc: 'did:example:123#key-1',
- *   sig: 'did:example:123#key-2'
+ *   serviceEndpoint: 'https://enbox-dwn.fly.dev'
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | DIF Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  */
 export interface DwnDidService extends DidService {
   /**
+   * @deprecated Optional legacy field. Resolve encryption keys from the DID document's
+   * `keyAgreement` verification methods instead.
+   *
    * One or more verification method `id` values that can be used to encrypt information
    * intended for the DID subject.
    */
   enc?: string | string[];
 
   /**
+   * @deprecated Optional legacy field. Resolve signing keys from the DID document's
+   * `authentication` or `assertionMethod` verification methods instead.
+   *
    * One or more verification method `id` values that will be used by the DID subject to sign data
    * or by another entity to verify signatures created by the DID subject.
    */
-  sig: string | string[];
+  sig?: string | string[];
 }
 
 /**
@@ -368,9 +374,11 @@ export function isDidService(obj: unknown): obj is DidService {
 /**
  * Checks if a given object is a {@link DwnDidService}.
  *
- * A {@link DwnDidService} is defined as {@link DidService} object with a `type` of
- * "DecentralizedWebNode" and `enc` and `sig` properties, where both properties are either strings
- * or arrays of strings.
+ * A {@link DwnDidService} is defined as a {@link DidService} object with a `type` of
+ * `"DecentralizedWebNode"`. The `enc` and `sig` properties are optional — they may be present
+ * on existing DID documents for backward compatibility, but are not required per the DWN
+ * specification. Encryption and signing keys are resolved from the DID document's verification
+ * methods, not from the service entry.
  *
  * @example
  * ```ts
@@ -382,33 +390,25 @@ export function isDidService(obj: unknown): obj is DidService {
  *       type: 'JsonWebKey2020',
  *       controller: 'did:example:123',
  *       publicKeyJwk: { ... }
- *     },
- *     {
- *       id: 'did:example:123#key-2',
- *       type: 'JsonWebKey2020',
- *       controller: 'did:example:123',
- *       publicKeyJwk: { ... }
  *     }
  *   ],
  *   service: [
  *     {
  *       id: 'did:example:123#dwn',
  *       type: 'DecentralizedWebNode',
- *       serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *       enc: 'did:example:123#key-1',
- *       sig: 'did:example:123#key-2'
+ *       serviceEndpoint: 'https://enbox-dwn.fly.dev'
  *     }
  *   ]
  * };
  *
- * if (isDwnService(didDocument.service[0])) {
+ * if (isDwnDidService(didDocument.service[0])) {
  *   console.log('The object is a DwnDidService');
  * } else {
  *   console.log('The object is not a DwnDidService');
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  *
  * @param obj - The object to be checked.
  * @returns `true` if `obj` is a DwnDidService; otherwise, `false`.
@@ -420,13 +420,14 @@ export function isDwnDidService(obj: unknown): obj is DwnDidService {
   // Validate that the `type` property is `DecentralizedWebNode`.
   if (obj.type !== 'DecentralizedWebNode') {return false;}
 
-  // Validate that the given object has the `enc` and `sig` properties.
-  if (!('enc' in obj && 'sig' in obj)) {return false;}
-
-  // Validate that the `enc` and `sig` properties are either strings or arrays of strings.
+  // If `enc` or `sig` are present, validate they are strings or arrays of strings.
   const isStringOrStringArray = (prop: any): boolean =>
     typeof prop === 'string' || Array.isArray(prop) && prop.every(item => typeof item === 'string');
-  return (isStringOrStringArray(obj.enc)) && (isStringOrStringArray(obj.sig));
+
+  if ('enc' in obj && obj.enc !== undefined && !isStringOrStringArray(obj.enc)) {return false;}
+  if ('sig' in obj && obj.sig !== undefined && !isStringOrStringArray(obj.sig)) {return false;}
+
+  return true;
 }
 
 /**