@enbox/dids
Version:
TBD DIDs library
378 lines • 15.9 kB
TypeScript
import type { Jwk } from '@enbox/crypto';
import type { RequireOnly } from '@enbox/common';
import type { KeyWithMulticodec } from './types/multibase.js';
import { DidService, DidDocument, DidVerificationMethod, DidVerificationRelationship } from './types/did-core.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.
*
* @example
* ```ts
* const service: DwnDidService = {
* id: 'did:example:123#dwn',
* type: 'DecentralizedWebNode',
* serviceEndpoint: 'https://enbox-production.up.railway.app',
* enc: 'did:example:123#key-1',
* sig: 'did:example:123#key-2'
* }
* ```
*
* @see {@link https://identity.foundation/decentralized-web-node/spec/ | DIF Decentralized Web Node (DWN) Specification}
*/
export interface DwnDidService extends DidService {
/**
* One or more verification method `id` values that can be used to encrypt information
* intended for the DID subject.
*/
enc?: string | string[];
/**
* 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[];
}
/**
* Extracts the fragment part of a Decentralized Identifier (DID) verification method identifier.
*
* This function takes any input and aims to return only the fragment of a DID identifier,
* which comes after the '#' symbol in a DID string. It's designed specifically for handling
* DID verification method identifiers. The function returns undefined for non-string inputs, inputs
* that do not contain a '#', or complex data structures like objects or arrays, ensuring that only
* the fragment part of a DID string is extracted when present.
*
* @example
* ```ts
* console.log(extractDidFragment("did:example:123#key-1")); // Output: "key-1"
* console.log(extractDidFragment("did:example:123")); // Output: undefined
* console.log(extractDidFragment({ id: "did:example:123#0", type: "JsonWebKey" })); // Output: undefined
* console.log(extractDidFragment(undefined)); // Output: undefined
* ```
*
* @param input - The input to be processed. Can be of any type, but the function is designed
* to work with strings that represent DID verification method identifiers.
* @returns The fragment part of the DID identifier if the input is a string containing a '#'.
* Returns an empty string for all other inputs, including non-string types, strings
* without a '#', and complex data structures.
*/
export declare function extractDidFragment(input: unknown): string | undefined;
/**
* Retrieves services from a given DID document, optionally filtered by `id` or `type`.
*
* If no `id` or `type` filters are provided, all defined services are returned.
*
* The given DID Document must adhere to the
* {@link https://www.w3.org/TR/did-core/ | W3C DID Core Specification}.
*
* @example
* ```ts
* const didDocument = { ... }; // W3C DID document
* const services = getServices({ didDocument, type: 'DecentralizedWebNode' });
* ```
*
* @param params - An object containing input parameters for retrieving services.
* @param params.didDocument - The DID document from which services are retrieved.
* @param params.id - Optional. A string representing the specific service ID to match. If provided, only the service with this ID will be returned.
* @param params.type - Optional. A string representing the specific service type to match. If provided, only the service(s) of this type will be returned.
* @returns An array of services. If no matching service is found, an empty array is returned.
*/
export declare function getServices({ didDocument, id, type }: {
didDocument: DidDocument;
id?: string;
type?: string;
}): DidService[];
/**
* Retrieves a verification method object from a DID document if there is a match for the given
* public key.
*
* This function searches the verification methods in a given DID document for a match with the
* provided public key (either in JWK or multibase format). If a matching verification method is
* found it is returned. If no match is found `null` is returned.
*
*
* @example
* ```ts
* const didDocument = {
* // ... contents of a DID document ...
* };
* const publicKeyJwk = { kty: 'OKP', crv: 'Ed25519', x: '...' };
*
* const verificationMethod = await getVerificationMethodByKey({
* didDocument,
* publicKeyJwk
* });
* ```
*
* @param params - An object containing input parameters for retrieving the verification method ID.
* @param params.didDocument - The DID document to search for the verification method.
* @param params.publicKeyJwk - The public key in JSON Web Key (JWK) format to match against the verification methods in the DID document.
* @param params.publicKeyMultibase - The public key as a multibase encoded string to match against the verification methods in the DID document.
* @returns A promise that resolves with the matching verification method, or `null` if no match is found.
* @throws Throws an `Error` if the `didDocument` parameter is missing or if the `didDocument` does not contain any verification methods.
*/
export declare function getVerificationMethodByKey({ didDocument, publicKeyJwk, publicKeyMultibase }: {
didDocument: DidDocument;
publicKeyJwk?: Jwk;
publicKeyMultibase?: string;
}): Promise<DidVerificationMethod | null>;
/**
* Retrieves all verification methods from a given DID document, including embedded methods.
*
* This function consolidates all verification methods into a single array for easy access and
* processing. It checks both the primary `verificationMethod` array and the individual verification
* relationship properties `authentication`, `assertionMethod`, `keyAgreement`,
* `capabilityInvocation`, and `capabilityDelegation` for embedded methods.
*
* The given DID Document must adhere to the
* {@link https://www.w3.org/TR/did-core/ | W3C DID Core Specification}.
*
* @example
* ```ts
* const didDocument = { ... }; // W3C DID document
* const verificationMethods = getVerificationMethods({ didDocument });
* ```
*
* @param params - An object containing input parameters for retrieving verification methods.
* @param params.didDocument - The DID document from which verification methods are retrieved.
* @returns An array of `DidVerificationMethod`. If no verification methods are found, an empty array is returned.
* @throws Throws an `TypeError` if the `didDocument` parameter is missing.
*/
export declare function getVerificationMethods({ didDocument }: {
didDocument: DidDocument;
}): DidVerificationMethod[];
/**
* Retrieves all DID verification method types from a given DID document.
*
* The given DID Document must adhere to the
* {@link https://www.w3.org/TR/did-core/ | W3C DID Core Specification}.
*
* @example
* ```ts
* const didDocument = {
* verificationMethod: [
* {
* 'id' : 'did:example:123#key-0',
* 'type' : 'Ed25519VerificationKey2018',
* 'controller' : 'did:example:123',
* 'publicKeyBase58' : '3M5RCDjPTWPkKSN3sxUmmMqHbmRPegYP1tjcKyrDbt9J'
* },
* {
* 'id' : 'did:example:123#key-1',
* 'type' : 'X25519KeyAgreementKey2019',
* 'controller' : 'did:example:123',
* 'publicKeyBase58' : 'FbQWLPRhTH95MCkQUeFYdiSoQt8zMwetqfWoxqPgaq7x'
* },
* {
* 'id' : 'did:example:123#key-3',
* 'type' : 'JsonWebKey2020',
* 'controller' : 'did:example:123',
* 'publicKeyJwk' : {
* 'kty' : 'EC',
* 'crv' : 'P-256',
* 'x' : 'Er6KSSnAjI70ObRWhlaMgqyIOQYrDJTE94ej5hybQ2M',
* 'y' : 'pPVzCOTJwgikPjuUE6UebfZySqEJ0ZtsWFpj7YSPGEk'
* }
* }
* ]
* },
* const vmTypes = getVerificationMethodTypes({ didDocument });
* console.log(vmTypes);
* // Output: ['Ed25519VerificationKey2018', 'X25519KeyAgreementKey2019', 'JsonWebKey2020']
* ```
*
* @param params - An object containing input parameters for retrieving types.
* @param params.didDocument - The DID document from which types are retrieved.
* @returns An array of types. If no types were found, an empty array is returned.
*/
export declare function getVerificationMethodTypes({ didDocument }: {
didDocument: DidDocument;
}): string[];
/**
* Retrieves a list of DID verification relationships by a specific method ID from a DID document.
*
* This function examines the specified DID document to identify any verification relationships
* (e.g., `authentication`, `assertionMethod`) that reference a verification method by its method ID
* or contain an embedded verification method matching the method ID. The method ID is typically a
* fragment of a DID (e.g., `did:example:123#key-1`) that uniquely identifies a verification method
* within the DID document.
*
* The search considers both direct references to verification methods by their IDs and verification
* methods embedded within the verification relationship arrays. It returns an array of
* `DidVerificationRelationship` enums corresponding to the verification relationships that contain
* the specified method ID.
*
* @param params - An object containing input parameters for retrieving verification relationships.
* @param params.didDocument - The DID document to search for verification relationships.
* @param params.methodId - The method ID to search for within the verification relationships.
* @returns An array of `DidVerificationRelationship` enums representing the types of verification
* relationships that reference the specified method ID.
*
* @example
* ```ts
* const didDocument: DidDocument = {
* // ...contents of a DID document...
* };
*
* const relationships = getVerificationRelationshipsById({
* didDocument,
* methodId: 'key-1'
* });
* console.log(relationships);
* // Output might include ['authentication', 'assertionMethod'] if those relationships
* // reference or contain the specified method ID.
* ```
*/
export declare function getVerificationRelationshipsById({ didDocument, methodId }: {
didDocument: DidDocument;
methodId: string;
}): DidVerificationRelationship[];
/**
* Checks if a given object is a {@link DidService}.
*
* A {@link DidService} in the context of DID resources must include the properties `id`, `type`,
* and `serviceEndpoint`. The `serviceEndpoint` can be a `DidServiceEndpoint` or an array of
* `DidServiceEndpoint` objects.
*
* @example
* ```ts
* const service = {
* id: "did:example:123#service-1",
* type: "OidcService",
* serviceEndpoint: "https://example.com/oidc"
* };
*
* if (isDidService(service)) {
* console.log('The object is a DidService');
* } else {
* console.log('The object is not a DidService');
* }
* ```
*
* @param obj - The object to be checked.
* @returns `true` if `obj` is a `DidService`; otherwise, `false`.
*/
export declare 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.
*
* @example
* ```ts
* const didDocument: DidDocument = {
* id: 'did:example:123',
* verificationMethod: [
* {
* id: 'did:example:123#key-1',
* 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-production.up.railway.app',
* enc: 'did:example:123#key-1',
* sig: 'did:example:123#key-2'
* }
* ]
* };
*
* if (isDwnService(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}
*
* @param obj - The object to be checked.
* @returns `true` if `obj` is a DwnDidService; otherwise, `false`.
*/
export declare function isDwnDidService(obj: unknown): obj is DwnDidService;
/**
* Checks if a given object is a DID Verification Method.
*
* A {@link DidVerificationMethod} in the context of DID resources must include the properties `id`,
* `type`, and `controller`.
*
* @example
* ```ts
* const resource = {
* id : "did:example:123#0",
* type : "JsonWebKey2020",
* controller : "did:example:123",
* publicKeyJwk : { ... }
* };
*
* if (isDidVerificationMethod(resource)) {
* console.log('The resource is a DidVerificationMethod');
* } else {
* console.log('The resource is not a DidVerificationMethod');
* }
* ```
*
* @param obj - The object to be checked.
* @returns `true` if `obj` is a `DidVerificationMethod`; otherwise, `false`.
*/
export declare function isDidVerificationMethod(obj: unknown): obj is DidVerificationMethod;
/**
* Converts a cryptographic key to a multibase identifier.
*
* @remarks
* This method provides a way to represent a cryptographic key as a multibase identifier.
* It takes a `Uint8Array` representing the key, and either the multicodec code or multicodec name
* as input. The method first adds the multicodec prefix to the key, then encodes it into Base58
* format. Finally, it converts the Base58 encoded key into a multibase identifier.
*
* @example
* ```ts
* const key = new Uint8Array([...]); // Cryptographic key as Uint8Array
* const multibaseId = keyBytesToMultibaseId({ key, multicodecName: 'ed25519-pub' });
* ```
*
* @param params - The parameters for the conversion.
* @returns The multibase identifier as a string.
*/
export declare function keyBytesToMultibaseId({ keyBytes, multicodecCode, multicodecName }: RequireOnly<KeyWithMulticodec, 'keyBytes'>): string;
/**
* Converts a multibase identifier to a cryptographic key.
*
* @remarks
* This function decodes a multibase identifier back into a cryptographic key. It first decodes the
* identifier from multibase format into Base58 format, and then converts it into a `Uint8Array`.
* Afterward, it removes the multicodec prefix, extracting the raw key data along with the
* multicodec code and name.
*
* @example
* ```ts
* const multibaseKeyId = '...'; // Multibase identifier of the key
* const { key, multicodecCode, multicodecName } = multibaseIdToKey({ multibaseKeyId });
* ```
*
* @param params - The parameters for the conversion.
* @param params.multibaseKeyId - The multibase identifier string of the key.
* @returns An object containing the key as a `Uint8Array` and its multicodec code and name.
* @throws `DidError` if the multibase identifier is invalid.
*/
export declare function multibaseIdToKeyBytes({ multibaseKeyId }: {
multibaseKeyId: string;
}): Required<KeyWithMulticodec>;
//# sourceMappingURL=utils.d.ts.map