@cap-js/audit-logging 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,7 +4,24 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 0.7.0 - tbd
+## Version 0.8.1 - 2024-09-13
+
+### Fixed
+
+- Support for @sap/cds^8.2
+- Reduce clutter in error raised for outbound requests
+
+## Version 0.8.0 - 2024-05-24
+
+### Added
+
+- Allow to specify undefined tenant in order to log to provider account in multi-tenant scenarios
+
+### Changed
+
+- Use kind `audit-log-to-restv2` in profile `hybrid`
+
+## Version 0.7.0 - 2024-05-15
 
 ### Added
 

package/README.md

@@ -1,26 +1,142 @@
 # Welcome to @cap-js/audit-logging
-[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/audit-logging)](https://api.reuse.software/info/github.com/cap-js/audit-logging)
 
-## About this project
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/audit-logging)](https://api.reuse.software/info/github.com/cap-js/audit-logging)
 
 `@cap-js/audit-logging` is a CDS plugin providing integration to the SAP Audit Log service as well as out-of-the-box personal data-related audit logging based on annotations.
 
-Documentation can be found at [cap.cloud.sap](https://cap.cloud.sap/docs/guides/data-privacy).
+Documentation can be found at [cap.cloud.sap](https://cap.cloud.sap/docs/guides/data-privacy). 
+
+> [!IMPORTANT]
+> The information in this file is by no means complete but enables you to get started quickly. Make sure to read the provided documentation at [cap.cloud.sap](https://cap.cloud.sap/docs/guides/data-privacy) to get the full picture. 
+
+
+## Preliminaries
+
+In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base to add change tracking to. Clone the repository and apply the step-by-step instructions:
+
+```sh
+git clone https://github.com/cap-js/incidents-app
+cd incidents-app
+npm i
+```
+
+
+## Setup
+
+To enable audit logging, simply add this self-configuring plugin package to your project:
+
+```sh
+npm add @cap-js/audit-logging
+```
+
+
+## Annotate Personal Data
+
+Identify entities and elements (potentially) holding personal data using `@PersonalData` annotations. Create a `db/data-privacy.cds` file and add the following:
+
+```cds
+using { sap.capire.incidents as my } from './schema';
+
+annotate my.Customers with @PersonalData : {
+  DataSubjectRole : 'Customer',
+  EntitySemantics : 'DataSubject'
+} {
+  ID           @PersonalData.FieldSemantics: 'DataSubjectID';
+  firstName    @PersonalData.IsPotentiallyPersonal;
+  lastName     @PersonalData.IsPotentiallyPersonal;
+  email        @PersonalData.IsPotentiallyPersonal;
+  phone        @PersonalData.IsPotentiallyPersonal;
+  creditCardNo @PersonalData.IsPotentiallySensitive;
+};
 
-## Requirements
+annotate my.Addresses with @PersonalData: {
+  EntitySemantics : 'DataSubjectDetails'
+} {
+  customer      @PersonalData.FieldSemantics: 'DataSubjectID';
+  city          @PersonalData.IsPotentiallyPersonal;
+  postCode      @PersonalData.IsPotentiallyPersonal;
+  streetAddress @PersonalData.IsPotentiallyPersonal;
+};
 
-See [Getting Started](https://cap.cloud.sap/docs/get-started) on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model.
+annotate my.Incidents with @PersonalData : {
+  EntitySemantics : 'Other'
+} {
+  customer @PersonalData.FieldSemantics: 'DataSubjectID';
+};
+
+```
+Learn more about the annotations in capire:
+- [@PersonalData.EntitySemantics](https://cap.cloud.sap/docs/guides/data-privacy/annotations#entitysemantics)
+- [@PersonalData.EntitySemantics: 'DataSubject'](https://cap.cloud.sap/docs/guides/data-privacy/annotations#datasubjectrole)
+- [@PersonalData.FieldSemantics: 'DataSubjectID'](https://cap.cloud.sap/docs/guides/data-privacy/annotations#fieldsemantics-datasubjectid)
+- [@PersonalData.IsPotentiallyPersonal](https://cap.cloud.sap/docs/guides/data-privacy/annotations#ispotentiallypersonal)
+- [@PersonalData.IsPotentiallySensitive](https://cap.cloud.sap/docs/guides/data-privacy/annotations#ispotentiallysensitive)
+
+
+## Test-Drive Locally
+
+You've prepared everything to log personal data-related events. Let's see that in action.
+
+Start the server as usual:
+```sh
+cds watch
+```
+
+Send an update request that changes personal data:
+```http
+PATCH http://localhost:4004/odata/v4/admin/Customers('1004155')
+Authorization: Basic alice:in-wonderland
+Content-Type: application/json
+
+{
+  "firstName": "Danny",
+  "lastName": "Joules"
+}
+```
+
+See the audit logs in the server's console output:
+```sh
+[audit-log] - PersonalDataModified: {
+  data_subject: {
+    id: { ID: '1004155' },
+    role: 'Customer',
+    type: 'AdminService.Customers'
+  },
+  object: {
+   type: 'AdminService.Customers',
+   id: { ID: '1004155' }
+  },
+  attributes: [
+    { name: 'firstName', old: 'Daniel', new: 'Danny' },
+    { name: 'lastName', old: 'Watts', new: 'Joules' }
+  ],
+  uuid: '71fa93d9-c993-405f-ba1b-a9ef42668199',
+  tenant: 't1',
+  user: 'alice',
+  time: 2023-02-26T08:13:48.287Z
+}
+```
+
+
+## In Production
 
 The end-to-end out-of-the-box functionality provided by this plugin requires a paid-for instance of the [SAP Audit Log service for customers](https://help.sap.com/docs/btp/sap-business-technology-platform/audit-log-write-api-for-customers?locale=en-US). However, it is possible to provide an own implementation that writes the audit logs to a custom store.
 
+[_Learn more about using the SAP Audit Log service._](https://cap.cloud.sap/docs/guides/data-privacy/audit-logging#use-sap-audit-log-service)
+
+[_Learn more about custom audit logging._](https://cap.cloud.sap/docs/guides/data-privacy/audit-logging#custom-audit-logging)
+
+
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/audit-logging/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
 
+
 ## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
 
+
 ## Licensing
 
 Copyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js/audit-logging).

package/lib/access.js

@@ -2,7 +2,6 @@ const cds = require('@sap/cds')
 
 // REVISIT: don't require internal stuff
 const getTemplate = require('@sap/cds/libx/_runtime/common/utils/template')
-const templateProcessor = require('@sap/cds/libx/_runtime/common/utils/templateProcessor')
 
 const {
   getRootEntity,
@@ -56,8 +55,16 @@ const auditAccess = async function (data, req) {
   if (!template.elements.size) return
 
   const accessLogs = {}
-  const _data = Array.isArray(data) ? data : [data]
-  _data.forEach(row => templateProcessor({ processFn: _processorFnAccess(accessLogs, this.model, req), row, template }))
+  const processFn = _processorFnAccess(accessLogs, this.model, req)
+  // cds internal templating mechanism api changed in 8.2.0 -> polyfill
+  if (!template.process) {
+    module.exports._templateProcessor ??= require('@sap/cds/libx/_runtime/common/utils/templateProcessor')
+    template.process = (data, processFn) => {
+      const _data = Array.isArray(data) ? data : [data]
+      _data.forEach(row => module.exports._templateProcessor({ processFn, row, template }))
+    }
+  }
+  template.process(data, processFn)
 
   for (const each of Object.keys(accessLogs)) if (!accessLogs[each].attributes.length) delete accessLogs[each]
   if (!Object.keys(accessLogs).length) return

package/lib/modification.js

@@ -2,7 +2,6 @@ const cds = require('@sap/cds')
 
 // REVISIT: don't require internal stuff
 const getTemplate = require('@sap/cds/libx/_runtime/common/utils/template')
-const templateProcessor = require('@sap/cds/libx/_runtime/common/utils/templateProcessor')
 
 const {
   getMapKeyForCurrentRequest,
@@ -166,7 +165,14 @@ const _getDataModificationLogs = (req, tx, diff, beforeWrite) => {
 
   const modificationLogs = {}
   const processFn = _processorFnModification(modificationLogs, tx.model, req, beforeWrite)
-  templateProcessor({ processFn, row: diff, template })
+  // cds internal templating mechanism api changed in 8.2.0 -> polyfill
+  if (!template.process) {
+    module.exports._templateProcessor ??= require('@sap/cds/libx/_runtime/common/utils/templateProcessor')
+    template.process = (data, processFn) => {
+      module.exports._templateProcessor({ processFn, row: data, template })
+    }
+  }
+  template.process(diff, processFn)
 
   return modificationLogs
 }

package/lib/utils.js

@@ -1,3 +1,5 @@
+const cds = require('@sap/cds')
+
 const WRITE = { CREATE: 1, UPDATE: 1, DELETE: 1 }
 
 const $hasPersonalData = Symbol('@cap-js/audit-logging:hasPersonalData')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/audit-logging",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "CDS plugin providing integration to the SAP Audit Log service as well as out-of-the-box personal data-related audit logging based on annotations.",
   "repository": "cap-js/audit-logging",
   "author": "SAP SE (https://www.sap.com)",
@@ -16,16 +16,16 @@
     "lint": "npx eslint .",
     "test": "npm run test-new-db && npm run test-old-db",
     "test-new-db": "CDS_ENV='better-sqlite' npx jest --silent",
-    "test-old-db": "npx jest --silent"
+    "test-old-db": "CDS_ENV='legacy-sqlite' npx jest --silent"
   },
   "peerDependencies": {
-    "@sap/cds": "^7"
+    "@sap/cds": ">=7"
   },
   "devDependencies": {
     "@cap-js/audit-logging": "file:.",
     "@cap-js/sqlite": "^1",
     "axios": "^1",
-    "eslint": "^8",
+    "eslint": "^9",
     "express": "^4",
     "jest": "^29",
     "sqlite3": "^5.1.6"
@@ -44,6 +44,9 @@
         "[development]": {
           "kind": "audit-log-to-console"
         },
+        "[hybrid]": {
+          "kind": "audit-log-to-restv2"
+        },
         "[production]": {
           "kind": "audit-log-to-restv2"
         }

package/srv/log2console.js

@@ -5,6 +5,7 @@ module.exports = class AuditLog2Console extends AuditLogService {
     this.on('*', function (req) {
       const { event, data } = req
 
+      // eslint-disable-next-line no-console
       console.log(`[audit-log] - ${event}:`, data)
     })
 

package/srv/log2restv2.js

@@ -93,6 +93,7 @@ module.exports = class AuditLog2RESTv2 extends AuditLogService {
     } else {
       url = this.options.credentials.url + PATHS.OAUTH2[path]
       data.tenant ??= this._provider //> if request has no tenant, stay in provider account
+      if (data.tenant === '$PROVIDER') data.tenant = this._provider
       headers.authorization = 'Bearer ' + (await this._getToken(data.tenant))
       data.tenant = data.tenant === this._provider ? '$PROVIDER' : '$SUBSCRIBER'
     }
@@ -153,12 +154,16 @@ async function _post(url, data, options) {
       const chunks = []
       res.on('data', chunk => chunks.push(chunk))
       res.on('end', () => {
+        const { statusCode, statusMessage } = res
         let body = Buffer.concat(chunks).toString()
         if (res.headers['content-type']?.match(/json/)) body = JSON.parse(body)
         if (res.statusCode >= 400) {
-          const err = new Error(res.statusMessage)
-          err.response = res
-          err.body = body
+          // prettier-ignore
+          const err = new Error(`Request failed with${statusMessage ? `: ${statusCode} - ${statusMessage}` : ` status ${statusCode}`}`)
+          err.request = { method: options.method, url, headers: options.headers, body: data }
+          if (err.request.headers.authorization)
+            err.request.headers.authorization = err.request.headers.authorization.split(' ')[0] + ' ***'
+          err.response = { statusCode, statusMessage, headers: res.headers, body }
           reject(err)
         } else {
           resolve(body)

package/srv/service.js

@@ -8,7 +8,8 @@ module.exports = class AuditLogService extends Base {
     this.before('*', req => {
       const { tenant, user, timestamp } = cds.context
       req.data.uuid ??= cds.utils.uuid()
-      req.data.tenant ??= tenant
+      // allows to specify undefined tenant in order to log to provider in multi-tenant scenarios
+      if (!('tenant' in req.data)) req.data.tenant = tenant
       req.data.user ??= user.id
       req.data.time ??= timestamp
     })