@enbox/dids 0.0.1

package/dist/types/types/portable-did.d.ts

@@ -0,0 +1,59 @@
+import type { Jwk } from '@enbox/crypto';
+import type { DidDocument, DidDocumentMetadata } from './did-core.js';
+/**
+ * Represents metadata about a DID resulting from create, update, or deactivate operations.
+ */
+export interface DidMetadata extends DidDocumentMetadata {
+    /**
+     * For DID methods that support publishing, the `published` property indicates whether the DID
+     * document has been published to the respective network.
+     *
+     * A `true` value signifies that the DID document is publicly accessible on the network (e.g.,
+     * Mainline DHT), allowing it to be resolved by others. A `false` value implies the DID document
+     * is not published, limiting its visibility to public resolution.  Absence of this property
+     * indicates that the DID method does not support publishing.
+     */
+    published?: boolean;
+}
+/**
+ * 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();
+ *
+ * // Export to a PortableDid.
+ * const portableDid = await did.export();
+ *
+ * // Instantiate a BearerDid object from a PortableDid.
+ * const importedDid = await DidExample.import(portableDid);
+ * // The `importedDid` object should be equivalent to the original `did` object.
+ * ```
+ */
+export interface PortableDid {
+    /** {@inheritDoc Did#uri} */
+    uri: string;
+    /**
+     * The DID document associated with this DID.
+     *
+     * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocument | DID Core Specification, § DID Document}
+     */
+    document: DidDocument;
+    /** {@inheritDoc DidMetadata} */
+    metadata: DidMetadata;
+    /**
+     * An optional array of private keys associated with the DID document's verification methods.
+     */
+    privateKeys?: Jwk[];
+}
+//# sourceMappingURL=portable-did.d.ts.map

package/dist/types/types/portable-did.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-did.d.ts","sourceRoot":"","sources":["../../../src/types/portable-did.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,mBAAmB;IACtD;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,QAAQ,EAAE,WAAW,CAAC;IAEtB,gCAAgC;IAChC,QAAQ,EAAE,WAAW,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;CACrB"}

package/dist/types/utils.d.ts

@@ -0,0 +1,378 @@
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}