@digigov-oss/gsis-audit-record-db

AuditRecordDB

According to Common Guide for Client Applications of GSIS, (https://www.gsis.gr/dimosia-dioikisi/ked/koinos-odigos) all online services are required to have the addition of tracking data (auditRecord) when calling them.

This module implements a JSON file storage database for use with the audit mechanism of GSIS. It follows the interoperability_specsv1.4 and simplifies the integration with Nextjs/Nodejs projects.

It also provides a way for automating protocol numbers and transactions Id's, if your app does not provide them.

Note: FileEngine, used in the examples below, is intended for development and testing only. Production deployments should use a real database engine, for example PostgreSqlEngine. See AuditEngine.

See CHANGELOG.md for release notes, including the breaking changes in 2.0.0.

Usage

import auditRecordDB from 'AuditRecordDB';

const main = () =>{
   //returns generated AuditRecord, stored by default in `/tmp` using `FileEngine`
   //`FileEngine` is for development only, use e.g. `PostgreSqlEngine` in production
   console.log(auditRecordDB({auditUnit:'DigiGov'}))
   /*
   {
    auditUnit: 'DigiGov',
    auditTransactionId: '1',
    auditProtocol: '1/2022-01-01',
    auditTransactionDate: '2022-01-01T00:00:01Z',
    auditUserIp: '127.0.0.1',
    auditUserId: 'system'
   }
   */
}

//you can change the FileEngine storage path
//use a dedicated directory owned by the service account, not a shared one
import auditRecordDB,{FileEngine} from 'AuditRecordDB';
const main = () =>{
console.log(auditRecordDB({},new FileEngine('/var/lib/my-service/audit')))
}

//you can change the protocol reset sequence type
import auditRecordDB,{FileEngine} from 'AuditRecordDB';
const main = () =>{
console.log(auditRecordDB({},new FileEngine(undefined, 'daily')))
}

AuditEngine

By default, the file storage engine FileEngine is used.

FileEngine is a simple JSON file storage engine that stores the audit records on the local filesystem. It is intended for development, testing and single-process use only: it does not provide the durability, concurrency, retention or access-control guarantees of a database, and its locking is local to the host. Do not use it in production.

If FileEngine has to be used anyway, do not leave it on the shared /tmp default. Pass a dedicated directory that only the service account can access, for example /var/lib/<service>/audit with mode 0700. The engine creates record files, sequence files and lock files with mode 0600, but it does not create the directory or change its permissions, so the directory itself must be provisioned correctly.

For production, use a real database engine. The PostgreSQL implementation is provided by the @digigov-oss/auditrecord-postgresql-engine module as PostgreSqlEngine, for example:

import auditRecordDB from 'AuditRecordDB';
import { PostgreSqlEngine } from '@digigov-oss/auditrecord-postgresql-engine';

const main = async () => {
  console.log(await auditRecordDB({auditUnit:'DigiGov'}, new PostgreSqlEngine(/* connection settings */)))
}

If you do not provide protocol numbers, the module will generate them for you. You can pass at the engine the type of protocol number reset you want to use from one of the following: "daily", "monthly", "yearly". By default, innumerable protocol numbers are generated.

Look at FileEngine.ts here and PostgreSqlEngine.ts of the @digigov-oss/auditrecord-postgresql-engine module for examples to extend the store to another 'real' database.