@cap-js/audit-logging 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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
+
+- Automatically promote entities that are associated with data subjects
+
 ## Version 0.6.0 - 2024-02-05
 
 ### Added

package/README.md

@@ -1,18 +1,125 @@
 # 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
-
 `@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 '../db/extensions';
+
+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/admin/Customers(8e2f2640-6866-4dcf-8f4d-3027aa831cad) HTTP/1.1
+Authorization: Basic alice:in-wonderland
+Content-Type: application/json
+
+{
+  "firstName": "Johnny",
+  "lastName": "Doey"
+}
+```
+
+See the audit logs in the server's console output:
+```sh
+{
+  data_subject: {
+    type: 'AdminService.Customers',
+    id: { ID: '8e2f2640-6866-4dcf-8f4d-3027aa831cad' },
+    role: 'Customer',
+  },
+  object: {
+   type: 'AdminService.Customers',
+   id: { ID: '8e2f2640-6866-4dcf-8f4d-3027aa831cad' }
+  },
+  attributes: [
+    { name: 'firstName', old: 'John', new: 'Johnny' },
+    { name: 'lastName', old: 'Doe', new: 'Doey' }
+  ],
+  user: 'alice',
+  tenant: 't1',
+  uuid: '1391A703E2CBE52E817269EC7527368C',
+  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).

package/cds-plugin.js

@@ -19,6 +19,20 @@ cds.on('served', services => {
     for (const entity of service.entities) if (hasPersonalData(entity)) relevantEntities.push(entity)
     if (!relevantEntities.length) continue
 
+    // automatically promote entities that are associated with data subjects
+    for (const entity of relevantEntities) {
+      if (entity['@PersonalData.EntitySemantics'] !== 'DataSubject') continue
+      for (const e of service.entities) {
+        for (const k in e.associations) {
+          if (e.associations[k].target === entity.name && k !== 'SiblingEntity') {
+            e['@PersonalData.EntitySemantics'] ??= 'Other'
+            e.associations[k]['@PersonalData.FieldSemantics'] ??= 'DataSubjectID'
+            if (!relevantEntities.includes(e)) relevantEntities.push(e)
+          }
+        }
+      }
+    }
+
     for (const entity of relevantEntities) {
       /*
        * data access

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/audit-logging",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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)",
@@ -19,7 +19,7 @@
     "test-old-db": "npx jest --silent"
   },
   "peerDependencies": {
-    "@sap/cds": "^7"
+    "@sap/cds": ">=7 || ^8.0.0-beta"
   },
   "devDependencies": {
     "@cap-js/audit-logging": "file:.",
@@ -44,6 +44,9 @@
         "[development]": {
           "kind": "audit-log-to-console"
         },
+        "[hybrid]": {
+          "kind": "audit-log-to-restv2"
+        },
         "[production]": {
           "kind": "audit-log-to-restv2"
         }

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'
     }

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
     })