@dwn-protocol/id-sdk 0.2.5 → 0.2.6

package/src/agent/types/managed-key.ts

@@ -1,442 +0,0 @@
-import type { IDCrypto } from '../../crypto/index.js';
-import type { RequireOnly } from '../../common/index.js';
-
-import { IDManagedAgent } from './agent.js';
-
-export interface CryptoManager {
-  agent: IDManagedAgent;
-
-  decrypt(options: DecryptOptions): Promise<Uint8Array>;
-
-  deriveBits(options: DeriveBitsOptions): Promise<Uint8Array>;
-
-  encrypt(options: EncryptOptions): Promise<Uint8Array>;
-
-  /**
-   * Generate a new ManagedKey within a CryptoManager implementation.
-   */
-  generateKey<T extends GenerateKeyOptionTypes>(options: GenerateKeyOptions<T>): Promise<GenerateKeyType<T>>;
-
-  /**
-   * Retrieves detailed information about a ManagedKey or ManagedKeyPair object.
-   *
-   * @param options - The options for retrieving the key.
-   * @param options.keyRef - The reference identifier for the key. Can specify the id or alias property of the key.
-   * @returns A promise that resolves to either a ManagedKey or ManagedKeyPair object.
-   */
-  getKey(options: { keyRef: string }): Promise<ManagedKey | ManagedKeyPair | undefined>;
-
-  importKey(options: PortableKeyPair): Promise<ManagedKeyPair>;
-  importKey(options: PortableKey): Promise<ManagedKey>;
-  importKey(options: ImportKeyOptions): Promise<ManagedKey | ManagedKeyPair>;
-
-  sign(options: SignOptions): Promise<Uint8Array>;
-
-  updateKey(options: UpdateKeyOptions): Promise<boolean>;
-
-  verify(options: VerifyOptions): Promise<boolean>;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface
- * {@link CryptoManager.encrypt | encrypt} method.
- *
- * @public
- */
-export type DecryptOptions = {
-  /**
-   * An object defining the cipher algorithm to use and its parameters.
-   */
-  algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.AesCtrOptions | IDCrypto.AesGcmOptions;
-
-  /**
-   * A Uint8Array object containing the data to be decrypted
-   * (also known as the ciphertext).
-   */
-  data: Uint8Array;
-
-  /**
-   * An identifier of the ManagedKey to be used for decryption.
-   * You can use the id or alias property of the key.
-   */
-  keyRef: string;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface
- * {@link CryptoManager.deriveBits | deriveBits} method.
- *
- * @public
- */
-export type DeriveBitsOptions = {
-
-  /**
-   * An object defining the derivation algorithm to use and its parameters.
-   */
-  // algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.EcdhDeriveKeyOptions;
-  algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.EcdhDeriveKeyOptions | IDCrypto.Pbkdf2Options;
-  /**
-   * An identifier of the ManagedKey that will be the input to the
-   * derivation algorithm.
-   *
-   * If the algorithm is ECDH, this identifier will refer to an ECDH key pair.
-   * For PBKDF2, it might be a password.
-   * For HDKF, it might be the shared secret output of an ECDH key agreement operation.
-   */
-  baseKeyRef: string;
-
-  /**
-   * A number representing the number of bits to derive. To be compatible with
-   * all browsers, the number should be a multiple of 8.
-   */
-  length?: number;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface
- * {@link CryptoManager.encrypt | encrypt} method.
- *
- * @public
- */
-export type EncryptOptions = {
-  /**
-   * An object defining the cipher algorithm to use and its parameters.
-   */
-  algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.AesCtrOptions | IDCrypto.AesGcmOptions;
-
-  /**
-   * An Uint8Array object containing the data to be encrypted
-   * (also known as the plaintext).
-   */
-  data: Uint8Array;
-
-  /**
-   * An identifier of the ManagedKey to be used for encryption.
-   * You can use the id or alias property of the key.
-   */
-  keyRef: string;
-}
-
-export type GenerateKeyOptions<T extends GenerateKeyOptionTypes> = {
-  algorithm: T;
-  alias?: string;
-  extractable?: boolean;
-  keyUsages: IDCrypto.KeyUsage[];
-  metadata?: KeyMetadata;
-};
-
-export type GenerateKeyOptionTypes =
-  | IDCrypto.AlgorithmIdentifier
-  // | RsaHashedGenerateKeyOptions
-  | IDCrypto.AesGenerateKeyOptions
-  | IDCrypto.EcdsaGenerateKeyOptions
-  | IDCrypto.EdDsaGenerateKeyOptions
-  // | HmacGenerateKeyOptions
-  // | Pbkdf2Params;
-
-export type GenerateKeyType<T> = T extends IDCrypto.EcGenerateKeyOptions ? ManagedKeyPair :
-  T extends IDCrypto.AesGenerateKeyOptions /*| HmacGenerateKeyOptions | Pbkdf2Params*/ ? ManagedKey :
-  T extends IDCrypto.AlgorithmIdentifier ? ManagedKey | ManagedKeyPair :
-  never;
-
-export type PortableKey =
-  RequireOnly<
-    ManagedKey,
-    'algorithm' | 'extractable' | 'type' | 'usages',
-    'id' | 'material' | 'state'
-  >
-  & { material: Uint8Array; };
-
-export interface PortableKeyPair {
-  privateKey: PortableKey;
-  publicKey: PortableKey;
-}
-
-export type ImportKeyOptions =
-  | PortableKey
-  | PortableKeyPair
-
-/**
- * Base interface to be implemented by key management systems.
- */
-export type KeyManagementSystem = CryptoManager;
-
-/**
- * KeyMetadata
- *
- * Implementations of KeyManagementSystem can populate this object with KMS platform
- * specific data about each key.
- *
- * This property can also be used to add various tags to the keys under management.
- */
-export type KeyMetadata = {
-  /**
-   * Additional properties of any type.
-   */
-  [key: string]: any;
-}
-
-/**
- * KeyState
- *
- * The read-only `state` property of the `ManagedKey` interface indicates the
- * status of the ManagedKey.
- *
- * It can have the following string values:
- *
- *   "Enabled": The key is ready for use.
- *
- *   "Disabled": The key may not be used, but the key material is still available,
- *               and the key can be placed back into the Enabled state.
- *
- *   "PendingCreation": The key is still being created. It may not be used,
- *                      enabled, disabled, or destroyed yet.  The KMS will
- *                      automatically change the state to enabled as soon
- *                      as the key is ready.
- *
- *   "PendingDeletion": The key is scheduled for deletion. It can be placed back
- *                      into the Disabled state up until the time of deletion
- *                      using the CancelKeyDeletion() method. Once the key has
- *                      been deleted, any ciphertext encrypted with this key
- *                      is no longer recoverable. Minimum and maximum waiting
- *                      periods are defined by each KMS implementation.
- *
- *   "PendingImport": The key is still being imported. It may not be used, enabled,
- *                    disabled, or deleted yet. The KMS will automatically change
- *                    the state to Enabled once the key is ready.
- *
- *   "PendingUpdate": The key is still being updated. It may not be used, enabled,
- *                    disabled, or deleted until the update process completes.
- *                    The KMS will automatically change the state to Enabled
- *                    once the key is ready.
- */
-export type KeyState = 'Enabled' | 'Disabled' | 'PendingCreation' | 'PendingDeletion' | 'PendingImport' | 'PendingUpdate';
-
-/**
- * ManagedKey
- *
- * A ManagedKey represents a cryptographic key used by a cipher for
- * encryption or decryption or an algorithm for signing or verification.
- */
-export interface ManagedKey {
-  /**
-   * A unique identifier for the Key, autogenerated by a KMS.
-   */
-  id: string;
-
-  /**
-   * An object detailing the algorithm for which the key can be used along
-   * with additional algorithm-specific parameters.
-   */
-  // algorithm: IDCrypto.GenerateKeyOptions;
-  algorithm: IDCrypto.KeyAlgorithm | IDCrypto.GenerateKeyOptions;
-  /**
-   * An alternate identifier used to identify the key in a KMS.
-   * This property can be used to associate a DID document key ID with a ManagedKey.
-   */
-  alias?: string;
-
-  /**
-   * A boolean value that is `true` if the key can be exported and `false` if not.
-   */
-  extractable: boolean;
-
-  /**
-   * Name of a registered key management system.
-   */
-  kms: string;
-
-  /**
-   * Key material as a raw binary data buffer.
-   */
-  material?: Uint8Array;
-
-  /**
-   * Optional. Additional Key metadata.
-   */
-  metadata?: KeyMetadata;
-
-  /**
-   * A registered string value specifying the algorithm and any algorithm
-   * specific parameters.
-   * Supported algorithms vary by KMS.
-   */
-  spec?: string;
-
-  /**
-   * The current status of the ManagedKey.
-   */
-  state: KeyState;
-
-  /**
-   * The type of key.
-   */
-  type: IDCrypto.KeyType;
-
-  /**
-   * Indicates which cryptographic operations are permissible to be used with this key.
-   */
-  usages: IDCrypto.KeyUsage[];
-}
-
-/**
- * Represents information about a managed key.
- * Private or secret key material is NOT present.
- *
- */
-export type ManagedKeyInfo = Omit<ManagedKey, 'material'>;
-
-export type ManagedKeyOptions = Omit<ManagedKey, 'toJwk'>
-
-/** ManagedKeyPair
- *
- * A ManagedKeyPair represents a key pair for an asymmetric cryptography algorithm,
- * also known as a public-key algorithm.
- *
- * A ManagedKeyPair object can be obtained using `generateKey()`, when the
- * selected algorithm is one of the asymmetric algorithms: ECDSA or ECDH.
- */
-export interface ManagedKeyPair {
-  /**
-   * A ManagedKey object representing the private key. For encryption and
-   * decryption algorithms, this key is used to decrypt. For signing and
-   * verification algorithms it is used to sign.
-   */
-  privateKey: ManagedKey;
-
-  /**
-   * A ManagedKey object representing the public key. For encryption and
-   * decryption algorithms, this key is used to encrypt. For signing and
-   * verification algorithms it is used to verify signatures.
-   */
-  publicKey: ManagedKey;
-}
-
-/**
- * ManagedKeyStore
- *
- * This interface should be implemented to provide platform specific
- * implementations that are usable by KeyManager and implementations
- * of KeyManagementSystem.
- *
- * Implementations of this class can be used to store:
- *   ManagedKey and ManagedKeyPair
- * or:
- *   ManagedPrivateKey
- * objects.
- *
- * @public
- */
-export interface ManagedKeyStore<K, V> {
-  deleteKey(options: { id: K, agent?: IDManagedAgent, context?: string }): Promise<boolean>
-  findKey(options: { id: K, agent?: IDManagedAgent, context?: string }): Promise<V | undefined>;
-  findKey(options: { alias: K, agent?: IDManagedAgent, context?: string }): Promise<V | undefined>;
-  getKey(options: { id: K, agent?: IDManagedAgent, context?: string }): Promise<V | undefined>
-  importKey(options: { key: Omit<V, 'id'>, agent?: IDManagedAgent, context?: string }): Promise<K>
-  listKeys(options?: { agent?: IDManagedAgent, context?: string }): Promise<V[]>
-  updateKey(options: { id: K, agent?: IDManagedAgent, context?: string } & Partial<V>): Promise<boolean>
-}
-
-/**
- * Represents a private key.
- *
- * The `alias` is used to refer to the key material which is stored as the hex encoding of the raw byte array
- * (`privateKeyHex`).
- *
- * The `type` refers to the type of key that is represented.
- *
- * @public
- */
-export interface ManagedPrivateKey {
-  /**
-   * A unique identifier for the Key, autogenerated by a KMS.
-   */
-  id: string
-
-  /**
-   * Key material as raw binary data.
-   */
-  material: Uint8Array;
-
-  /**
-   * The type of key.
-   */
-  type: IDCrypto.PrivateKeyType;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface {@link CryptoManager.sign | sign} method.
- *
- * @public
- */
-export type SignOptions = {
-  /**
-   * An object that specifies the signature algorithm to use and its parameters.
-   */
-  algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.EcdsaOptions | IDCrypto.EdDsaOptions;
-
-  /**
-   * An Uint8Array object containing the data to be signed.
-   */
-  data: Uint8Array;
-
-  /**
-   * An identifier of the ManagedKey to sign with.
-   * You can use the id or alias property of the key.
-   */
-  keyRef: string;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface
- * {@link CryptoManager.updateKey | updateKey} method.
- *
- * @public
- */
-export type UpdateKeyOptions = {
-  /**
-   * An alternate identifier used to identify the key in a KMS.
-   * This property can be used to associate a DID document key ID with a ManagedKey.
-   */
-  alias?: string;
-
-  /**
-   * An identifier of the ManagedKey to be used for decryption.
-   * You can use the id or alias property of the key.
-   */
-  keyRef: string;
-
-  /**
-   * Optional. Additional Key metadata.
-   */
-  metadata?: KeyMetadata;
-}
-
-/**
- * Input arguments for implementations of the CryptoManager interface
- * {@link CryptoManager.verify | verify} method.
- *
- * @public
- */
-export type VerifyOptions = {
-  /**
-   * An object that specifies the algorithm to use and its parameters.
-   */
-  algorithm: IDCrypto.AlgorithmIdentifier | IDCrypto.EcdsaOptions | IDCrypto.EdDsaOptions;
-
-  /**
-   * An Uint8Array object containing the data whose signature is to be verified.
-   */
-  data: Uint8Array;
-
-  /**
-   * An identifier of the ManagedKey to sign with.
-   * You can use the id or alias property of the key.
-   */
-  keyRef: string;
-
-  /**
-   * A Uint8Array containing the signature to verify.
-   */
-  signature: Uint8Array;
-}

package/src/agent/utils.ts

@@ -1,190 +0,0 @@
-import type { JsonWebKey, IDCrypto } from '../crypto/index.js';
-
-import { Jose } from '../crypto/index.js';
-import { RequireOnly } from '../common/index.js';
-import { Readable } from 'readable-stream';
-import { ReadableWebToNodeStream } from 'readable-web-to-node-stream';
-
-import { ManagedKey, ManagedKeyPair, PortableKey, PortableKeyPair } from './types/managed-key.js';
-
-export function blobToIsomorphicNodeReadable(blob: Blob): Readable {
-  return webReadableToIsomorphicNodeReadable(blob.stream() as ReadableStream<any>);
-}
-
-export function cryptoToManagedKey(options: {
-  cryptoKey: IDCrypto.CryptoKey,
-    keyData: RequireOnly<ManagedKey, 'kms'>
-  }): ManagedKey {
-  const { cryptoKey, keyData } = options;
-
-  const managedKey: ManagedKey = {
-    id          : keyData.id ?? '',
-    algorithm   : cryptoKey.algorithm,
-    alias       : keyData.alias,
-    extractable : cryptoKey.extractable,
-    kms         : keyData.kms,
-    material    : (cryptoKey.type === 'public') ? cryptoKey.material : undefined,
-    metadata    : keyData.metadata,
-    state       : 'Enabled',
-    type        : cryptoKey.type,
-    usages      : cryptoKey.usages
-  };
-
-  return managedKey;
-}
-
-export function cryptoToManagedKeyPair(options: {
-  cryptoKeyPair: IDCrypto.CryptoKeyPair,
-    keyData: RequireOnly<ManagedKey, 'kms' | 'state'>
-  }): ManagedKeyPair {
-  const { cryptoKeyPair, keyData } = options;
-
-  const privateKey = cryptoKeyPair.privateKey;
-  const publicKey = cryptoKeyPair.publicKey;
-
-  const managedKeyPair = {
-    privateKey: {
-      id          : keyData.id ?? '',
-      algorithm   : privateKey.algorithm,
-      alias       : keyData.alias,
-      extractable : privateKey.extractable,
-      kms         : keyData.kms,
-      metadata    : keyData.metadata,
-      state       : keyData.state,
-      type        : privateKey.type,
-      usages      : privateKey.usages
-    },
-
-    publicKey: {
-      id          : keyData.id ?? '',
-      algorithm   : publicKey.algorithm,
-      alias       : keyData.alias,
-      extractable : publicKey.extractable,
-      kms         : keyData.kms,
-      material    : publicKey.material,
-      metadata    : keyData.metadata,
-      state       : keyData.state,
-      type        : publicKey.type,
-      usages      : publicKey.usages
-    },
-  };
-
-  return managedKeyPair;
-}
-
-export function cryptoToPortableKey(options: {
-  cryptoKey: IDCrypto.CryptoKey,
-    keyData: RequireOnly<ManagedKey, 'kms'>
-  }): PortableKey {
-  const { cryptoKey, keyData } = options;
-
-  const portableKey = {
-    id          : keyData.id ?? '',
-    algorithm   : cryptoKey.algorithm,
-    alias       : keyData.alias,
-    extractable : cryptoKey.extractable,
-    kms         : keyData.kms,
-    material    : cryptoKey.material,
-    metadata    : keyData.metadata,
-    type        : cryptoKey.type,
-    usages      : cryptoKey.usages
-  };
-
-  return portableKey;
-}
-
-export function cryptoToPortableKeyPair(options: {
-  cryptoKeyPair: IDCrypto.CryptoKeyPair,
-    keyData: RequireOnly<ManagedKey, 'kms'>
-  }): PortableKeyPair {
-  const { cryptoKeyPair, keyData } = options;
-
-  const privateKey = cryptoKeyPair.privateKey;
-  const publicKey = cryptoKeyPair.publicKey;
-
-  const portableKeyPair = {
-    privateKey: {
-      id          : keyData.id ?? '',
-      algorithm   : privateKey.algorithm,
-      alias       : keyData.alias,
-      extractable : privateKey.extractable,
-      kms         : keyData.kms,
-      material    : privateKey.material,
-      metadata    : keyData.metadata,
-      type        : privateKey.type,
-      usages      : privateKey.usages
-    },
-
-    publicKey: {
-      id          : keyData.id ?? '',
-      algorithm   : publicKey.algorithm,
-      alias       : keyData.alias,
-      extractable : publicKey.extractable,
-      kms         : keyData.kms,
-      material    : publicKey.material,
-      metadata    : keyData.metadata,
-      type        : publicKey.type,
-      usages      : publicKey.usages
-    },
-  };
-
-  return portableKeyPair;
-}
-
-/**
- * Type guard function to check if the given key is a ManagedKey.
- *
- * @param key The key to check.
- * @returns True if the key is a ManagedKeyPair, false otherwise.
- */
-export function isManagedKey(key: ManagedKey | ManagedKeyPair | undefined): key is ManagedKey {
-  return key !== undefined && 'algorithm' in key && 'extractable' in key && 'type' in key && 'usages' in key;
-}
-
-/**
- * Type guard function to check if the given key is a ManagedKeyPair.
- *
- * @param key The key to check.
- * @returns True if the key is a ManagedKeyPair, false otherwise.
- */
-export function isManagedKeyPair(key: ManagedKey | ManagedKeyPair | undefined): key is ManagedKeyPair {
-  return key !== undefined && 'privateKey' in key && 'publicKey' in key;
-}
-
-export async function managedKeyToJwk({ key }: {
-  key: RequireOnly<ManagedKey, 'algorithm' | 'extractable' | 'material' | 'type' | 'usages'>
-}): Promise<JsonWebKey> {
-  if (key.material === undefined) {
-    throw new Error(`Could not convert to JWK: 'material' is undefined.`);
-  }
-
-  const cryptoKey: IDCrypto.CryptoKey = {
-    algorithm   : key.algorithm,
-    extractable : key.extractable,
-    material    : key.material,
-    type        : key.type,
-    usages      : key.usages
-  };
-
-  const jwk = await Jose.cryptoKeyToJwk({ key: cryptoKey });
-
-  return jwk;
-}
-
-export function managedToCryptoKey({ key }: {
-  key: RequireOnly<ManagedKey, 'algorithm' | 'extractable' | 'material' | 'type' | 'usages'>
-}): IDCrypto.CryptoKey {
-  const cryptoKey: IDCrypto.CryptoKey = {
-    algorithm   : key.algorithm,
-    extractable : key.extractable,
-    material    : key.material,
-    type        : key.type,
-    usages      : key.usages
-  };
-
-  return cryptoKey;
-}
-
-export function webReadableToIsomorphicNodeReadable(webReadable: ReadableStream<any>) {
-  return new ReadableWebToNodeStream(webReadable);
-}