Break out BearerDid/PortableDid and add DidRegistrationResult

Signed-off-by: Frank Hinek <[email protected]>

packages/dids/src/bearer-did.ts

@@ -0,0 +1,42 @@
+import type { CryptoApi, Signer } from '@web5/crypto';
+
+import type { DidMetadata } from './portable-did.js';
+import type { DidDocument } from './types/did-core.js';
+
+/**
+ * Represents a Decentralized Identifier (DID) along with its DID document, key manager, metadata,
+ * and convenience functions.
+ */
+export interface BearerDid {
+  /**
+   * The DID document associated with this DID.
+   */
+  didDocument: DidDocument;
+
+  /**
+   * Returns a {@link @web5/crypto#Signer} that can be used to sign messages, credentials, or
+   * arbitrary data.
+   *
+   * If given, the `keyUri` parameter is used to select a key from the verification methods present
+   * in the DID Document. If `keyUri` is not given, each DID method implementation will select a
+   * default verification method key from the DID Document.
+   *
+   * @param params - The parameters for the `getSigner` operation.
+   * @param params.keyUri - Key URI of the key that will be used for sign and verify operations. Optional.
+   * @returns An instantiated {@link Signer} that can be used to sign and verify data.
+   */
+  getSigner: (params?: { keyUri?: string }) => Promise<Signer>;
+
+  /**
+   * Key Management System (KMS) used to manage a DIDs keys and sign data.
+   *
+   * Each DID method requires at least one key be present in the provided `keyManager`.
+   */
+  keyManager: CryptoApi;
+
+  /** {@inheritDoc DidMetadata} */
+  metadata: DidMetadata;
+
+  /** {@inheritDoc Did#uri} */
+  uri: string;
+}

packages/dids/src/index.ts

@@ -1,5 +1,7 @@
 export * from './did.js';
 export * from './did-error.js';
+export * from './bearer-did.js';
+export * from './portable-did.js';
 
 export * from './methods/did-dht.js';
 export * from './methods/did-ion.js';

packages/dids/src/methods/did-ion.ts

@@ -9,21 +9,16 @@ import type {
 import { IonDid, IonRequest } from '@decentralized-identity/ion-sdk';
 import { LocalKeyManager, computeJwkThumbprint } from '@web5/crypto';
 
+import type { BearerDid } from '../bearer-did.js';
+import type { DidCreateOptions, DidCreateVerificationMethod } from '../methods/did-method.js';
+import type { DidMetadata, PortableDid, PortableDidVerificationMethod } from '../portable-did.js';
 import type {
   DidService,
   DidDocument,
   DidResolutionResult,
   DidResolutionOptions,
   DidVerificationMethod,
 } from '../types/did-core.js';
-import type {
-  BearerDid,
-  DidMetadata,
-  PortableDid,
-  DidCreateOptions,
-  DidCreateVerificationMethod,
-  PortableDidVerificationMethod,
-} from '../methods/did-method.js';
 
 import { Did } from '../did.js';
 import { DidMethod } from '../methods/did-method.js';
@@ -631,7 +626,7 @@ export class DidIon extends DidMethod {
 /**
  * The `DidIonUtils` class provides utility functions to support operations in the DID ION method.
  */
-class DidIonUtils {
+export class DidIonUtils {
   /**
    * Appends a specified path to a base URL, ensuring proper formatting of the resulting URL.
    *

packages/dids/src/methods/did-jwk.ts

@@ -11,7 +11,9 @@ import type {
 import { Convert } from '@web5/common';
 import { LocalKeyManager } from '@web5/crypto';
 
-import type { BearerDid, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js';
+import type { BearerDid } from '../bearer-did.js';
+import type { DidMetadata, PortableDid } from '../portable-did.js';
+import type { DidCreateOptions, DidCreateVerificationMethod } from './did-method.js';
 import type { DidDocument, DidResolutionOptions, DidResolutionResult, DidVerificationMethod } from '../types/did-core.js';
 
 import { Did } from '../did.js';

packages/dids/src/methods/did-key.ts

@@ -20,7 +20,9 @@ import {
   LocalKeyManager,
 } from '@web5/crypto';
 
-import type { BearerDid, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js';
+import type { BearerDid } from '../bearer-did.js';
+import type { DidMetadata, PortableDid } from '../portable-did.js';
+import type { DidCreateOptions, DidCreateVerificationMethod } from './did-method.js';
 import type { DidDocument, DidResolutionOptions, DidResolutionResult, DidVerificationMethod } from '../types/did-core.js';
 
 import { Did } from '../did.js';

packages/dids/src/methods/did-method.ts

@@ -8,6 +8,8 @@ import type {
   InferKeyGeneratorAlgorithm,
 } from '@web5/crypto';
 
+import type { BearerDid } from '../bearer-did.js';
+import type { DidMetadata, PortableDid } from '../portable-did.js';
 import type {
   DidDocument,
   DidResolutionResult,
@@ -16,46 +18,8 @@ import type {
 } from '../types/did-core.js';
 
 import { getVerificationMethodByKey } from '../utils.js';
-import { DidVerificationRelationship } from '../types/did-core.js';
 import { DidError, DidErrorCode } from '../did-error.js';
-
-/**
- * Represents a Decentralized Identifier (DID) along with its DID document, key manager, metadata,
- * and convenience functions.
- */
-export interface BearerDid {
-  /**
-   * The DID document associated with this DID.
-   */
-  didDocument: DidDocument;
-
-  /**
-   * Returns a {@link @web5/crypto#Signer} that can be used to sign messages, credentials, or
-   * arbitrary data.
-   *
-   * If given, the `keyUri` parameter is used to select a key from the verification methods present
-   * in the DID Document. If `keyUri` is not given, each DID method implementation will select a
-   * default verification method key from the DID Document.
-   *
-   * @param params - The parameters for the `getSigner` operation.
-   * @param params.keyUri - Key URI of the key that will be used for sign and verify operations. Optional.
-   * @returns An instantiated {@link Signer} that can be used to sign and verify data.
-   */
-  getSigner: (params?: { keyUri?: string }) => Promise<Signer>;
-
-  /**
-   * Key Management System (KMS) used to manage a DIDs keys and sign data.
-   *
-   * Each DID method requires at least one key be present in the provided `keyManager`.
-   */
-  keyManager: CryptoApi;
-
-  /** {@inheritDoc DidMetadata} */
-  metadata: DidMetadata;
-
-  /** {@inheritDoc Did#uri} */
-  uri: string;
-}
+import { DidVerificationRelationship } from '../types/did-core.js';
 
 /**
  * Represents options during the creation of a Decentralized Identifier (DID).
@@ -116,14 +80,6 @@ export interface DidCreateVerificationMethod<TKms> extends Pick<Partial<DidVerif
   purposes?: (DidVerificationRelationship | keyof typeof DidVerificationRelationship)[];
 }
 
-/**
- * Represents metadata about a DID resulting from create, update, or deactivate operations.
- */
-export type DidMetadata = {
-  // Additional properties of any type.
-  [key: string]: any;
-}
-
 /**
  * Defines the API for a specific DID method. It includes functionalities for creating and resolving
  * DIDs.
@@ -191,92 +147,76 @@ export interface DidMethodResolver {
 }
 
 /**
- * Format to document a DID identifier, along with its associated data, which can be exported,
- * saved to a file, or imported. The intent is bundle all of the necessary metadata to enable usage
- * of the DID in different contexts.
- */
-/**
- * Format that documents the key material and metadata of a Decentralized Identifier (DID) to enable
- * usage of the DID in different contexts.
- *
- * This format is useful for exporting, saving to a file, or importing a DID across process
- * boundaries or between different DID method implementations.
- *
- * @example
- * ```ts
- * // Generate a new DID.
- * const did = await DidExample.create();
+ * Represents the result of a Decentralized Identifier (DID) registration operation.
  *
- * // Export the DID to a PortableDid.
- * const portableDid = await DidExample.toKeys({ did });
- *
- * // Instantiate a BearerDid object from a PortableDid.
- * const didFromKeys = await DidExample.fromKeys({ ...portableDid });
- * // The `didFromKeys` object should be equivalent to the original `did` object.
- * ```
+ * This type encapsulates the complete outcome of registering a DID, including the registration
+ * metadata, the DID document (if registration is successful), and metadata about the DID document.
  */
-export interface PortableDid {
-  /** {@inheritDoc Did#uri} */
-  uri?: string;
-
+export interface DidRegistrationResult {
   /**
-   * An array of verification methods, including the key material and key purpose, which are
-   * included in the DID document.
+   * The DID document resulting from the registration process, if successful.
    *
-   * @see {@link https://www.w3.org/TR/did-core/#verification-methods | DID Core Specification, § Verification Methods}
+   * If the registration operation was successful, this MUST contain a DID document
+   * corresponding to the DID. If the registration is unsuccessful, this value MUST be empty.
+   *
+   * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocument | DID Core Specification, § DID Document}
    */
-  verificationMethods: PortableDidVerificationMethod[];
-}
+  didDocument: DidDocument | null;
 
-/**
- * Represents a verification method within a {@link PortableDid}, including the private key and
- * the purposes for which the verification method can be used.
- *
- * This interface extends {@link DidVerificationMethod}, providing a structure to document the key
- * material and metadata associated with a DID's verification methods.
- */
-export interface PortableDidVerificationMethod extends Partial<DidVerificationMethod> {
   /**
-   * Express the private key in JWK format.
+   * Metadata about the DID Document.
+   *
+   * This structure contains information about the DID Document like creation and update timestamps,
+   * deactivation status, versioning information, and other details relevant to the DID Document.
    *
-   * (Optional) A JSON Web Key that conforms to {@link https://datatracker.ietf.org/doc/html/rfc7517 | RFC 7517}.
+   * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocumentmetadata | DID Core Specification, § DID Document Metadata}
    */
-  privateKeyJwk?: Jwk;
+  didDocumentMetadata: DidMetadata;
 
   /**
-   * Optionally specify the purposes for which a verification method is intended to be used in a DID
-   * document.
-   *
-   * The `purposes` property defines the specific
-   * {@link DidVerificationRelationship | verification relationships} between the DID subject and
-   * the verification method. This enables the verification method to be utilized for distinct
-   * actions such as authentication, assertion, key agreement, capability delegation, and others. It
-   * is important for verifiers to recognize that a verification method must be associated with the
-   * relevant purpose in the DID document to be valid for that specific use case.
+   * A metadata structure consisting of values relating to the results of the DID registration
+   * process.
    *
-   * @example
-   * ```ts
-   * const verificationMethod: PortableDidVerificationMethod = {
-   *   publicKeyJwk: {
-   *     kty: "OKP",
-   *     crv: "X25519",
-   *     x: "7XdJtNmJ9pV_O_3mxWdn6YjiHJ-HhNkdYQARzVU_mwY",
-   *     kid: "xtsuKULPh6VN9fuJMRwj66cDfQyLaxuXHkMlmAe_v6I"
-   *   },
-   *   privateKeyJwk: {
-   *     kty: "OKP",
-   *     crv: "X25519",
-   *     d: "qM1E646TMZwFcLwRAFwOAYnTT_AvbBd3NBGtGRKTyU8",
-   *     x: "7XdJtNmJ9pV_O_3mxWdn6YjiHJ-HhNkdYQARzVU_mwY",
-   *     kid: "xtsuKULPh6VN9fuJMRwj66cDfQyLaxuXHkMlmAe_v6I"
-   *   },
-   *   purposes: ['authentication', 'assertionMethod']
-   * };
-   * ```
+   * This structure is REQUIRED, and in the case of an error in the registration process,
+   * this MUST NOT be empty. If the registration is not successful, this structure MUST contain an
+   * `error` property describing the error.
    */
-  purposes?: (DidVerificationRelationship | keyof typeof DidVerificationRelationship)[];
+  didRegistrationMetadata: DidRegistrationMetadata;
 }
 
+/**
+ * Represents metadata related to the result of a DID registration operation.
+ *
+ * This type includes fields that provide information about the outcome of a DID registration
+ * process (e.g., create, update, deactivate), including any errors that occurred.
+ *
+ * This metadata typically changes between invocations of the `create`, `update`, and `deactivate`
+ * functions, as it represents data about the registration process itself.
+ */
+export type DidRegistrationMetadata = {
+  /**
+   * An error code indicating issues encountered during the DID registration process.
+   *
+   * While the DID Core specification does not define a specific set of error codes for the result
+   * returned by the `create`, `update`, or `deactivate` functions, it is recommended to use the
+   * error codes defined in the DID Specification Registries for
+   * {@link https://www.w3.org/TR/did-spec-registries/#error | DID Resolution Metadata }.
+   *
+   * Recommended error codes include:
+   *   - `internalError`: An unexpected error occurred during DID registration process.
+   *   - `invalidDid`: The provided DID is invalid.
+   *   - `invalidDidDocument`: The provided DID document does not conform to valid syntax.
+   *   - `invalidDidDocumentLength`: The byte length of the provided DID document does not match the expected value.
+   *   - `invalidSignature`: Verification of a signature failed.
+   *   - `methodNotSupported`: The DID method specified is not supported.
+   *   - Custom error codes can also be provided as strings.
+   */
+  error?: string;
+
+  // Additional output metadata generated during DID registration.
+  [key: string]: any;
+};
+
 /**
  * Base abstraction for all Decentralized Identifier (DID) method implementations.
  *