`@synanetics/interweave-audit-client`

Generates FHIR AuditEvents in line with the Interweave Specification

Description

A client for generating AuditEvents for DataConsumers in the Interweave ecosystem, according to the specification, which can be found at the following address: https://interweavedigital.com/wp-content/uploads/2024/06/YHCR-Design-Paper-009.-Auditing-v1.3.pdf. The client generates and sends the AuditEvents to the configured endpoint. The core AuditEvent generation functionality has been abstracted into a separate class, and concrete implementations are responsible for the submission of the event, so that HTTP and NATS clients can use the same event generation logic, whilst managing their own submissions.

Intended usage pattern

An Organization exists in an Interweave region. The Organization has both a DataConsumer and a DataProvider registered in the region's Exchange/PIX. The auditable events generated by the DataConsumer are sent to its corresponding DataProvider, so that they can be queried/reported upon, without the need for the DataConsumer to host its own AuditEvent service.

Unsupport features

Local authentication event generation (YHCR0101)

Supported features

Regional IAM authentication event generation (YHCR0102)
Search result response event generation (YHCR0302)
HTTP event submission
NATS event submission (to a Connect appliance's "audit" Moleculer service)
GCP PubSub queue topic submission

Usage

import { HttpAuditEventClient } from '@synanetics/interweave-audit-client';

const client =  new HttpAuditEventClient({
  url: 'https://data-consumer.fhir.nhs.uk/AuditEvent',
  odsCode: 'ABC01',
  dataConsumer: {
    name: 'ABC NHS Trust',
    identifier: [{
      code: 'participant01',
      system: 'https://yhcr.nhs.uk/Id/participant-id',
    }]
  }
});

const jwt = {
  sub: '...',
  // other claims
}

const tokenResponse = await fetch('http://iam.server.com', { body: JSON.stringify(jwt) });

const auditEventResponse = await client.submitAuthenticationEvent({
  response: tokenResponse,
  jwt,
  requestUrl: 'http://iam.server.com',
});

// auditEventResponse will be the result of submitting the AuditEvent to the server, usually an
// AuditEvent FHIR resource.

BigQuery Gotchas

The GCP PubSub client is intended to publish to a topic that BigQuery subscribes to. During the development phase, the following issues were discovered:

When associating a Topic to a BigQuery Subscription and selecting the "use table schema" option, this will respect the required/nullable status of each of the columns, meaning you won't be able to leave out "LastUpdated", for example, from your BigQuery writes (they will silently fail). As such, the BigQuery schema should have any fields that need to be defaulted temporarily set to nullable whilst the Subscription is being created.
"JSON" type BigQuery columns need to be stringified, otherwise inserts silently fail.