@dwn-protocol/id-sdk 0.2.5 → 0.2.6

package/src/dids/did-ion.ts

@@ -1,613 +0,0 @@
-import type { JwkKeyPair, PrivateKeyJwk, PublicKeyJwk, IDCrypto } from '../crypto/index.js';
-import type { IonDocumentModel, IonPublicKeyModel, JwkEd25519, JwkEs256k } from '@decentralized-identity/ion-sdk';
-
-import { Convert, universalTypeOf } from '../common/index.js';
-import IonProofOfWork from '@decentralized-identity/ion-pow-sdk';
-import { EcdsaAlgorithm, EdDsaAlgorithm, Jose } from '../crypto/index.js';
-import { IonDid, IonPublicKeyPurpose, IonRequest } from '@decentralized-identity/ion-sdk';
-
-import type { DidDocument, DidKeySetVerificationMethodKey, DidMethod, DidResolutionOptions, DidResolutionResult, DidService, DwnServiceEndpoint, PortableDid } from './types.js';
-
-import { getServices, isDwnServiceEndpoint, parseDid } from './utils.js';
-
-export type DidIonAnchorOptions = {
-  challengeEnabled?: boolean;
-  challengeEndpoint?: string;
-  operationsEndpoint?: string;
-  keySet: DidIonKeySet;
-  services: DidService[];
-}
-
-export type DidIonCreateOptions = {
-  anchor?: boolean;
-  keyAlgorithm?: typeof SupportedCryptoAlgorithms[number];
-  keySet?: DidIonKeySet;
-  services?: DidService[];
-}
-
-export type DidIonKeySet = {
-  recoveryKey?: JwkKeyPair;
-  updateKey?: JwkKeyPair;
-  verificationMethodKeys?: DidKeySetVerificationMethodKey[];
-}
-
-enum OperationType {
-  Create = 'create',
-  Update = 'update',
-  Deactivate = 'deactivate',
-  Recover = 'recover'
-}
-
-/**
- * Data model representing a public key in the DID Document.
- */
-export interface IonCreateRequestModel {
-  type: OperationType;
-  suffixData: {
-    deltaHash: string;
-    recoveryCommitment: string;
-  };
-  delta: {
-    updateCommitment: string;
-    patches: {
-      action: string;
-      document: IonDocumentModel;
-    }[];
-  }
-}
-
-const SupportedCryptoAlgorithms = [
-  'Ed25519',
-  'secp256k1'
-] as const;
-
-const VerificationRelationshipToIonPublicKeyPurpose = {
-  assertionMethod      : IonPublicKeyPurpose.AssertionMethod,
-  authentication       : IonPublicKeyPurpose.Authentication,
-  capabilityDelegation : IonPublicKeyPurpose.CapabilityDelegation,
-  capabilityInvocation : IonPublicKeyPurpose.CapabilityInvocation,
-  keyAgreement         : IonPublicKeyPurpose.KeyAgreement
-};
-
-export class DidIonMethod implements DidMethod {
-  /**
-   * Name of the DID method
-  */
-  public static methodName = 'ion';
-
-  public static async anchor(options: {
-    services: DidService[],
-    keySet: DidIonKeySet,
-    challengeEnabled?: boolean,
-    challengeEndpoint?: string,
-    operationsEndpoint?: string
-  }): Promise<DidResolutionResult | undefined> {
-    const {
-      challengeEnabled = true,
-      challengeEndpoint = 'https://beta.ion.msidentity.com/api/v1.0/proof-of-work-challenge',
-      keySet,
-      services,
-      operationsEndpoint = 'https://beta.ion.msidentity.com/api/v1.0/operations'
-    } = options;
-
-    // Create ION Document.
-    const ionDocument = await DidIonMethod.createIonDocument({
-      keySet: keySet,
-      services
-    });
-
-    const createRequest = await DidIonMethod.getIonCreateRequest({
-      ionDocument,
-      recoveryPublicKeyJwk : keySet.recoveryKey.publicKeyJwk,
-      updatePublicKeyJwk   : keySet.updateKey.publicKeyJwk
-    });
-
-    let resolutionResult: DidResolutionResult;
-
-    if (challengeEnabled) {
-      const response = await IonProofOfWork.submitIonRequest(
-        challengeEndpoint,
-        operationsEndpoint,
-        JSON.stringify(createRequest)
-      );
-
-      if (response !== undefined && universalTypeOf(response) === 'String') {
-        resolutionResult = JSON.parse(response);
-      }
-
-    } else {
-      const response = await fetch(operationsEndpoint, {
-        method  : 'POST',
-        mode    : 'cors',
-        body    : JSON.stringify(createRequest),
-        headers : {
-          'Content-Type': 'application/json'
-        }
-      });
-
-      if (response.ok) {
-        resolutionResult = await response.json();
-      }
-    }
-
-    return resolutionResult;
-  }
-
-  public static async create(options?: DidIonCreateOptions): Promise<PortableDid> {
-    let { anchor, keyAlgorithm, keySet, services } = options ?? { };
-
-    // Begin constructing a PortableDid.
-    const did: Partial<PortableDid> = {};
-
-    // If any member of the key set is missing, generate the keys.
-    did.keySet = await DidIonMethod.generateKeySet({ keyAlgorithm, keySet });
-
-    // Generate Long Form DID URI.
-    did.did = await DidIonMethod.getLongFormDid({
-      keySet: did.keySet,
-      services
-    });
-
-    // Get short form DID.
-    did.canonicalId = await DidIonMethod.getShortFormDid({ didUrl: did.did });
-
-    let didResolutionResult: DidResolutionResult | undefined;
-    if (anchor) {
-      // Attempt to anchor the DID.
-      didResolutionResult = await DidIonMethod.anchor({
-        keySet: did.keySet,
-        services
-      });
-
-    } else {
-      // If anchoring was not requested, then resolve the long form DID.
-      didResolutionResult = await DidIonMethod.resolve({ didUrl: did.did });
-    }
-
-    // Store the DID Document.
-    did.document = didResolutionResult.didDocument;
-
-    return did as PortableDid;
-  }
-
-  public static async decodeLongFormDid(options: {
-    didUrl: string
-  }): Promise<IonCreateRequestModel> {
-    const { didUrl } = options;
-
-    const parsedDid = parseDid({ didUrl });
-
-    if (!parsedDid) {
-      throw new Error(`DidIonMethod: Unable to parse DID: ${didUrl}`);
-    }
-
-    const decodedLongFormDid = Convert.base64Url(
-      parsedDid.id.split(':').pop()
-    ).toObject() as Pick<IonCreateRequestModel, 'delta' | 'suffixData'>;
-
-    const createRequest: IonCreateRequestModel = {
-      ...decodedLongFormDid,
-      type: OperationType.Create
-    };
-
-    return createRequest;
-  }
-
-  /**
-   * Generates two key pairs used for authorization and encryption purposes
-   * when interfacing with DWNs. The IDs of these keys are referenced in the
-   * service object that includes the dwnUrls provided.
-   */
-  public static async generateDwnOptions(options: {
-    encryptionKeyId?: string,
-    serviceEndpointNodes: string[],
-    serviceId?: string,
-    signingKeyAlgorithm?: typeof SupportedCryptoAlgorithms[number]
-    signingKeyId?: string,
-  }): Promise<DidIonCreateOptions> {
-    const {
-      signingKeyAlgorithm = 'Ed25519', // Generate Ed25519 key pairs, by default.
-      serviceId = '#dwn', // Use default ID value, unless overridden.
-      signingKeyId = '#dwn-sig', // Use default key ID value, unless overridden.
-      encryptionKeyId = '#dwn-enc', // Use default key ID value, unless overridden.
-      serviceEndpointNodes } = options;
-
-    const signingKeyPair = await DidIonMethod.generateJwkKeyPair({
-      keyAlgorithm : signingKeyAlgorithm,
-      keyId        : signingKeyId
-    });
-
-    /** Currently, `id` has only implemented support for record
-     * encryption using the `ECIES-ES256K` crypto algorithm. Until the
-     * DWN SDK supports ECIES with EdDSA, the encryption key pair must
-     * use secp256k1. */
-    const encryptionKeyPair = await DidIonMethod.generateJwkKeyPair({
-      keyAlgorithm : 'secp256k1',
-      keyId        : encryptionKeyId
-    });
-
-    const keySet: DidIonKeySet = {
-      verificationMethodKeys: [
-        { ...signingKeyPair, relationships: ['authentication'] },
-        { ...encryptionKeyPair, relationships: ['keyAgreement'] }
-      ]
-    };
-
-    const serviceEndpoint: DwnServiceEndpoint = {
-      encryptionKeys : [encryptionKeyId],
-      nodes          : serviceEndpointNodes,
-      signingKeys    : [signingKeyId]
-    };
-
-    const services: DidService[] = [{
-      id   : serviceId,
-      serviceEndpoint,
-      type : 'DecentralizedWebNode',
-    }];
-
-    return { keySet, services };
-  }
-
-  public static async generateJwkKeyPair(options: {
-    keyAlgorithm: typeof SupportedCryptoAlgorithms[number],
-    keyId?: string
-  }): Promise<JwkKeyPair> {
-    const { keyAlgorithm, keyId } = options;
-
-    let cryptoKeyPair: IDCrypto.CryptoKeyPair;
-
-    switch (keyAlgorithm) {
-      case 'Ed25519': {
-        cryptoKeyPair = await new EdDsaAlgorithm().generateKey({
-          algorithm   : { name: 'EdDSA', namedCurve: 'Ed25519' },
-          extractable : true,
-          keyUsages   : ['sign', 'verify']
-        });
-        break;
-      }
-
-      case 'secp256k1': {
-        cryptoKeyPair = await new EcdsaAlgorithm().generateKey({
-          algorithm   : { name: 'ECDSA', namedCurve: 'secp256k1' },
-          extractable : true,
-          keyUsages   : ['sign', 'verify']
-        });
-        break;
-      }
-
-      default: {
-        throw new Error(`Unsupported crypto algorithm: '${keyAlgorithm}'`);
-      }
-    }
-
-    // Convert the CryptoKeyPair to JwkKeyPair.
-    const jwkKeyPair = await Jose.cryptoKeyToJwkPair({ keyPair: cryptoKeyPair });
-
-    // Set kid values.
-    if (keyId) {
-      jwkKeyPair.privateKeyJwk.kid = keyId;
-      jwkKeyPair.publicKeyJwk.kid = keyId;
-    } else {
-      // If a key ID is not specified, generate RFC 7638 JWK thumbprint.
-      const jwkThumbprint = await Jose.jwkThumbprint({ key: jwkKeyPair.publicKeyJwk });
-      jwkKeyPair.privateKeyJwk.kid = jwkThumbprint;
-      jwkKeyPair.publicKeyJwk.kid = jwkThumbprint;
-    }
-
-    return jwkKeyPair;
-  }
-
-  public static async generateKeySet(options?: {
-    keyAlgorithm?: typeof SupportedCryptoAlgorithms[number],
-    keySet?: DidIonKeySet
-  }): Promise<DidIonKeySet> {
-    // Generate Ed25519 authentication key pair, by default.
-    let { keyAlgorithm = 'Ed25519', keySet = {} } = options ?? {};
-
-    // If keySet lacks verification method keys, generate one.
-    if (keySet.verificationMethodKeys === undefined) {
-      const authenticationkeyPair = await DidIonMethod.generateJwkKeyPair({
-        keyAlgorithm,
-        keyId: 'dwn-sig'
-      });
-      keySet.verificationMethodKeys = [{
-        ...authenticationkeyPair,
-        relationships: ['authentication', 'assertionMethod']
-      }];
-    }
-
-    // If keySet lacks recovery key, generate one.
-    if (keySet.recoveryKey === undefined) {
-      // Note: ION/Sidetree only supports secp256k1 recovery keys.
-      keySet.recoveryKey = await DidIonMethod.generateJwkKeyPair({
-        keyAlgorithm : 'secp256k1',
-        keyId        : 'ion-recovery-1'
-      });
-    }
-
-    // If keySet lacks update key, generate one.
-    if (keySet.updateKey === undefined) {
-      // Note: ION/Sidetree only supports secp256k1 update keys.
-      keySet.updateKey = await DidIonMethod.generateJwkKeyPair({
-        keyAlgorithm : 'secp256k1',
-        keyId        : 'ion-update-1'
-      });
-    }
-
-    // Generate RFC 7638 JWK thumbprints if `kid` is missing from any key.
-    for (const key of [...keySet.verificationMethodKeys, keySet.recoveryKey, keySet.updateKey]) {
-      if ('publicKeyJwk' in key) key.publicKeyJwk.kid ??= await Jose.jwkThumbprint({ key: key.publicKeyJwk });
-      if ('privateKeyJwk' in key) key.privateKeyJwk.kid ??= await Jose.jwkThumbprint({ key: key.privateKeyJwk });
-    }
-
-    return keySet;
-  }
-
-  /**
-   * Given the W3C DID Document of a `did:ion` DID, return the identifier of
-   * the verification method key that will be used for signing messages and
-   * credentials, by default.
-   *
-   * @param document = DID Document to get the default signing key from.
-   * @returns Verification method identifier for the default signing key.
-   */
-  public static async getDefaultSigningKey(options: {
-      didDocument: DidDocument
-    }): Promise<string | undefined> {
-    const { didDocument } = options;
-
-    if (!didDocument.id) {
-      throw new Error(`DidIonMethod: DID document is missing 'id' property`);
-    }
-
-    /** If the DID document contains a DWN service endpoint in the expected
-     * format, return the first entry in the `signingKeys` array. */
-    const [dwnService] = getServices({ didDocument, type: 'DecentralizedWebNode' });
-    if (isDwnServiceEndpoint(dwnService?.serviceEndpoint)) {
-      const [verificationMethodId] = dwnService.serviceEndpoint.signingKeys;
-      const did = didDocument.id;
-      const signingKeyId = `${did}${verificationMethodId}`;
-      return signingKeyId;
-    }
-
-    /** Otherwise, fallback to a naive approach of returning the first key ID
-     * in the `authentication` verification relationships array. */
-    if (didDocument.authentication
-        && Array.isArray(didDocument.authentication)
-        && didDocument.authentication.length > 0
-        && typeof didDocument.authentication[0] === 'string') {
-      const [verificationMethodId] = didDocument.authentication;
-      const did = didDocument.id;
-      const signingKeyId = `${did}${verificationMethodId}`;
-      return signingKeyId;
-    }
-  }
-
-  public static async getLongFormDid(options: {
-    services: DidService[],
-    keySet: DidIonKeySet
-  }): Promise<string> {
-    const { services = [], keySet } = options;
-
-    // Create ION Document.
-    const ionDocument = await DidIonMethod.createIonDocument({
-      keySet: keySet,
-      services
-    });
-
-    // Filter JWK to only those properties expected by ION/Sidetree.
-    const recoveryKey = DidIonMethod.jwkToIonJwk({ key: keySet.recoveryKey.publicKeyJwk }) as JwkEs256k;
-    const updateKey = DidIonMethod.jwkToIonJwk({ key: keySet.updateKey.publicKeyJwk }) as JwkEs256k;
-
-    // Create an ION DID create request operation.
-    const did = await IonDid.createLongFormDid({
-      document: ionDocument,
-      recoveryKey,
-      updateKey
-    });
-
-    return did;
-  }
-
-  public static async getShortFormDid(options: {
-    didUrl: string
-  }): Promise<string> {
-    const { didUrl } = options;
-
-    const parsedDid = parseDid({ didUrl });
-
-    if (!parsedDid) {
-      throw new Error(`DidIonMethod: Unable to parse DID: ${didUrl}`);
-    }
-
-    const shortFormDid = parsedDid.did.split(':', 3).join(':');
-
-    return shortFormDid;
-  }
-
-  public static async resolve(options: {
-    didUrl: string,
-    resolutionOptions?: DidResolutionOptions
-  }): Promise<DidResolutionResult> {
-    // TODO: add resolutionOptions as defined in https://www.w3.org/TR/did-core/#did-resolution
-    const { didUrl, resolutionOptions = {} } = options;
-
-    const parsedDid = parseDid({ didUrl });
-    if (!parsedDid) {
-      return {
-        '@context'            : 'https://w3id.org/did-resolution/v1',
-        didDocument           : undefined,
-        didDocumentMetadata   : {},
-        didResolutionMetadata : {
-          contentType  : 'application/did+json',
-          error        : 'invalidDid',
-          errorMessage : `Cannot parse DID: ${didUrl}`
-        }
-      };
-    }
-
-    if (parsedDid.method !== 'ion') {
-      return {
-        '@context'            : 'https://w3id.org/did-resolution/v1',
-        didDocument           : undefined,
-        didDocumentMetadata   : {},
-        didResolutionMetadata : {
-          contentType  : 'application/did+json',
-          error        : 'methodNotSupported',
-          errorMessage : `Method not supported: ${parsedDid.method}`
-        }
-      };
-    }
-
-    const { resolutionEndpoint = 'https://discover.did.msidentity.com/1.0/identifiers/' } = resolutionOptions;
-    const normalizeUrl = (url: string): string => url.endsWith('/') ? url : url + '/';
-    const resolutionUrl = `${normalizeUrl(resolutionEndpoint)}${parsedDid.did}`;
-
-    const response = await fetch(resolutionUrl);
-
-    let resolutionResult: DidResolutionResult | object;
-    try {
-      resolutionResult = await response.json();
-    } catch (error) {
-      resolutionResult = {};
-    }
-
-    if (response.ok) {
-      return resolutionResult as DidResolutionResult;
-    }
-
-    // Response was not "OK" (HTTP 4xx-5xx status code)
-
-    // Return result if it contains DID resolution metadata.
-    if ('didResolutionMetadata' in resolutionResult) {
-      return resolutionResult;
-    }
-
-    // Set default error code and message.
-    let error = 'internalError';
-    let errorMessage = `DID resolver responded with HTTP status code: ${response.status}`;
-
-    /** The Microsoft resolution endpoint does not return a valid DidResolutionResult
-       * when an ION DID is "not found" so normalization is needed. */
-    if ('error' in resolutionResult &&
-        typeof resolutionResult.error === 'object' &&
-        'code' in resolutionResult.error &&
-        typeof resolutionResult.error.code === 'string' &&
-        'message' in resolutionResult.error &&
-        typeof resolutionResult.error.message === 'string') {
-      error = resolutionResult.error.code.includes('not_found') ? 'notFound' : error;
-      errorMessage = resolutionResult.error.message ?? errorMessage;
-    }
-
-    return {
-      '@context'            : 'https://w3id.org/did-resolution/v1',
-      didDocument           : undefined,
-      didDocumentMetadata   : {},
-      didResolutionMetadata : {
-        contentType: 'application/did+json',
-        error,
-        errorMessage
-      }
-    };
-  }
-
-  public static async createIonDocument(options: {
-    keySet: DidIonKeySet,
-    services?: DidService[]
-  }): Promise<IonDocumentModel> {
-    const { services = [], keySet } = options;
-
-    /**
-     * STEP 1: Convert key set verification method keys to ION SDK format.
-     */
-
-    const ionPublicKeys: IonPublicKeyModel[] = [];
-
-    for (const key of keySet.verificationMethodKeys) {
-      // Map W3C DID verification relationship names to ION public key purposes.
-      const ionPurposes: IonPublicKeyPurpose[] = [];
-      for (const relationship of key.relationships) {
-        ionPurposes.push(
-          VerificationRelationshipToIonPublicKeyPurpose[relationship]
-        );
-      }
-
-      /** During certain ION operations, JWK validation will throw an error
-       * if key IDs provided as input are prefixed with `#`. ION operation
-       * outputs and DID document resolution always include the `#` prefix
-       * for key IDs resulting in a confusing mismatch between inputs and
-       * outputs.  To improve the developer experience, this inconsistency
-       * is addressed by normalizing input key IDs before being passed
-       * to ION SDK methods. */
-      const publicKeyId = (key.publicKeyJwk.kid.startsWith('#'))
-        ? key.publicKeyJwk.kid.substring(1)
-        : key.publicKeyJwk.kid;
-
-      // Convert public key JWK to ION format.
-      const publicKey: IonPublicKeyModel = {
-        id           : publicKeyId,
-        publicKeyJwk : DidIonMethod.jwkToIonJwk({ key: key.publicKeyJwk }),
-        purposes     : ionPurposes,
-        type         : 'JsonWebKey2020'
-      };
-
-      ionPublicKeys.push(publicKey);
-    }
-
-    /**
-     * STEP 2: Convert service entries, if any, to ION SDK format.
-     */
-    const ionServices = services.map(service => ({
-      ...service,
-      id: service.id.startsWith('#') ? service.id.substring(1) : service.id
-    }));
-
-    /**
-     * STEP 3: Format as ION document.
-     */
-
-    const ionDocumentModel: IonDocumentModel = {
-      publicKeys : ionPublicKeys,
-      services   : ionServices
-    };
-
-    return ionDocumentModel;
-  }
-
-  public static async getIonCreateRequest(options: {
-    ionDocument: IonDocumentModel,
-    recoveryPublicKeyJwk: PublicKeyJwk,
-    updatePublicKeyJwk: PublicKeyJwk
-  }): Promise<IonCreateRequestModel> {
-    const { ionDocument, recoveryPublicKeyJwk, updatePublicKeyJwk } = options;
-
-    // Create an ION DID create request operation.
-    const createRequest = await IonRequest.createCreateRequest({
-      document    : ionDocument,
-      recoveryKey : DidIonMethod.jwkToIonJwk({ key: recoveryPublicKeyJwk }) as JwkEs256k,
-      updateKey   : DidIonMethod.jwkToIonJwk({ key: updatePublicKeyJwk }) as JwkEs256k
-    });
-
-    return createRequest;
-  }
-
-  private static jwkToIonJwk({ key }: { key: PrivateKeyJwk | PublicKeyJwk }): JwkEd25519 | JwkEs256k {
-    let ionJwk: Partial<JwkEd25519 | JwkEs256k> = { };
-
-    if ('crv' in key) {
-      ionJwk.crv = key.crv;
-      ionJwk.kty = key.kty;
-      ionJwk.x = key.x;
-      if ('d' in key) ionJwk.d = key.d;
-
-      if ('y' in key && key.y) {
-        // secp256k1 JWK.
-        return { ...ionJwk, y: key.y} as JwkEs256k;
-      }
-      // Ed25519 JWK.
-      return { ...ionJwk } as JwkEd25519;
-    }
-
-    throw new Error(`jwkToIonJwk: Unsupported key algorithm.`);
-  }
-}