@enbox/dids/dist/types/methods/did-method.d.ts

TBD DIDs library

import type { CryptoApi, LocalKeyManager, InferKeyGeneratorAlgorithm } from '@enbox/crypto';
import type { BearerDid } from '../bearer-did.js';
import type { DidMetadata } from '../types/portable-did.js';
import type { DidDocument, DidResolutionResult, DidResolutionOptions, DidVerificationMethod } from '../types/did-core.js';
import { DidVerificationRelationship } from '../types/did-core.js';
/**
 * Represents options during the creation of a Decentralized Identifier (DID).
 *
 * Implementations of this interface may contain properties and methods that provide specific
 * options or metadata during the DID creation processes following specific DID method
 * specifications.
 */
export interface DidCreateOptions<TKms> {
    /**
     * Optional. An array of verification methods to be included in the DID document.
     */
    verificationMethods?: DidCreateVerificationMethod<TKms>[];
}
/**
 * Options for additional verification methods added to the DID Document during the creation of a
 * new Decentralized Identifier (DID).
 */
export interface DidCreateVerificationMethod<TKms> extends Pick<Partial<DidVerificationMethod>, 'controller' | 'id' | 'type'> {
    /**
     * The name of the cryptographic algorithm to be used for key generation.
     *
     * Examples might include `Ed25519` and `ES256K` but will vary depending on the DID method
     * specification and the key management system in use.
     *
     * @example
     * ```ts
     * const verificationMethod: DidCreateVerificationMethod = {
     *   algorithm: 'Ed25519'
     * };
     * ```
     */
    algorithm: TKms extends CryptoApi ? InferKeyGeneratorAlgorithm<TKms> : InferKeyGeneratorAlgorithm<LocalKeyManager>;
    /**
     * 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.
     *
     * @example
     * ```ts
     * const verificationMethod: DidCreateVerificationMethod = {
     *   algorithm: 'Ed25519',
     *   controller: 'did:example:1234',
     *   purposes: ['authentication', 'assertionMethod']
     * };
     * ```
     */
    purposes?: (DidVerificationRelationship | keyof typeof DidVerificationRelationship)[];
}
/**
 * Defines the API for a specific DID method. It includes functionalities for creating and resolving
 * DIDs.
 *
 * @typeparam T - The type of the DID instance associated with this method.
 * @typeparam O - The type of the options used for creating the DID.
 */
export interface DidMethodApi<TKms extends CryptoApi | undefined = CryptoApi, TDid extends BearerDid = BearerDid, TOptions extends DidCreateOptions<TKms> = DidCreateOptions<TKms>> extends DidMethodResolver {
    /**
     * The name of the DID method.
     *
     * For example, in the DID `did:example:123456`, "example" would be the method name.
     */
    methodName: string;
    new (): DidMethod;
    /**
     * Creates a new DID.
     *
     * This function should generate a new DID in accordance with the DID method specification being
     * implemented, using the provided `keyManager`, and optionally, any provided `options`.
     *
     * @param params - The parameters used to create the DID.
     * @param params.keyManager - Optional. The cryptographic API used for key management.
     * @param params.options - Optional. The options used for creating the DID.
     * @returns A promise that resolves to the newly created DID instance.
     */
    create(params: {
        keyManager?: TKms;
        options?: TOptions;
    }): Promise<TDid>;
    /**
     * Given a DID Document, return the verification method that will be used for signing messages and
     * credentials.
     *
     * If given, the `methodId` parameter is used to select the verification method. If not given, a
     * DID method specific approach is taken to selecting the verification method to return.
     *
     * @param params - The parameters for the `getSigningMethod` operation.
     * @param params.didDocument - DID Document to get the verification method from.
     * @param params.methodId - ID of the verification method to use for signing.
     * @returns A promise that resolves to the erification method to use for signing.
     */
    getSigningMethod(params: {
        didDocument: DidDocument;
        methodId?: string;
    }): Promise<DidVerificationMethod>;
}
/**
 * Defines the interface for resolving a DID using a specific DID method.
 *
 * A DID resolver takes a DID URI as input and returns a {@link DidResolutionResult} object.
 *
 * @property {string} methodName - The name of the DID method.
 * @method resolve - Asynchronous method to resolve a DID URI. Takes the DID URI and optional resolution options.
 */
export interface DidMethodResolver {
    /**
     * The name of the DID method.
     *
     * For example, in the DID `did:example:123456`, "example" would be the method name.
     */
    methodName: string;
    new (): DidMethod;
    /**
     * Resolves a DID URI.
     *
     * This function should resolve the DID URI in accordance with the DID method specification being
     * implemented, using the provided `options`.
     *
     * @param didUri - The DID URI to be resolved.
     * @param options - Optional. The options used for resolving the DID.
     * @returns A {@link DidResolutionResult} object containing the DID document and metadata or an error.
     */
    resolve(didUri: string, options?: DidResolutionOptions): Promise<DidResolutionResult>;
}
/**
 * Represents the result of a Decentralized Identifier (DID) registration operation.
 *
 * 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 DidRegistrationResult {
    /**
     * The DID document resulting from the registration process, if successful.
     *
     * 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}
     */
    didDocument: DidDocument | null;
    /**
     * 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.
     *
     * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocumentmetadata | DID Core Specification, § DID Document Metadata}
     */
    didDocumentMetadata: DidMetadata;
    /**
     * A metadata structure consisting of values relating to the results of the DID registration
     * process.
     *
     * 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.
     */
    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;
    [key: string]: any;
};
/**
 * Base abstraction for all Decentralized Identifier (DID) method implementations.
 *
 * This base class serves as a foundational structure upon which specific DID methods
 * can be implemented. Subclasses should furnish particular method and data models adherent
 * to various DID methods, taking care to adhere to the
 * {@link https://www.w3.org/TR/did-core/ | W3C DID Core specification} and the
 * respective DID method specifications.
 */
export declare class DidMethod {
    /**
     * MUST be implemented by all DID method implementations that extend {@link DidMethod}.
     *
     * Given the W3C DID Document of a DID, return the verification method that will be used for
     * signing messages and credentials. If given, the `methodId` parameter is used to select the
     * verification method. If not given, each DID method implementation will select a default
     * verification method from the DID Document.
     *
     * @param _params - The parameters for the `getSigningMethod` operation.
     * @param _params.didDocument - DID Document to get the verification method from.
     * @param _params.methodId - ID of the verification method to use for signing.
     * @returns Verification method to use for signing.
     */
    static getSigningMethod(_params: {
        didDocument: DidDocument;
        methodId?: string;
    }): Promise<DidVerificationMethod | undefined>;
    /**
     * MUST be implemented by all DID method implementations that extend {@link DidMethod}.
     *
     * Resolves a DID URI to a DID Document.
     *
     * @param _didUri - The DID to be resolved.
     * @param _options - Optional parameters for resolving the DID.
     * @returns A Promise resolving to a {@link DidResolutionResult} object representing the result of the resolution.
     */
    static resolve(_didUri: string, _options?: DidResolutionOptions): Promise<DidResolutionResult>;
}
//# sourceMappingURL=did-method.d.ts.map