feat(protect): audit logging

[calvinbrewer]

The .audit interface is a method available on all Protect.js operations.
It allows you to attach arbitrary metadata to the operation for ZeroKMS audit logging purposes.

Usage example:

  const plaintext = await protectClient.decrypt(ciphertext.data).audit({
    metadata: {
      user: 'cj@cjb.io',
      action: 'read',
      requestId: 'abc-123',
    },
  })

The metadata object can contain any key-value pairs you wish to associate with the operation.
This metadata will be included in the ZeroKMS audit logs.

The .audit() method is chainable and does not affect the result of the operation itself.

[freshtonic]

@cj does this mean no auditing happens at all on decryption if .audit is skipped, or is .audit for additional metadata?

[engineforce]

LGTM

[auxesis]

does this mean no auditing happens at all on decryption if .audit is skipped, or is .audit for additional metadata?

@freshtonic .audit is only for additional user-supplied metadata.

ZeroKMS will still produce logs for key generation and retrieval operations, regardless of the call to .audit.

[coderdan]

This is great!

I wonder if it might be clearer to name the method auditContext or something? This would communicate that the method is to supply additional information for the audit log rather than it being required for auditing to take place. What do you think @calvinbrewer?