@cap-js/audit-logging 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,25 @@
+# Welcome to @cap-js/audit-logging
+
+## About this project
+
+`@cap-js/audit-logging` is a CDS plugin providing integration to the SAP BTP Audit Logging 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).
+
+## Requirements
+
+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.
+
+The end-to-end out-of-the-box functionality provided by this plugin requires a paid-for instance of the [SAP Audit Logging Service for SAP BTP]([url](https://help.sap.com/docs/application-logging-service?locale=en-US)). However, it is possible to provide an own implementation that writes the audit logs to a custom store.
+
+## 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

@@ -0,0 +1,48 @@
+const cds = require('@sap/cds')
+
+const { auditAccess } = require('./lib/access')
+const { addDiffToCtx, calcModLogs4Before, calcModLogs4After, emitModLogs } = require('./lib/modification')
+const { hasPersonalData } = require('./lib/utils')
+
+const WRITE = ['CREATE', 'UPDATE', 'DELETE']
+
+/*
+ * Add generic audit logging handlers
+ */
+cds.on('served', services => {
+  const db = cds.db
+
+  for (const service of services) {
+    if (!(service instanceof cds.ApplicationService)) continue
+
+    const relevantEntities = []
+    for (const entity of service.entities) if (hasPersonalData(entity)) relevantEntities.push(entity)
+    if (!relevantEntities.length) return
+
+    for (const entity of relevantEntities) {
+      /*
+       * data access
+       */
+      service.after('READ', entity, auditAccess)
+
+      /*
+       * data modification
+       */
+      // common
+      db.before(WRITE, entity, addDiffToCtx)
+      service.after(WRITE, entity, emitModLogs)
+      /*
+       * for new or modified data, modifications are calculated in after phase
+       * for deleted data, modifications are calculated in before phase
+       * deep updates can contain new, modified and deleted data -> both phases
+       */
+      // create
+      db.after('CREATE', entity, calcModLogs4After)
+      // update
+      db.before('UPDATE', entity, calcModLogs4Before)
+      db.after('UPDATE', entity, calcModLogs4After)
+      // delete
+      db.before('DELETE', entity, calcModLogs4Before)
+    }
+  }
+})

package/lib/access.js

@@ -0,0 +1,72 @@
+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,
+  getPick,
+  createLogEntry,
+  addObjectID,
+  addDataSubject,
+  addDataSubjectForDetailsEntity,
+  resolveDataSubjectPromises
+} = require('./utils')
+
+let audit
+
+const _processorFnAccess = (accessLogs, model, req) => {
+  return ({ row, key, element, plain }) => {
+    if (row.IsActiveEntity === false) return
+
+    const entity = getRootEntity(element)
+
+    // create or augment log entry
+    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 })
+        // REVISIT: attribute vs. attachment?
+      }
+    }
+
+    // add promise to determine data subject if a DataSubjectDetails entity
+    const semantics = entity['@PersonalData.EntitySemantics']
+    if (
+      (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)
+    }
+  }
+}
+
+const auditAccess = async function (data, req) {
+  if (!cds.env.requires['audit-log'].handle?.includes('READ')) 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 accessLogs = {}
+  const _data = Array.isArray(data) ? data : [data]
+  _data.forEach(row => templateProcessor({ processFn: _processorFnAccess(accessLogs, this.model, req), row, template }))
+
+  const accesses = (await resolveDataSubjectPromises(accessLogs)).filter(ele => ele.attributes.length)
+  if (!accesses.length) return
+
+  audit = audit || (await cds.connect.to('audit-log'))
+
+  await Promise.all(accesses.map(access => audit.log('SensitiveDataRead', access)))
+}
+
+module.exports = {
+  auditAccess
+}

package/lib/modification.js

@@ -0,0 +1,184 @@
+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,
+  getRootEntity,
+  getPick,
+  createLogEntry,
+  addObjectID,
+  addDataSubject,
+  addDataSubjectForDetailsEntity,
+  resolveDataSubjectPromises
+} = require('./utils')
+
+let audit
+
+// REVISIT: remove once old database impl is removed
+const _getDataWithAppliedTransitions = (data, req) => {
+  let d
+  const query = req.query.INSERT || req.query.UPDATE || req.query.DELETE
+  // NOTE: there will only be transitions if old database impl is used
+  const transition = query._transitions?.find(t => t.queryTarget.name === req.target.name)
+  if (transition) {
+    d = { _op: data._op }
+    if (data._old) d._old = {}
+    for (const [k, v] of transition.mapping) {
+      if (v.ref[0] in data) d[k] = data[v.ref[0]]
+      if (data._old && v.ref[0] in data._old) d._old[k] = data._old[v.ref[0]]
+    }
+  }
+  return d || data
+}
+
+/*
+ * REVISIT: diff() doesn't work in srv after phase but foreign key propagation has not yet taken place in srv before phase
+ *          -> calc diff in db layer and store in audit data structure at context
+ *          -> REVISIT for GA: clear req._.partialPersistentState?
+ */
+const addDiffToCtx = async function (req) {
+  // store diff in audit data structure at context
+  const _audit = (req.context._audit ??= {})
+  if (!_audit.diffs) _audit.diffs = new Map()
+
+  // get diff
+  let diff = await req.diff()
+  diff = _getDataWithAppliedTransitions(diff, req)
+
+  // add keys, if necessary
+  let keys = _getDataWithAppliedTransitions(Object.assign({}, req.data), req)
+  for (const key in keys) if (!(key in req.target.keys)) delete keys[key]
+  Object.assign(diff, keys)
+
+  _audit.diffs.set(req._.query, diff)
+}
+addDiffToCtx._initial = true
+
+const _getOldAndNew = (action, row, key) => {
+  let oldValue = action === 'Create' ? null : row._old && row._old[key]
+  if (oldValue === undefined) oldValue = null
+  else if (Array.isArray(oldValue)) oldValue = JSON.stringify(oldValue)
+  let newValue = action === 'Delete' ? null : row[key]
+  if (newValue === undefined) newValue = null
+  else if (Array.isArray(newValue)) newValue = JSON.stringify(newValue)
+  return { oldValue, newValue }
+}
+
+const _addAttribute = (log, action, row, key) => {
+  if (!log.attributes.find(ele => ele.name === key)) {
+    const { oldValue, newValue } = _getOldAndNew(action, row, key)
+    if (oldValue !== newValue) {
+      const attr = { name: key }
+      if (action !== 'Create') attr.old = oldValue
+      if (action !== 'Delete') attr.new = newValue
+      log.attributes.push(attr)
+    }
+  }
+}
+
+const _maskAttribute = (attributes, key) => {
+  const attribute = attributes?.find(ele => ele.name === key)
+  if (attribute) {
+    if ('old' in attribute) attribute.old = '***'
+    if ('new' in attribute) attribute.new = '***'
+  }
+}
+
+const _processorFnModification = (modificationLogs, model, req, beforeWrite) => elementInfo => {
+  if (!elementInfo.row?._op) return
+
+  let { row, key, element, plain } = elementInfo
+
+  // delete in before phase, create and update in after phase
+  if ((row._op === 'delete') !== !!beforeWrite) return
+
+  const entity = getRootEntity(element)
+  const action = row._op[0].toUpperCase() + row._op.slice(1)
+
+  // create or augment log entry
+  const modificationLog = createLogEntry(modificationLogs, entity, row)
+
+  // process categories
+  for (const category of plain.categories) {
+    if (category === 'ObjectID') {
+      addObjectID(modificationLog, row, key)
+    } else if (category === 'DataSubjectID') {
+      addDataSubject(modificationLog, row, key, entity)
+    } else if (category === 'IsPotentiallyPersonal' || category === 'IsPotentiallySensitive') {
+      _addAttribute(modificationLog, action, row, key)
+      // do not log the value of a sensitive attribute
+      if (element['@PersonalData.IsPotentiallySensitive']) _maskAttribute(modificationLog.attributes, key)
+    }
+  }
+
+  // add promise to determine data subject if a DataSubjectDetails entity
+  if (
+    (entity['@PersonalData.EntitySemantics'] === 'DataSubjectDetails' ||
+      entity['@PersonalData.EntitySemantics'] === 'Other') &&
+    Object.keys(modificationLog.data_subject.id).length === 0 // > id still an empty object -> promise not yet set
+  ) {
+    addDataSubjectForDetailsEntity(row, modificationLog, req, entity, model)
+  }
+}
+
+const _getDataModificationLogs = (req, tx, diff, beforeWrite) => {
+  const template = getTemplate(
+    `personal_${req.event}`.toLowerCase(),
+    Object.assign({ name: req.target._service.name, model: tx.model }),
+    req.target,
+    { pick: getPick(req.event) }
+  )
+
+  const modificationLogs = {}
+  const processFn = _processorFnModification(modificationLogs, tx.model, req, beforeWrite)
+  templateProcessor({ processFn, row: diff, template })
+
+  return modificationLogs
+}
+
+const _calcModificationLogsHandler = async function (req, beforeWrite, that) {
+  const mapKey = getMapKeyForCurrentRequest(req)
+
+  const _audit = (req.context._audit ??= {})
+  const modificationLogs = _getDataModificationLogs(req, that, _audit.diffs.get(mapKey), beforeWrite)
+
+  // store modificationLogs in audit data structure at context
+  if (!_audit.modificationLogs) _audit.modificationLogs = new Map()
+  const existingLogs = _audit.modificationLogs.get(mapKey) || {}
+  _audit.modificationLogs.set(mapKey, Object.assign(existingLogs, modificationLogs))
+
+  // execute the data subject promises before going along to on phase
+  // guarantees that the reads are executed before the data is modified
+  await resolveDataSubjectPromises(modificationLogs)
+}
+
+const calcModLogs4Before = function (req) {
+  return _calcModificationLogsHandler(req, true, this)
+}
+
+const calcModLogs4After = function (_, req) {
+  return _calcModificationLogsHandler(req, false, this)
+}
+
+const emitModLogs = async function (_, req) {
+  const modificationLogs = req.context?._audit?.modificationLogs?.get(req.query)
+  if (!modificationLogs) return
+
+  audit = audit || (await cds.connect.to('audit-log'))
+
+  const modifications = Object.keys(modificationLogs)
+    .map(k => modificationLogs[k])
+    .filter(log => log.attributes.length)
+
+  await Promise.all(modifications.map(modification => audit.log('PersonalDataModified', modification)))
+}
+
+module.exports = {
+  addDiffToCtx,
+  calcModLogs4Before,
+  calcModLogs4After,
+  emitModLogs
+}

package/lib/utils.js

@@ -0,0 +1,237 @@
+const WRITE = { CREATE: 1, UPDATE: 1, DELETE: 1 }
+
+const hasPersonalData = entity => {
+  if (!entity['@PersonalData.DataSubjectRole']) return
+  if (!entity['@PersonalData.EntitySemantics']) return
+  return !!Object.values(entity.elements).some(
+    element =>
+      element['@PersonalData.IsPotentiallyPersonal'] ||
+      element['@PersonalData.IsPotentiallySensitive'] ||
+      (element['@PersonalData.FieldSemantics'] && element['@PersonalData.FieldSemantics'] === 'DataSubjectID')
+  )
+}
+
+const getMapKeyForCurrentRequest = req => {
+  // running in srv or db layer? -> srv's req.query used as key of diff and logs maps at req.context
+  // REVISIT: req._tx should not be used like that!
+  return req.tx.isDatabaseService ? req._.query : req.query
+}
+
+const getRootEntity = element => {
+  let entity = element.parent
+  while (entity.kind !== 'entity') entity = entity.parent
+  return entity
+}
+
+const _isDataSubject = (element, target) => {
+  return (
+    !element.isAssociation &&
+    element['@PersonalData.FieldSemantics'] === 'DataSubjectID' &&
+    target['@PersonalData.EntitySemantics'] === 'DataSubject'
+  )
+}
+
+const getPick = event => {
+  return (element, target) => {
+    if (!hasPersonalData(target)) return
+    const categories = []
+    if (!element.isAssociation && element.key) categories.push('ObjectID')
+    if (_isDataSubject(element, target)) categories.push('DataSubjectID')
+    if (event in WRITE && element['@PersonalData.IsPotentiallyPersonal']) categories.push('IsPotentiallyPersonal')
+    if (element['@PersonalData.IsPotentiallySensitive']) categories.push('IsPotentiallySensitive')
+    if (categories.length) return { categories }
+  }
+}
+
+const _getHash = (entity, row) => {
+  return `${entity.name}(${Object.keys(entity.keys)
+    .map(k => `${k}=${row[k]}`)
+    .join(',')})`
+}
+
+const createLogEntry = (logs, entity, row) => {
+  const hash = _getHash(entity, row)
+  let log = logs[hash]
+  if (!log) {
+    logs[hash] = {
+      data_subject: { id: {}, role: entity['@PersonalData.DataSubjectRole'] },
+      object: { type: entity.name, id: {} },
+      attributes: []
+    }
+    log = logs[hash]
+  }
+  return log
+}
+
+const addObjectID = (log, row, key) => {
+  if (!(key in log.object.id) && key !== 'IsActiveEntity') log.object.id[key] = row[key] || row._old?.[key]
+}
+
+const addDataSubject = (log, row, key, entity) => {
+  if (!log.data_subject.type) log.data_subject.type = entity.name
+  if (!(key in log.data_subject.id)) {
+    const value = row[key] || row._old?.[key]
+    log.data_subject.id[key] = value
+  }
+}
+
+const _addKeysToWhere = (keys, row, alias) => {
+  return keys
+    .filter(key => !key.isAssociation && key.name !== 'IsActiveEntity')
+    .reduce((keys, key) => {
+      if (keys.length) keys.push('and')
+      keys.push({ ref: [alias, key.name] }, '=', { val: row[key.name] })
+      return keys
+    }, [])
+}
+
+const _keyColumns = (keys, alias) => {
+  return keys
+    .filter(key => !key.isAssociation && key.name !== 'IsActiveEntity')
+    .map(key => ({ ref: [alias, key.name] }))
+}
+
+const _alias = entity => entity.name.replace(`${entity._service.name}.`, '').replace('.', '_')
+
+const _buildSubSelect = (model, { entity, relative, element, next }, row, previousCqn) => {
+  // relative is a parent or an entity itself
+
+  const keys = Object.values(entity.keys)
+
+  const entityName = entity.name
+  const as = _alias(entity)
+
+  const childCqn = SELECT.from({ ref: [entityName], as }).columns(_keyColumns(keys, as))
+
+  const targetAlias = _alias(element._target)
+  const relativeAlias = _alias(relative)
+
+  childCqn.where(relative._relations[element.name].join(targetAlias, relativeAlias))
+
+  if (previousCqn) childCqn.where('exists', previousCqn)
+  else childCqn.where(_addKeysToWhere(keys, row, as))
+
+  if (next) return _buildSubSelect(model, next, {}, childCqn)
+
+  return childCqn
+}
+
+const _getDataSubjectIdPromise = ({ dataSubjectEntity, subs }, row, model) => {
+  const keys = Object.values(dataSubjectEntity.keys)
+  const as = _alias(dataSubjectEntity)
+
+  const cqn = SELECT.from({ ref: [dataSubjectEntity.name], as })
+    .columns(_keyColumns(keys, as))
+    .where(['exists', _buildSubSelect(model, subs[0], row)])
+
+  // entity reused in different branches => must check all
+  for (let i = 1; i < subs.length; i++) cqn.or(['exists', _buildSubSelect(model, subs[i], row)])
+
+  return cqn.then(res => {
+    const id = {}
+    for (const k in res[0]) id[k] = res[0][k]
+    return id
+  })
+}
+
+const _getUps = (entity, model) => {
+  if (entity.own('__parents')) return entity.__parents
+  const ups = []
+  for (const def of Object.values(model.definitions)) {
+    if (def.kind !== 'entity' || !def.associations) continue
+    for (const element of Object.values(def.associations)) {
+      if (element.target !== entity.name || element._isBacklink) continue
+      if (element.name === 'SiblingEntity') continue
+      ups.push(element)
+    }
+  }
+  return entity.set('__parents', ups)
+}
+
+const _ifDataSubject = (entity, role) => {
+  return entity['@PersonalData.EntitySemantics'] === 'DataSubject' && entity['@PersonalData.DataSubjectRole'] === role
+}
+
+const _getDataSubjectUp = (role, model, entity, prev, next, result) => {
+  for (const element of _getUps(entity, model)) {
+    const me = { entity, relative: element.parent, element }
+    if (prev) prev.next = me
+    if (_ifDataSubject(element.parent, role)) {
+      if (!result) result = { dataSubjectEntity: element.parent, subs: [] }
+      result.subs.push(next || me)
+      return result
+    } else {
+      // dfs is a must here
+      result = _getDataSubjectUp(role, model, element.parent, me, next || me, result)
+    }
+  }
+  return result
+}
+
+const _getDataSubjectDown = (role, entity, prev, next) => {
+  const associations = Object.values(entity.associations || {}).filter(e => !e._isBacklink)
+  for (const element of associations) {
+    const me = { entity, relative: entity, element }
+    if (_ifDataSubject(element._target, role)) {
+      if (prev) prev.next = me
+      return { dataSubjectEntity: element._target, subs: [next || me] }
+    }
+  }
+  // bfs makes more sense here
+  for (const element of associations) {
+    const me = { entity, relative: entity, element }
+    if (prev) prev.next = me
+    const dataSubject = _getDataSubjectDown(role, element._target, me, next || me)
+    if (dataSubject) return dataSubject
+  }
+}
+
+const getDataSubject = (entity, model, role) => {
+  const hash = '__dataSubject4' + role
+  if (entity.own(hash)) return entity[hash]
+  // entities with EntitySemantics 'DataSubjectDetails' or 'Other' must not necessarily
+  // be always below or always above 'DataSubject' entity in CSN tree
+  let dataSubject = _getDataSubjectUp(role, model, entity)
+  if (!dataSubject) dataSubject = _getDataSubjectDown(role, entity)
+  return entity.set(hash, dataSubject)
+}
+
+const addDataSubjectForDetailsEntity = (row, log, req, entity, model) => {
+  const role = entity['@PersonalData.DataSubjectRole']
+  const dataSubjectInfo = getDataSubject(entity, model, role)
+  log.data_subject.type = dataSubjectInfo.dataSubjectEntity.name
+  /*
+   * for each req (cf. $batch with atomicity) and data subject role (e.g., customer vs supplier),
+   * store (in audit data structure at context) and reuse a single promise to look up the respective data subject
+   */
+  const mapKey = getMapKeyForCurrentRequest(req)
+  const _audit = (req.context._audit ??= {})
+  if (!_audit.dataSubjects) _audit.dataSubjects = new Map()
+  if (!_audit.dataSubjects.has(mapKey)) _audit.dataSubjects.set(mapKey, new Map())
+  const map = _audit.dataSubjects.get(mapKey)
+  if (map.has(role)) log.data_subject.id = map.get(role)
+  // REVISIT by downward lookups row might already contain ID - some potential to optimize
+  else map.set(role, _getDataSubjectIdPromise(dataSubjectInfo, row, model))
+}
+
+const resolveDataSubjectPromises = log => {
+  const logs = Object.values(log)
+  return Promise.all(logs.map(log => log.data_subject.id)).then(IDs =>
+    logs.map((log, i) => {
+      log.data_subject.id = IDs[i]
+      return log
+    })
+  )
+}
+
+module.exports = {
+  hasPersonalData,
+  getMapKeyForCurrentRequest,
+  getRootEntity,
+  getPick,
+  createLogEntry,
+  addObjectID,
+  addDataSubject,
+  addDataSubjectForDetailsEntity,
+  resolveDataSubjectPromises
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cap-js/audit-logging",
+  "version": "0.1.0",
+  "description": "CDS plugin providing integration to the SAP BTP Audit Logging 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)",
+  "homepage": "https://cap.cloud.sap/",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "cds-plugin.js",
+  "files": [
+    "lib",
+    "srv"
+  ],
+  "scripts": {
+    "lint": "npx eslint .",
+    "test": "npx jest --silent"
+  },
+  "peerDependencies": {
+    "@sap/cds": "^7"
+  },
+  "devDependencies": {
+    "@cap-js/sqlite": "^1.0.1",
+    "axios": "^1.4.0",
+    "eslint": "^8",
+    "express": "^4.18.2",
+    "jest": "^29.5.0"
+  },
+  "cds": {
+    "requires": {
+      "audit-log": true,
+      "kinds": {
+        "audit-log": {
+          "handle": [
+            "WRITE"
+          ],
+          "[development]": {
+            "kind": "audit-log-to-console"
+          },
+          "[production]": {
+            "kind": "audit-log-to-restv2"
+          }
+        },
+        "audit-log-to-console": {
+          "impl": "@cap-js/audit-logging/srv/log2console",
+          "outbox": false
+        },
+        "audit-log-to-restv2": {
+          "impl": "@cap-js/audit-logging/srv/log2restv2",
+          "vcap": {
+            "label": "auditlog"
+          },
+          "outbox": true
+        }
+      }
+    }
+  }
+}

package/srv/log2console.js

@@ -0,0 +1,14 @@
+const AuditLogService = require('./service')
+
+module.exports = class AuditLog2Console extends AuditLogService {
+  async init() {
+    this.on('*', function (req) {
+      const { event, data } = req
+
+      console.log(`[audit-log] - ${event}:`, data)
+    })
+
+    // call AuditLogService's init
+    await super.init()
+  }
+}

package/srv/log2restv2.js

@@ -0,0 +1,170 @@
+const cds = require('@sap/cds')
+
+const LOG = cds.log('audit-log')
+
+const AuditLogService = require('./service')
+
+module.exports = class AuditLog2RESTv2 extends AuditLogService {
+  async init() {
+    // credentials stuff
+    const { credentials } = this.options
+    if (!credentials) throw new Error('No or malformed credentials for "audit-log"')
+    if (credentials.uaa) {
+      this._oauth2 = true
+      this._tokens = new Map()
+      this._providerTenant = credentials.uaa.tenantid
+    } else {
+      this._auth = 'Basic ' + Buffer.from(credentials.user + ':' + credentials.password).toString('base64')
+    }
+    this._vcap = process.env.VCAP_APPLICATION ? JSON.parse(process.env.VCAP_APPLICATION) : null
+
+    this.on('*', function (req) {
+      const { event, data } = req
+
+      // event.match() is used to support the old event names
+      if (event === 'SensitiveDataRead' || event.match(/^dataAccess/i)) {
+        return this._handle(data, 'DATA_ACCESS')
+      }
+      if (event === 'PersonalDataModified' || event.match(/^dataModification/i)) {
+        data.success = true
+        return this._handle(data, 'DATA_MODIFICATION')
+      }
+      if (event === 'ConfigurationModified' || event.match(/^configChange/i)) {
+        data.success = true
+        return this._handle(data, 'CONFIGURATION_CHANGE')
+      }
+      if (event === 'SecurityEvent' || event.match(/^security/i)) {
+        if (typeof data.data === 'object') data.data = JSON.stringify(data.data)
+        return this._handle(data, 'SECURITY_EVENT')
+      }
+
+      LOG._warn && LOG.warn(`Event "${event}" is not implemented`)
+    })
+
+    // call AuditLogService's init
+    await super.init()
+  }
+
+  async _getToken(tenant) {
+    const { _tokens: tokens } = this
+    if (tokens.has(tenant)) return tokens.get(tenant)
+
+    const url = this.options.credentials.uaa.url + '/oauth/token'
+    const data = {
+      grant_type: 'client_credentials',
+      response_type: 'token',
+      client_id: this.options.credentials.uaa.clientid,
+      client_secret: this.options.credentials.uaa.clientsecret
+    }
+    const urlencoded = Object.keys(data).reduce((acc, cur) => {
+      acc += (acc ? '&' : '') + cur + '=' + data[cur]
+      return acc
+    }, '')
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
+    if (tenant !== this._providerTenant) headers['x-zid'] = tenant
+    try {
+      const { access_token, expires_in } = await _post(url, urlencoded, headers)
+      tokens.set(tenant, access_token)
+      // remove token from cache 60 seconds before it expires
+      setTimeout(() => tokens.delete(tenant), (expires_in - 60) * 1000)
+      return access_token
+    } catch (err) {
+      // 401 could also mean x-zid is not valid
+      if (String(err.response?.statusCode).match(/^4\d\d$/)) err.unrecoverable = true
+      throw err
+    }
+  }
+
+  async _send(data, path) {
+    let url
+    const headers = { 'content-type': 'application/json' }
+    // TODO: what are these for?
+    if (this._vcap) {
+      headers.XS_AUDIT_ORG = this._vcap.organization_name
+      headers.XS_AUDIT_SPACE = this._vcap.space_name
+      headers.XS_AUDIT_APP = this._vcap.application_name
+    }
+    if (this._oauth2) {
+      url = this.options.credentials.url + PATHS.OAUTH2[path]
+      headers.authorization = 'Bearer ' + (await this._getToken(data.tenant))
+      data.tenant = data.tenant === this._providerTenant ? '$PROVIDER' : '$SUBSCRIBER'
+    } else {
+      url = this.options.credentials.url + PATHS.STANDARD[path]
+      headers.authorization = this._auth
+    }
+    try {
+      await _post(url, data, headers)
+    } catch (err) {
+      // 429 (rate limit) is not unrecoverable
+      if (String(err.response?.statusCode).match(/^4\d\d$/) && err.response?.statusCode !== 429)
+        err.unrecoverable = true
+      throw err
+    }
+  }
+
+  async _handle(logs, path) {
+    if (!Array.isArray(logs)) logs = [logs]
+
+    // write the logs
+    const errors = []
+    await Promise.all(logs.map(log => this._send(log, path).catch(err => errors.push(err))))
+    if (errors.length) throw _getErrorToThrow(errors)
+  }
+}
+
+/*
+ * consts
+ */
+
+const PATHS = {
+  STANDARD: {
+    DATA_ACCESS: '/audit-log/v2/data-accesses',
+    DATA_MODIFICATION: '/audit-log/v2/data-modifications',
+    CONFIGURATION_CHANGE: '/audit-log/v2/configuration-changes',
+    SECURITY_EVENT: '/audit-log/v2/security-events'
+  },
+  OAUTH2: {
+    DATA_ACCESS: '/audit-log/oauth2/v2/data-accesses',
+    DATA_MODIFICATION: '/audit-log/oauth2/v2/data-modifications',
+    CONFIGURATION_CHANGE: '/audit-log/oauth2/v2/configuration-changes',
+    SECURITY_EVENT: '/audit-log/oauth2/v2/security-events'
+  }
+}
+
+/*
+ * utils
+ */
+
+const https = require('https')
+
+async function _post(url, data, headers) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { method: 'POST', headers }, res => {
+      const chunks = []
+      res.on('data', chunk => chunks.push(chunk))
+      res.on('end', () => {
+        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
+          reject(err)
+        } else {
+          resolve(body)
+        }
+      })
+    })
+    req.on('error', reject)
+    req.write(typeof data === 'object' ? JSON.stringify(data) : data)
+    req.end()
+  })
+}
+
+function _getErrorToThrow(errors) {
+  if (errors.length === 1) return errors[0]
+  const error = new cds.error('MULTIPLE_ERRORS')
+  error.details = errors
+  if (errors.some(e => e.unrecoverable)) error.unrecoverable = true
+  return error
+}

package/srv/service.js

@@ -0,0 +1,21 @@
+const cds = require('@sap/cds')
+
+// REVISIT: cds.OutboxService or technique to avoid extending OutboxService
+const OutboxService = require('@sap/cds/libx/_runtime/messaging/Outbox')
+
+module.exports = class AuditLogService extends OutboxService {
+  async init() {
+    // add common audit log entry fields
+    this.before('*', req => {
+      const { tenant, user, timestamp: time } = cds.context
+      Object.assign(req.data, { uuid: cds.utils.uuid(), tenant, user: user.id, time })
+    })
+
+    // call OutboxService's init
+    await super.init()
+
+    // add self-explanatory api (await audit.log/logSync(event, data))
+    this.log = this.emit
+    this.logSync = this.send
+  }
+}