LGTM!

I had to dismiss all approvals as we need a way to know how the key was derived in some scenarios.

For this reason, in most of the functions, instead of accepting / returning a CryptoKey we'll return an EncryptionKey object, which has this shape:

export type EncryptionKey = {
  key: CryptoKey; // this might change in the future for other, more generic, types
  derivationFunction: KeyDerivationOptions;
};

export type KeyDerivationOptions = {
  algorithm: 'PBKDF2'; // this can easily become an enum in the future
  params: PBKDF2Params; // ..and this a union type, depending on `algorithm`
};

export type PBKDF2Params = {
  iterations?: number;
  exportable?: boolean;
};

And keyMetadata field (which reports the same object of derivationFunction) has been added also to the encryption result object:

export type EncryptionResult = {
  data: string;
  iv: string;
  salt?: string;
  // old encryption results will not have this
  keyMetadata?: KeyDerivationOptions;
};

Finally, instead of adding a single iterations argument to keyFromPassword function, the function has now this signature:

keyFromPassword(
  password: string,
  salt: string,
  opts: KeyDerivationOptions = {
    algorithm: 'PBKDF2',
    params: {
      iterations: 900_000,
      exportable: false,
    },
  },
): Promise<EncryptionKey>;

This allows:

1. The client to choose the preferred algorithm and parameters
2. To easily extend this in the future with other algorithms and parameters

Changes in f10e866 are needed to carry derivation function metadata in the exported key and to expect them (in new cases) when importing it.

While I do acknowledge the benefit of having easy backwards compatibility, I am worried about the longer term technical debt this may incur. Given we are adding additional guards, conditions, and migrated tests to support two kinds of inputs for each operation, many of the the functions now require additional context on the various support cases to be modified effectively in the future.

IMO this is a case where I think verbosity may be better than the neatness of minimizing bundle size, as software bugs here can result in a bit more severe behaviour. Especially since a majority of the conditions are only relevant on that first migration.

What are your thoughts on this:

1. We denote this as being a breaking change and define a migration guide for developers who wish to update to this breaking change version.
2. Alongside the guide, we provide a transformation function which will take in the encrypted data, and transform it into the format we expect. Notably, adding the key argument, and adding the previous parameters that we used to use for the PBKDF2 function. This function will be a no-op if the vault is already migrated.
3. Consumers of this package will simply call the transformation function after they've loaded their vault, but before they interact with the updated interface.

In the MetaMask extension, this can be done with a migration, in other clients, they can use their own strategy, or simply call this each time their vault is loaded as it will later get saved with the new updated parameters.

This will remove all the additional complexity from these functions leaving them simple to understand and build on in the future without worry of breaking vault compatibility.

I have some other comments besides this but I will save that for another comment so it is more easily quotable. A lot of these comments are just about the tests.

One final thing, but this otherwise looks good to me.

LGTM!

LGTM!