@cap-js/audit-logging 1.2.0 → 1.2.2

package/README.md

@@ -4,11 +4,10 @@
 
 `@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. 
-
+> 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
 
@@ -20,7 +19,6 @@ cd incidents-app
 npm i
 ```
 
-
 ## Setup
 
 To enable audit logging, simply add this self-configuring plugin package to your project:
@@ -29,7 +27,6 @@ To enable audit logging, simply add this self-configuring plugin package to your
 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:
@@ -65,24 +62,27 @@ annotate my.Incidents with @PersonalData : {
 };
 
 ```
+
 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
@@ -95,6 +95,7 @@ Content-Type: application/json
 ```
 
 See the audit logs in the server's console output:
+
 ```sh
 [audit-log] - PersonalDataModified: {
   data_subject: {
@@ -117,26 +118,22 @@ See the audit logs in the server's console output:
 }
 ```
 
-
 ## 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)
+[_Learn more about using the SAP Audit Log service._](https://cap.cloud.sap/docs/guides/security/dpp-audit-logging#use-sap-audit-log-service)
 
+[_Learn more about custom audit logging._](https://cap.cloud.sap/docs/guides/security/dpp-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/cds-plugin.js

@@ -5,7 +5,7 @@ const {
   addDiffToCtx,
   calcModLogs4Before,
   calcModLogs4After,
-  emitModLogs,
+  emitModLogs
 } = require("./lib/modification");
 const { hasPersonalData } = require("./lib/utils");
 
@@ -30,13 +30,9 @@ cds.on("served", (services) => {
       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"
-          ) {
+          if (e.associations[k].target === entity.name && k !== "SiblingEntity") {
             e["@PersonalData.EntitySemantics"] ??= "Other";
-            e.associations[k]["@PersonalData.FieldSemantics"] ??=
-              "DataSubjectID";
+            e.associations[k]["@PersonalData.FieldSemantics"] ??= "DataSubjectID";
             if (!relevantEntities.includes(e)) relevantEntities.push(e);
           }
         }
@@ -47,18 +43,18 @@ cds.on("served", (services) => {
     if (!(service instanceof cds.ApplicationService)) continue;
     service.after("READ", async (res, req) => {
       // Checking for req.target._service to make sure only entities within services are considered
-      if (!req.target._service || !hasPersonalData(req.target)) return;
+      if (!req.target?._service || !hasPersonalData(req.target)) return;
       await auditAccess.call(service, res, req);
     });
 
     service.after(WRITE, async (res, req) => {
-      if (!req.target._service || !hasPersonalData(req.target)) return;
+      if (!req.target?._service || !hasPersonalData(req.target)) return;
       await emitModLogs.call(service, res, req);
     });
   }
 
   db.before("CREATE", async (req) => {
-    if (!req.target._service || !hasPersonalData(req.target)) return;
+    if (!req.target?._service || !hasPersonalData(req.target)) return;
     await addDiffToCtx.call(db, req);
   });
   /*
@@ -67,11 +63,11 @@ cds.on("served", (services) => {
    * deep updates can contain new, modified and deleted data -> both phases
    */
   db.after(["CREATE", "UPDATE"], async (res, req) => {
-    if (!req.target._service || !hasPersonalData(req.target)) return;
+    if (!req.target?._service || !hasPersonalData(req.target)) return;
     await calcModLogs4After.call(db, res, req);
   });
   db.before(["DELETE", "UPDATE"], async (req) => {
-    if (!req.target._service || !hasPersonalData(req.target)) return;
+    if (!req.target?._service || !hasPersonalData(req.target)) return;
     await addDiffToCtx.call(db, req);
     await calcModLogs4Before.call(db, req);
   });
@@ -81,5 +77,5 @@ cds.on("served", (services) => {
  * Export base class for extending in custom implementations
  */
 module.exports = {
-  AuditLogService: require("./srv/service"),
+  AuditLogService: require("./srv/service")
 };

package/lib/_relation.js

@@ -1,208 +1,211 @@
-let initializing = false
+let initializing = false;
 
 class Relation {
   constructor(csn, path = []) {
-    if (!initializing) throw new Error(`Do not new a relation, use 'Relation.to()' instead`)
-    Object.defineProperty(this, 'csn', { get: () => csn })
-    Object.defineProperty(this, 'path', {
+    if (!initializing) throw new Error(`Do not new a relation, use 'Relation.to()' instead`);
+    Object.defineProperty(this, "csn", { get: () => csn });
+    Object.defineProperty(this, "path", {
       get: () => path,
-      set: _ => {
-        path = _
+      set: (_) => {
+        path = _;
       }
-    })
-    if (csn.target) Object.defineProperty(this, 'target', { get: () => csn.target })
-    initializing = false
+    });
+    if (csn.target) Object.defineProperty(this, "target", { get: () => csn.target });
+    initializing = false;
   }
 
   static to(from, name) {
-    initializing = true
-    if (!name) return new Relation(from)
-    return from._elements[name] && new Relation(from._elements[name], [...from.path, name])
+    initializing = true;
+    if (!name) return new Relation(from);
+    return from._elements[name] && new Relation(from._elements[name], [...from.path, name]);
   }
 
   _has(prop) {
-    return Reflect.has(this, prop)
+    return Reflect.has(this, prop);
   }
 
   get _elements() {
-    if (this.csn.elements) return this.csn.elements
-    if (this.csn._target && this.csn._target.elements) return this.csn._target.elements
+    if (this.csn.elements) return this.csn.elements;
+    if (this.csn._target && this.csn._target.elements) return this.csn._target.elements;
     // if (csn.targetAspect) relation.elements = model.definitions[csn.targetAspect].elements
     // if (csn.kind = 'type') relation.elements = model.definitions[csn.type].element
-    return {}
+    return {};
   }
 
-  join(fromAlias = '', toAlias = '') {
-    return _getOnCond(this.csn, this.path, { select: fromAlias, join: toAlias })
+  join(fromAlias = "", toAlias = "") {
+    return _getOnCond(this.csn, this.path, { select: fromAlias, join: toAlias });
   }
 }
 
-const exposeRelation = relation => Object.defineProperty({}, '_', { get: () => relation })
+const exposeRelation = (relation) => Object.defineProperty({}, "_", { get: () => relation });
 
-const relationHandler = relation => ({
+const relationHandler = (relation) => ({
   get: (target, name) => {
-    const path = name.split(',')
-    const prop = path.join('_')
+    const path = name.split(",");
+    const prop = path.join("_");
     if (!target[prop]) {
       if (path.length === 1) {
         // REVISIT: property 'join' must not be used in CSN to make this working
-        if (relation._has(prop)) return relation[prop]
-        const newRelation = Relation.to(relation, prop)
+        if (relation._has(prop)) return relation[prop];
+        const newRelation = Relation.to(relation, prop);
         if (newRelation) {
-          target[prop] = new Proxy(exposeRelation(newRelation), relationHandler(newRelation))
+          target[prop] = new Proxy(exposeRelation(newRelation), relationHandler(newRelation));
         }
 
-        return target[prop]
+        return target[prop];
       }
 
-      target[prop] = path.reduce((relation, value) => relation[value] || relation.csn._relations[value], relation)
-      target[prop].path = path
+      target[prop] = path.reduce(
+        (relation, value) => relation[value] || relation.csn._relations[value],
+        relation
+      );
+      target[prop].path = path;
     }
 
-    return target[prop]
+    return target[prop];
   }
-})
+});
 
 module.exports = {
   Relation,
   exposeRelation,
   relationHandler
-}
+};
 
 //
 // ----- utils
 //
 
-const _prefixForStruct = element => {
-  const prefixes = []
-  let parent = element.parent
-  while (parent && parent.kind !== 'entity') {
-    prefixes.push(parent.name)
-    parent = parent.parent
+const _prefixForStruct = (element) => {
+  const prefixes = [];
+  let parent = element.parent;
+  while (parent && parent.kind !== "entity") {
+    prefixes.push(parent.name);
+    parent = parent.parent;
   }
-  return prefixes.length ? prefixes.reverse().join('_') + '_' : ''
-}
+  return prefixes.length ? prefixes.reverse().join("_") + "_" : "";
+};
 
 const _toRef = (alias, column) => {
-  if (Array.isArray(column)) column = column.join('_')
-  return { ref: alias ? [alias, column] : [column] }
-}
+  if (Array.isArray(column)) column = column.join("_");
+  return { ref: alias ? [alias, column] : [column] };
+};
 
 const _adaptRefs = (onCond, path, { select, join }) => {
-  const _adaptEl = el => {
-    const ref = el.ref
+  const _adaptEl = (el) => {
+    const ref = el.ref;
 
     if (ref) {
-      if (ref[0] === path.join('_') && ref[1]) {
-        return _toRef(select, ref.slice(1))
+      if (ref[0] === path.join("_") && ref[1]) {
+        return _toRef(select, ref.slice(1));
       }
 
       // no alias for special $user of canonical localized association
-      if (ref[0] === '$user' && path[0] === 'localized') {
-        return _toRef(undefined, ref.slice(0))
+      if (ref[0] === "$user" && path[0] === "localized") {
+        return _toRef(undefined, ref.slice(0));
       }
 
-      return _toRef(join, ref.slice(0))
+      return _toRef(join, ref.slice(0));
     }
 
-    if (el.xpr) return { xpr: el.xpr.map(_adaptEl) }
-    return el
-  }
+    if (el.xpr) return { xpr: el.xpr.map(_adaptEl) };
+    return el;
+  };
 
-  return onCond.map(_adaptEl)
-}
+  return onCond.map(_adaptEl);
+};
 
 const _replace$selfAndAliasOnCond = (xpr, csnElement, aliases, path) => {
-  const selfIndex = xpr.findIndex(({ ref }) => ref?.[0] === '$self')
+  const selfIndex = xpr.findIndex(({ ref }) => ref?.[0] === "$self");
   if (selfIndex != -1) {
-    let backLinkIndex
-    if (xpr[selfIndex + 1] && xpr[selfIndex + 1] === '=') backLinkIndex = selfIndex + 2
-    if (xpr[selfIndex - 1] && xpr[selfIndex - 1] === '=') backLinkIndex = selfIndex - 2
+    let backLinkIndex;
+    if (xpr[selfIndex + 1] && xpr[selfIndex + 1] === "=") backLinkIndex = selfIndex + 2;
+    if (xpr[selfIndex - 1] && xpr[selfIndex - 1] === "=") backLinkIndex = selfIndex - 2;
     if (backLinkIndex != null) {
-      const ref = xpr[backLinkIndex].ref
-      const backlinkName = ref[ref.length - 1]
+      const ref = xpr[backLinkIndex].ref;
+      const backlinkName = ref[ref.length - 1];
       const mutOnCond = _newOnConditions(csnElement._backlink, [backlinkName], {
         select: aliases.join,
         join: aliases.select
-      })
+      });
 
-      xpr.splice(Math.min(backLinkIndex, selfIndex), 3, ...mutOnCond)
+      xpr.splice(Math.min(backLinkIndex, selfIndex), 3, ...mutOnCond);
     }
   }
 
   for (let i = 0; i < xpr.length; i++) {
-    const element = xpr[i]
+    const element = xpr[i];
     if (element.xpr) {
-      _replace$selfAndAliasOnCond(element.xpr, csnElement, aliases, path)
-      continue
+      _replace$selfAndAliasOnCond(element.xpr, csnElement, aliases, path);
+      continue;
     }
 
     if (element.ref) {
-      if (element.ref[0] === path.join('_') && element.ref[1]) {
-        element.ref = _toRef(aliases.select, element.ref.slice(1)).ref
-        continue
+      if (element.ref[0] === path.join("_") && element.ref[1]) {
+        element.ref = _toRef(aliases.select, element.ref.slice(1)).ref;
+        continue;
       }
 
       // no alias for special $user of canonical localized association
-      if (element.ref[0] === '$user' && path[0] === 'localized') {
-        element.ref = _toRef(undefined, element.ref.slice(0)).ref
-        continue
+      if (element.ref[0] === "$user" && path[0] === "localized") {
+        element.ref = _toRef(undefined, element.ref.slice(0)).ref;
+        continue;
       }
       //no alias for special $now variable
-      if (element.ref[0] === '$now') {
-        continue
+      if (element.ref[0] === "$now") {
+        continue;
       }
 
       if (element.ref[0] === aliases.join || element.ref[0] === aliases.select) {
         // nothing todo here, as already right alias
-        continue
+        continue;
       }
 
-      element.ref = _toRef(aliases.join, element.ref.slice(0)).ref
+      element.ref = _toRef(aliases.join, element.ref.slice(0)).ref;
     }
   }
-}
+};
 
 const _args = (csnElement, path, aliases) => {
-  const onCond = csnElement.on
-  if (!onCond || onCond.length === 0) return []
-  if (onCond.length < 3 && !onCond[0]?.xpr) return onCond
-  if (!csnElement._isSelfManaged) return _adaptRefs(onCond, path, aliases)
+  const onCond = csnElement.on;
+  if (!onCond || onCond.length === 0) return [];
+  if (onCond.length < 3 && !onCond[0]?.xpr) return onCond;
+  if (!csnElement._isSelfManaged) return _adaptRefs(onCond, path, aliases);
 
-  const onCondCopy = JSON.parse(JSON.stringify(onCond))
-  _replace$selfAndAliasOnCond(onCondCopy, csnElement, aliases, path)
+  const onCondCopy = JSON.parse(JSON.stringify(onCond));
+  _replace$selfAndAliasOnCond(onCondCopy, csnElement, aliases, path);
 
-  return onCondCopy
-}
+  return onCondCopy;
+};
 
 // this is only for 2one managed w/o on-conditions, i.e. no static values are possible
 const _foreignToOn = (csnElement, path, { select, join }) => {
-  const on = []
+  const on = [];
 
   for (const key of csnElement._foreignKeys) {
     if (on.length !== 0) {
-      on.push('and')
+      on.push("and");
     }
 
-    const prefixChild = _prefixForStruct(key.childElement)
-    const ref1 = _toRef(select, prefixChild + key.childElement.name)
-    const structPrefix = path.length > 1 ? path.slice(0, -1) : []
-    const ref2 = _toRef(join, [...structPrefix, key.parentElement.name])
-    on.push(ref1, '=', ref2)
+    const prefixChild = _prefixForStruct(key.childElement);
+    const ref1 = _toRef(select, prefixChild + key.childElement.name);
+    const structPrefix = path.length > 1 ? path.slice(0, -1) : [];
+    const ref2 = _toRef(join, [...structPrefix, key.parentElement.name]);
+    on.push(ref1, "=", ref2);
   }
 
-  return on
-}
+  return on;
+};
 
 const _newOnConditions = (csnElement, path, aliases) => {
   if (csnElement.keys) {
-    return _foreignToOn(csnElement, path, aliases)
+    return _foreignToOn(csnElement, path, aliases);
   }
 
-  return _args(csnElement, path, aliases)
-}
+  return _args(csnElement, path, aliases);
+};
 
-const _getOnCond = (csnElement, path = [], aliases = { select: '', join: '' }) => {
-  const onCond = _newOnConditions(csnElement, path, aliases)
-  return [{ xpr: onCond }]
-}
+const _getOnCond = (csnElement, path = [], aliases = { select: "", join: "" }) => {
+  const onCond = _newOnConditions(csnElement, path, aliases);
+  return [{ xpr: onCond }];
+};

package/lib/access.js

@@ -1,7 +1,7 @@
-const cds = require('@sap/cds')
+const cds = require("@sap/cds");
 
 // REVISIT: don't require internal stuff
-const getTemplate = require('@sap/cds/libx/_runtime/common/utils/template')
+const getTemplate = require("@sap/cds/libx/_runtime/common/utils/template");
 
 const {
   getRootEntity,
@@ -11,73 +11,74 @@ const {
   addDataSubject,
   addDataSubjectForDetailsEntity,
   resolveDataSubjects
-} = require('./utils')
+} = require("./utils");
 
-let audit
+let audit;
 
 const _processorFnAccess = (accessLogs, model, req) => {
   return ({ row, key, element, plain }) => {
-    if (row.IsActiveEntity === false) return
+    if (row.IsActiveEntity === false) return;
 
-    const entity = getRootEntity(element)
+    const entity = getRootEntity(element);
 
     // create or augment log entry
-    const entry = createLogEntry(accessLogs, entity, row)
+    const entry = createLogEntry(accessLogs, entity, row);
 
     // process categories
     for (const category of plain.categories) {
-      if (category === 'ObjectID') addObjectID(entry, row, key)
-      else if (category === 'DataSubjectID') addDataSubject(entry, row, key, entity)
-      else if (category === 'IsPotentiallySensitive' && key in row) {
-        if (!entry.attributes.some(e => e.name === key)) entry.attributes.push({ name: key })
+      if (category === "ObjectID") addObjectID(entry, row, key);
+      else if (category === "DataSubjectID") addDataSubject(entry, row, key, entity);
+      else if (category === "IsPotentiallySensitive" && key in row) {
+        if (!entry.attributes.some((e) => e.name === key)) entry.attributes.push({ name: key });
         // REVISIT: attribute vs. attachment?
       }
     }
 
     // add promise to determine data subject if a DataSubjectDetails entity
-    const semantics = entity['@PersonalData.EntitySemantics']
+    const semantics = entity["@PersonalData.EntitySemantics"];
     if (
-      (semantics === 'DataSubjectDetails' || semantics === 'Other') &&
+      (semantics === "DataSubjectDetails" || semantics === "Other") &&
       Object.keys(entry.data_subject.id).length === 0 // > id still an empty object -> promise not yet set
     ) {
-      addDataSubjectForDetailsEntity(row, entry, req, entity, model)
+      addDataSubjectForDetailsEntity(row, entry, req, entity, model);
     }
-  }
-}
+  };
+};
 
 const auditAccess = async function (data, req) {
-  if (!cds.env.requires['audit-log'].handle?.includes('READ')) return
+  if (!cds.env.requires["audit-log"].handle?.includes("READ")) return;
 
-  if (typeof data !== 'object' || data == null) return
+  if (typeof data !== "object" || data == null) return;
 
-  const mock = Object.assign({ name: req.target._service.name, model: this.model })
-  const template = getTemplate('personal_read', mock, req.target, { pick: getPick('READ') })
-  if (!template.elements.size) return
+  const mock = Object.assign({ name: req.target._service.name, model: this.model });
+  const template = getTemplate("personal_read", mock, req.target, { pick: getPick("READ") });
+  if (!template.elements.size) return;
 
-  const accessLogs = {}
-  const processFn = _processorFnAccess(accessLogs, this.model, req)
+  const accessLogs = {};
+  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')
+    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 }))
-    }
+      const _data = Array.isArray(data) ? data : [data];
+      _data.forEach((row) => module.exports._templateProcessor({ processFn, row, template }));
+    };
   }
-  template.process(data, processFn)
+  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
+  for (const each of Object.keys(accessLogs))
+    if (!accessLogs[each].attributes.length) delete accessLogs[each];
+  if (!Object.keys(accessLogs).length) return;
 
-  await resolveDataSubjects(accessLogs, req)
-  const accesses = Object.values(accessLogs).filter(ele => ele.attributes.length)
-  if (!accesses.length) return
+  await resolveDataSubjects(accessLogs, req);
+  const accesses = Object.values(accessLogs).filter((ele) => ele.attributes.length);
+  if (!accesses.length) return;
 
-  audit = audit || (await cds.connect.to('audit-log'))
+  audit = audit || (await cds.connect.to("audit-log"));
 
-  await Promise.all(accesses.map(access => audit.log('SensitiveDataRead', access)))
-}
+  await Promise.all(accesses.map((access) => audit.log("SensitiveDataRead", access)));
+};
 
 module.exports = {
   auditAccess
-}
+};