@enbox/dids 0.0.4 → 0.0.5

package/dist/types/methods/did-dht-pkarr.d.ts

@@ -0,0 +1,56 @@
+import type { Packet } from '@dnsquery/dns-packet';
+import type { Signer } from '@enbox/crypto';
+import type { Bep44Message } from './did-dht-types.js';
+/**
+ * Retrieves a signed BEP44 message from a DID DHT Gateway or Pkarr Relay server.
+ *
+ * @see {@link https://github.com/Nuhvi/pkarr/blob/main/design/relays.md | Pkarr Relay design}
+ *
+ * @param params - The parameters for the get operation.
+ * @param params.gatewayUri - The DID DHT Gateway or Pkarr Relay URI.
+ * @param params.publicKeyBytes - The public key bytes of the Identity Key, z-base-32 encoded.
+ * @returns A promise resolving to a BEP44 message containing the signed DNS packet.
+ */
+export declare function pkarrGet({ gatewayUri, publicKeyBytes }: {
+    publicKeyBytes: Uint8Array;
+    gatewayUri: string;
+}): Promise<Bep44Message>;
+/**
+ * Publishes a signed BEP44 message to a DID DHT Gateway or Pkarr Relay server.
+ *
+ * @see {@link https://github.com/Nuhvi/pkarr/blob/main/design/relays.md | Pkarr Relay design}
+ *
+ * @param params - The parameters to use when publishing a signed BEP44 message to a Pkarr relay server.
+ * @param params.gatewayUri - The DID DHT Gateway or Pkarr Relay URI.
+ * @param params.bep44Message - The BEP44 message to be published, containing the signed DNS packet.
+ * @returns A promise resolving to `true` if the message was successfully published, otherwise `false`.
+ */
+export declare function pkarrPut({ gatewayUri, bep44Message }: {
+    bep44Message: Bep44Message;
+    gatewayUri: string;
+}): Promise<boolean>;
+/**
+ * Creates a BEP44 put message, which is used to publish a DID document to the DHT network.
+ *
+ * @param params - The parameters to use when creating the BEP44 put message.
+ * @param params.dnsPacket - The DNS packet to encode in the BEP44 message.
+ * @param params.publicKeyBytes - The public key bytes of the Identity Key.
+ * @param params.signer - Signer that can sign and verify data using the Identity Key.
+ * @returns A promise that resolves to a BEP44 put message.
+ */
+export declare function createBep44PutMessage({ dnsPacket, publicKeyBytes, signer }: {
+    dnsPacket: Packet;
+    publicKeyBytes: Uint8Array;
+    signer: Signer;
+}): Promise<Bep44Message>;
+/**
+ * Parses and verifies a BEP44 Get message, converting it to a DNS packet.
+ *
+ * @param params - The parameters to use when verifying and parsing the BEP44 Get response message.
+ * @param params.bep44Message - The BEP44 message to verify and parse.
+ * @returns A promise that resolves to a DNS packet.
+ */
+export declare function parseBep44GetMessage({ bep44Message }: {
+    bep44Message: Bep44Message;
+}): Promise<Packet>;
+//# sourceMappingURL=did-dht-pkarr.d.ts.map

package/dist/types/methods/did-dht-pkarr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-dht-pkarr.d.ts","sourceRoot":"","sources":["../../../src/methods/did-dht-pkarr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAoBvD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE;IAC7D,cAAc,EAAE,UAAU,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6CxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE;IAC3D,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4BnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,UAAU,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsBxB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,YAAY,EAAE,EAAE;IAC3D,YAAY,EAAE,YAAY,CAAC;CAC5B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB"}

package/dist/types/methods/did-dht-types.d.ts

@@ -0,0 +1,286 @@
+import type { DidCreateOptions, DidCreateVerificationMethod } from './did-method.js';
+import type { DidService } from '../types/did-core.js';
+/**
+ * Represents a BEP44 message, which is used for storing and retrieving data in the Mainline DHT
+ * network.
+ *
+ * A BEP44 message is used primarily in the context of the DID DHT method for publishing and
+ * resolving DID documents in the DHT network. This type encapsulates the data structure required
+ * for such operations in accordance with BEP44.
+ *
+ * @see {@link https://www.bittorrent.org/beps/bep_0044.html | BEP44}
+ */
+export interface Bep44Message {
+    /**
+     * The public key bytes of the Identity Key, which serves as the identifier in the DHT network for
+     * the corresponding BEP44 message.
+     */
+    k: Uint8Array;
+    /**
+     * The sequence number of the message, used to ensure the latest version of the data is retrieved
+     * and updated. It's a monotonically increasing number.
+     */
+    seq: number;
+    /**
+     * The signature of the message, ensuring the authenticity and integrity of the data. It's
+     * computed over the bencoded sequence number and value.
+     */
+    sig: Uint8Array;
+    /**
+     * The actual data being stored or retrieved from the DHT network, typically encoded in a format
+     * suitable for DNS packet representation of a DID Document.
+     */
+    v: Uint8Array;
+}
+/**
+ * Options for creating a Decentralized Identifier (DID) using the DID DHT method.
+ */
+export interface DidDhtCreateOptions<TKms> extends DidCreateOptions<TKms> {
+    /**
+     * Optionally specify that the DID Subject is also identified by one or more other DIDs or URIs.
+     *
+     * A DID subject can have multiple identifiers for different purposes, or at different times.
+     * The assertion that two or more DIDs (or other types of URI) refer to the same DID subject can
+     * be made using the `alsoKnownAs` property.
+     *
+     * @see {@link https://www.w3.org/TR/did-core/#also-known-as | DID Core Specification, § Also Known As}
+     *
+     * @example
+     * ```ts
+     * const did = await DidDht.create({
+     *  options: {
+     *   alsoKnownAs: 'did:example:123'
+     * };
+     * ```
+     */
+    alsoKnownAs?: string[];
+    /**
+     * Optionally specify which DID (or DIDs) is authorized to make changes to the DID document.
+     *
+     * A DID controller is an entity that is authorized to make changes to a DID document. Typically,
+     * only the DID Subject (i.e., the value of `id` property in the DID document) is authoritative.
+     * However, another DID (or DIDs) can be specified as the DID controller, and when doing so, any
+     * verification methods contained in the DID document for the other DID should be accepted as
+     * authoritative. In other words, proofs created by the controller DID should be considered
+     * equivalent to proofs created by the DID Subject.
+     *
+     * @see {@link https://www.w3.org/TR/did-core/#did-controller | DID Core Specification, § DID Controller}
+     *
+     * @example
+     * ```ts
+     * const did = await DidDht.create({
+     *  options: {
+     *   controller: 'did:example:123'
+     * };
+     * ```
+     */
+    controllers?: string | string[];
+    /**
+     * Optional. The URI of a server involved in executing DID method operations. In the context of
+     * DID creation, the endpoint is expected to be a DID DHT Gateway or Pkarr relay. If not
+     * specified, a default gateway node is used.
+     */
+    gatewayUri?: string;
+    /**
+     * Optional. Determines whether the created DID should be published to the DHT network.
+     *
+     * If set to `true` or omitted, the DID is publicly discoverable. If `false`, the DID is not
+     * published and cannot be resolved by others. By default, newly created DIDs are published.
+     *
+     * @see {@link https://did-dht.com | DID DHT Method Specification}
+     *
+     * @example
+     * ```ts
+     * const did = await DidDht.create({
+     *  options: {
+     *   publish: false
+     * };
+     * ```
+     */
+    publish?: boolean;
+    /**
+     * Optional. An array of service endpoints associated with the DID.
+     *
+     * Services are used in DID documents to express ways of communicating with the DID subject or
+     * associated entities. A service can be any type of service the DID subject wants to advertise,
+     * including decentralized identity management services for further discovery, authentication,
+     * authorization, or interaction.
+     *
+     * @see {@link https://www.w3.org/TR/did-core/#services | DID Core Specification, § Services}
+     *
+     * @example
+     * ```ts
+     * const did = await DidDht.create({
+     *  options: {
+     *   services: [
+     *     {
+     *       id: 'did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y#dwn',
+     *       type: 'DecentralizedWebNode',
+     *       serviceEndpoint: ['https://example.com/dwn1', 'https://example/dwn2']
+     *     }
+     *   ]
+     * };
+     * ```
+     */
+    services?: DidService[];
+    /**
+     * Optionally specify one or more registered DID DHT types to make the DID discovereable.
+     *
+     * Type indexing is an OPTIONAL feature that enables DIDs to become discoverable. DIDs that wish
+     * to be discoverable and resolveable by type can include one or more types when publishing their
+     * DID document to a DID DHT Gateway.
+     *
+     * The registered DID types are published in the {@link https://did-dht.com/registry/index.html#indexed-types | DID DHT Registry}.
+     */
+    types?: (DidDhtRegisteredDidType | keyof typeof DidDhtRegisteredDidType)[];
+    /**
+     * Optional. An array of verification methods to be included in the DID document.
+     *
+     * By default, a newly created DID DHT document will contain a single Ed25519 verification method,
+     * also known as the {@link https://did-dht.com/#term:identity-key | Identity Key}. Additional
+     * verification methods can be added to the DID document using the `verificationMethods` property.
+     *
+     * @see {@link https://www.w3.org/TR/did-core/#verification-methods | DID Core Specification, § Verification Methods}
+     *
+     * @example
+     * ```ts
+     * const did = await DidDht.create({
+     *  options: {
+     *   verificationMethods: [
+     *     {
+     *       algorithm: 'Ed25519',
+     *       purposes: ['authentication', 'assertionMethod']
+     *     },
+     *     {
+     *       algorithm: 'Ed25519',
+     *       id: 'dwn-sig',
+     *       purposes: ['authentication', 'assertionMethod']
+     *     }
+     *   ]
+     * };
+     * ```
+     */
+    verificationMethods?: DidCreateVerificationMethod<TKms>[];
+}
+/**
+ * Proof to used to construct the `_prv._did.` DNS record as described in https://did-dht.com/#rotation to link a DID to a previous DID.
+ */
+export type PreviousDidProof = {
+    /** The previous DID. */
+    previousDid: string;
+    /** The signature signed using the private Identity Key of the previous DID in Base64URL format. */
+    signature: string;
+};
+/**
+ * Represents an optional extension to a DID Document's DNS packet representation exposed as a
+ * type index.
+ *
+ * Type indexing is an OPTIONAL feature that enables DIDs to become discoverable. DIDs that wish to
+ * be discoverable and resolveable by type can include one or more types when publishing their DID
+ * document to a DID DHT Gateway.
+ *
+ * The registered DID types are published in the {@link https://did-dht.com/registry/index.html#indexed-types | DID DHT Registry}.
+ */
+export declare enum DidDhtRegisteredDidType {
+    /**
+     * Type 0 is reserved for DIDs that do not wish to associate themselves with a specific type but
+     * wish to make themselves discoverable.
+     */
+    Discoverable = 0,
+    /**
+     * Organization
+     * @see {@link https://schema.org/Organization | schema definition}
+     */
+    Organization = 1,
+    /**
+     * Government Organization
+     * @see {@link https://schema.org/GovernmentOrganization | schema definition}
+     */
+    Government = 2,
+    /**
+     * Corporation
+     * @see {@link https://schema.org/Corporation | schema definition}
+     */
+    Corporation = 3,
+    /**
+     * Corporation
+     * @see {@link https://schema.org/Corporation | schema definition}
+     */
+    LocalBusiness = 4,
+    /**
+     * Software Package
+     * @see {@link https://schema.org/SoftwareSourceCode | schema definition}
+     */
+    SoftwarePackage = 5,
+    /**
+     * Web App
+     * @see {@link https://schema.org/WebApplication | schema definition}
+     */
+    WebApp = 6,
+    /**
+     * Financial Institution
+     * @see {@link https://schema.org/FinancialService | schema definition}
+     */
+    FinancialInstitution = 7
+}
+/**
+ * Enumerates the types of keys that can be used in a DID DHT document.
+ *
+ * The DID DHT method supports various cryptographic key types. These key types are essential for
+ * the creation and management of DIDs and their associated cryptographic operations like signing
+ * and encryption. The registered key types are published in the DID DHT Registry and each is
+ * assigned a unique numerical value for use by client and gateway implementations.
+ *
+ * The registered key types are published in the {@link https://did-dht.com/registry/index.html#key-type-index | DID DHT Registry}.
+ */
+export declare enum DidDhtRegisteredKeyType {
+    /**
+     * Ed25519: A public-key signature system using the EdDSA (Edwards-curve Digital Signature
+     * Algorithm) and Curve25519.
+     */
+    Ed25519 = 0,
+    /**
+     * secp256k1: A cryptographic curve used for digital signatures in a range of decentralized
+     * systems.
+     */
+    secp256k1 = 1,
+    /**
+     * secp256r1: Also known as P-256 or prime256v1, this curve is used for cryptographic operations
+     * and is widely supported in various cryptographic libraries and standards.
+     */
+    secp256r1 = 2,
+    /**
+     * X25519: A public key used for Diffie-Hellman key exchange using Curve25519.
+     */
+    X25519 = 3
+}
+/**
+ * Maps {@link https://www.w3.org/TR/did-core/#verification-relationships | DID Core Verification Relationship}
+ * values to the corresponding record name in the DNS packet representation of a DHT DID document.
+ */
+export declare enum DidDhtVerificationRelationship {
+    /**
+     * Specifies how the DID subject is expected to be authenticated.
+     */
+    authentication = "auth",
+    /**
+     * Specifies how the DID subject is expected to express claims, such as for issuing Verifiable
+     * Credentials.
+     */
+    assertionMethod = "asm",
+    /**
+     * Specifies a mechanism used by the DID subject to delegate a cryptographic capability to another
+     * party
+     */
+    capabilityDelegation = "del",
+    /**
+     * Specifies a verification method used by the DID subject to invoke a cryptographic capability.
+     */
+    capabilityInvocation = "inv",
+    /**
+     * Specifies how an entity can generate encryption material to communicate confidentially with the
+     * DID subject.
+     */
+    keyAgreement = "agm"
+}
+//# sourceMappingURL=did-dht-types.d.ts.map

package/dist/types/methods/did-dht-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-dht-types.d.ts","sourceRoot":"","sources":["../../../src/methods/did-dht-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,CAAC,EAAE,UAAU,CAAC;IAEd;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAE,UAAU,CAAC;IAEhB;;;OAGG;IACH,CAAC,EAAE,UAAU,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,CAAE,SAAQ,gBAAgB,CAAC,IAAI,CAAC;IACvE;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEhC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,CAAC,uBAAuB,GAAG,MAAM,OAAO,uBAAuB,CAAC,EAAE,CAAC;IAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IAEpB,mGAAmG;IACnG,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;GASG;AACH,oBAAY,uBAAuB;IACjC;;;OAGG;IACH,YAAY,IAAI;IAEhB;;;OAGG;IACH,YAAY,IAAI;IAEhB;;;OAGG;IACH,UAAU,IAAI;IAEd;;;OAGG;IACH,WAAW,IAAI;IAEf;;;OAGG;IACH,aAAa,IAAI;IAEjB;;;OAGG;IACH,eAAe,IAAI;IAEnB;;;OAGG;IACH,MAAM,IAAI;IAEV;;;OAGG;IACH,oBAAoB,IAAI;CACzB;AAED;;;;;;;;;GASG;AACH,oBAAY,uBAAuB;IACjC;;;OAGG;IACH,OAAO,IAAI;IAEX;;;OAGG;IACH,SAAS,IAAI;IAEb;;;OAGG;IACH,SAAS,IAAI;IAEb;;OAEG;IACH,MAAM,IAAI;CACX;AAED;;;GAGG;AACH,oBAAY,8BAA8B;IACxC;;OAEG;IACH,cAAc,SAAS;IAEvB;;;OAGG;IACH,eAAe,QAAQ;IAEvB;;;OAGG;IACH,oBAAoB,QAAQ;IAE5B;;OAEG;IACH,oBAAoB,QAAQ;IAE5B;;;OAGG;IACH,YAAY,QAAQ;CACrB"}

package/dist/types/methods/did-dht-utils.d.ts

@@ -0,0 +1,54 @@
+import type { AsymmetricKeyConverter, Jwk } from '@enbox/crypto';
+import type { PreviousDidProof } from './did-dht-types.js';
+/**
+ * Converts a DID URI to a JSON Web Key (JWK) representing the Identity Key.
+ *
+ * @param params - The parameters to use for the conversion.
+ * @param params.didUri - The DID URI containing the Identity Key.
+ * @returns A promise that resolves to a JWK representing the Identity Key.
+ */
+export declare function identifierToIdentityKey({ didUri }: {
+    didUri: string;
+}): Promise<Jwk>;
+/**
+ * Converts a DID URI to the byte array representation of the Identity Key.
+ *
+ * @param params - The parameters to use for the conversion.
+ * @param params.didUri - The DID URI containing the Identity Key.
+ * @returns A byte array representation of the Identity Key.
+ */
+export declare function identifierToIdentityKeyBytes({ didUri }: {
+    didUri: string;
+}): Uint8Array;
+/**
+ * Encodes a DID DHT Identity Key into a DID identifier.
+ *
+ * This method first z-base-32 encodes the Identity Key. The resulting string is prefixed with
+ * `did:dht:` to form the DID identifier.
+ *
+ * @param params - The parameters to use for the conversion.
+ * @param params.identityKey The Identity Key from which the DID identifier is computed.
+ * @returns A promise that resolves to a string containing the DID identifier.
+ */
+export declare function identityKeyToIdentifier({ identityKey }: {
+    identityKey: Jwk;
+}): Promise<string>;
+/**
+ * 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.
+ */
+export declare function keyConverter(curve: string): AsymmetricKeyConverter;
+/**
+ * Validates the proof of previous DID given.
+ *
+ * @param params - The parameters to validate the previous DID proof.
+ * @param params.newDid - The new DID that the previous DID is linking to.
+ * @param params.previousDidProof - The proof of the previous DID, containing the previous DID and signature signed by the previous DID.
+ */
+export declare function validatePreviousDidProof({ newDid, previousDidProof }: {
+    newDid: string;
+    previousDidProof: PreviousDidProof;
+}): Promise<void>;
+//# sourceMappingURL=did-dht-utils.d.ts.map

package/dist/types/methods/did-dht-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-dht-utils.d.ts","sourceRoot":"","sources":["../../../src/methods/did-dht-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAKjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAU3D;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,EAAE,MAAM,EAAE,EAAE;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,GAAG,CAAC,CAQf;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,MAAM,EAAE,EAAE;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CA2Bb;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,EAAE,WAAW,EAAE,EAAE;IAC7D,WAAW,EAAE,GAAG,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAmClE;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,gBAAgB,CAAC;CACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}