@iobroker/db-objects-redis 7.2.3 → 8.0.0-alpha.1-20260921-e5941ca8a

package/build/esm/lib/objects/objectsInRedisClient.js

@@ -2,25 +2,29 @@
  * Object DB in REDIS - Client
  *
  * MIT License
- * Written by bluefox <dogafox@gmail.com>, 2014-2024
+ * Written by bluefox <dogafox@gmail.com>, 2014-2026
  *
  */
-// @ts-expect-error no ts module
-import extend from 'node.extend';
-import Redis from 'ioredis';
-import { tools } from '@iobroker/db-base';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
+import * as url from 'node:url';
 import deepClone from 'deep-clone';
-import * as utils from '../../lib/objects/objectsUtils.js';
 import semver from 'semver';
+// @ts-expect-error no ts module
+import extend from 'node.extend';
+import Redis from 'ioredis';
+import { tools } from '@iobroker/db-base';
+import { checkObjectRightsAsync, } from '../../lib/objects/objectsUtils.js';
+import * as utils from '../../lib/objects/objectsUtils.js';
 import * as CONSTS from '../../lib/objects/constants.js';
-import * as url from 'node:url';
 // eslint-disable-next-line unicorn/prefer-module
 const thisDir = url.fileURLToPath(new URL('.', import.meta.url || `file://${__filename}`));
 const ERRORS = CONSTS.ERRORS;
+/**
+ * Client for the objects database backed by Redis (or the in-memory redis-protocol server)
+ */
 export class ObjectsInRedisClient {
     client;
     fileNamespace;
@@ -47,6 +51,9 @@ export class ObjectsInRedisClient {
     noLegacyMultihost;
     userSubscriptions;
     systemSubscriptions;
+    /**
+     * @param settings Settings for the objects client including connection and namespaces
+     */
     constructor(settings) {
         this.settings = settings || {};
         this.redisNamespace = `${this.settings.redisNamespace || this.settings.connection?.redisNamespace || 'cfg'}.`;
@@ -107,6 +114,9 @@ export class ObjectsInRedisClient {
             throw new Error(`This host does not support protocol version "${protoVersion}"`);
         }
     }
+    /**
+     * Connect to the objects database and set up the change and file subscriptions
+     */
     connectDb() {
         this.settings.connection = this.settings.connection || {};
         const onChange = this.settings.change; // on change handler
@@ -135,7 +145,7 @@ export class ObjectsInRedisClient {
             if (ready && reconnectCount >= retry_max_count) {
                 return new Error('Stop trying to reconnect');
             }
-            // A function that receives an options object as parameter including the retry attempt,
+            // A function that receives an options object as a parameter including the retry attempt,
             // the total_retry_time indicating how much time passed since the last time connected,
             // the error why the connection was lost and the number of times_connected in total.
             // If you return a number from this function, the retry will happen exactly after that
@@ -161,7 +171,7 @@ export class ObjectsInRedisClient {
             const defaultPort = Array.isArray(configuredPort) ? null : configuredPort;
             this.settings.connection.options.sentinels = this.settings.connection.host.map((redisNode, idx) => ({
                 host: redisNode,
-                // @ts-expect-error ts does not get that if defPort is null we have an array
+                // @ts-expect-error ts does not get that if defPort is null, we have an array
                 port: defaultPort === null ? configuredPort[idx] : defaultPort,
             }));
             this.settings.connection.options.name = this.settings.connection.sentinelName
@@ -177,11 +187,11 @@ export class ObjectsInRedisClient {
         this.settings.connection.options.db = this.settings.connection.options.db || 0;
         this.settings.connection.options.family = this.settings.connection.options.family || 0;
         this.settings.connection.options.password =
-            this.settings.connection.options.auth_pass || this.settings.connection.pass || null;
-        this.settings.connection.options.autoResubscribe = false; // We do our own resubscribe because other sometimes not work
+            this.settings.connection.options.auth_pass || this.settings.connection.pass || undefined;
+        this.settings.connection.options.autoResubscribe = false; // We do our own re-subscribing because other sometimes not work
         // REDIS does not allow whitespaces, we have some because of pid
         this.settings.connection.options.connectionName = this.namespace.replace(/\s/g, '');
-        this.client = new Redis(this.settings.connection.options);
+        this.client = new Redis.Redis(this.settings.connection.options);
         this.client.on('error', error => {
             if (this.settings.connection.enhancedLogging) {
                 this.log.silly(`${this.namespace} Redis ERROR Objects: (${this.stop}) ${error.message} / ${error.stack}`);
@@ -236,7 +246,7 @@ export class ObjectsInRedisClient {
                 this.log.silly(`${this.namespace} Objects-Redis Event reconnect (reconnectCounter=${reconnectCounter}, stop=${this.stop})`);
             }
             if (reconnectCounter > 2) {
-                // fallback logic for nodejs <10
+                // fallback logic for Node.js <10
                 this.log.error(`${this.namespace} The DB port  ${this.settings.connection.options.port} is occupied by something that is not a Redis protocol server. Please check other software running on this port or, if you use iobroker, make sure to update to js-controller 2.0 or higher!`);
                 return;
             }
@@ -263,7 +273,7 @@ export class ObjectsInRedisClient {
             if (!this.subSystem && typeof onChange === 'function') {
                 initCounter++;
                 this.log.debug(`${this.namespace} Objects create System PubSub Client`);
-                this.subSystem = new Redis(this.settings.connection.options);
+                this.subSystem = new Redis.Redis(this.settings.connection.options);
                 if (typeof this.settings.primaryHostLost === 'function') {
                     try {
                         // enable Expiry/Evicted events in server - same as states (could be same db)
@@ -300,7 +310,7 @@ export class ObjectsInRedisClient {
                                 if (newUseSets !== this.useSets) {
                                     this.log.info(`${this.namespace} Sets ${newUseSets ? 'activated' : 'deactivated'}: restarting ...`);
                                     this.useSets = newUseSets;
-                                    // luas are no longer up to date, lets restart
+                                    // luas are no longer up to date, let's restart
                                     if (typeof this.settings.disconnected === 'function') {
                                         this.settings.disconnected();
                                     }
@@ -318,7 +328,7 @@ export class ObjectsInRedisClient {
                                         !isDeepStrictEqual(obj.common.defaultNewAcl, this.defaultNewAcl)) {
                                         this.defaultNewAcl = deepClone(obj.common.defaultNewAcl);
                                         if (this.settings.controller) {
-                                            this.setDefaultAcl(this.defaultNewAcl);
+                                            this.setDefaultAcl(this.defaultNewAcl).catch(e => this.log.error(`${this.namespace} Cannot set default ACL: ${e.message}`));
                                         }
                                     }
                                     onChange(id, obj);
@@ -357,7 +367,7 @@ export class ObjectsInRedisClient {
                 if (this.settings.connection.enhancedLogging) {
                     this.subSystem.on('connect', () => this.log.silly(`${this.namespace} PubSub System client Objects-Redis Event connect (stop=${this.stop})`));
                     this.subSystem.on('close', () => this.log.silly(`${this.namespace} PubSub System client Objects-Redis Event close (stop=${this.stop})`));
-                    this.subSystem.on('reconnecting', reconnectCounter => this.log.silly(`${this.namespace} PubSub System client Objects-Redis Event reconnect (reconnectCounter=${reconnectCounter}, stop=${this.stop})`));
+                    this.subSystem.on('reconnecting', (reconnectCounter) => this.log.silly(`${this.namespace} PubSub System client Objects-Redis Event reconnect (reconnectCounter=${reconnectCounter}, stop=${this.stop})`));
                 }
                 this.subSystem.on('ready', async () => {
                     if (--initCounter < 1) {
@@ -372,7 +382,7 @@ export class ObjectsInRedisClient {
                         }
                         ready = true;
                     }
-                    // subscribe on system.config anytime because also adapters need stuff like defaultNewAcl (especially admin)
+                    // subscribe to system.config anytime because also adapters need stuff like defaultNewAcl (especially admin)
                     try {
                         if (this.subSystem) {
                             await this.subSystem.psubscribe(`${this.objNamespace}system.config`);
@@ -405,7 +415,7 @@ export class ObjectsInRedisClient {
             if (!this.sub && (typeof onChangeUser === 'function' || typeof onChangeFileUser === 'function')) {
                 initCounter++;
                 this.log.debug(`${this.namespace} Objects create User PubSub Client`);
-                this.sub = new Redis(this.settings.connection.options);
+                this.sub = new Redis.Redis(this.settings.connection.options);
                 this.sub.on('pmessage', (pattern, channel, message) => {
                     setImmediate(() => {
                         this.log.silly(`${this.namespace} Objects user redis pmessage ${pattern}/${channel}:${message}`);
@@ -465,11 +475,11 @@ export class ObjectsInRedisClient {
                 if (this.settings.connection.enhancedLogging) {
                     this.sub.on('connect', () => this.log.silly(`${this.namespace} PubSub user client Objects-Redis Event connect (stop=${this.stop})`));
                     this.sub.on('close', () => this.log.silly(`${this.namespace} PubSub user client Objects-Redis Event close (stop=${this.stop})`));
-                    this.sub.on('reconnecting', reconnectCounter => this.log.silly(`${this.namespace} PubSub user client Objects-Redis Event reconnect (reconnectCounter=${reconnectCounter}, stop=${this.stop})`));
+                    this.sub.on('reconnecting', (reconnectCounter) => this.log.silly(`${this.namespace} PubSub user client Objects-Redis Event reconnect (reconnectCounter=${reconnectCounter}, stop=${this.stop})`));
                 }
                 this.sub.on('ready', async () => {
                     if (!this.sub) {
-                        // client gone while ready emitted, can maybe not happen but ts is happy
+                        // client gone while ready emitted, can maybe not happen, but ts is happy
                         return;
                     }
                     if (--initCounter < 1) {
@@ -502,7 +512,7 @@ export class ObjectsInRedisClient {
                 this.useSets = !!parseInt((await this.client.get(`${this.metaNamespace}objects.features.useSets`)) || '0');
             }
             catch (e) {
-                // if unsupported we have a legacy host
+                // if unsupported, we have a legacy host
                 if (!e.message.includes('UNSUPPORTED')) {
                     this.log.error(`${this.namespace} Cannot determine Set feature status: ${e.message}`);
                     return;
@@ -516,13 +526,13 @@ export class ObjectsInRedisClient {
                 this.log.error(`${this.namespace} ${e.message}`);
                 throw new Error('Objects DB is not allowed to start in the current Multihost environment');
             }
-            // for controller v4 we have to check if we can use the new lua scripts and set logic
+            // for controller v4 we have to check if we can use the new Lua scripts and set logic
             // TODO: remove this backward shim if controller v4.0 is old enough
             let keys = await this._getKeysViaScan(`${this.objNamespace}system.host.*`);
             // filter out obvious non-host objects
             const hostRegex = new RegExp(`^${this.objNamespace.replace(/\./g, '\\.')}system\\.host\\.[^.]+$`);
             keys = keys.filter(id => hostRegex.test(id));
-            /** if false we have a host smaller 4 (no proto version for this existing) */
+            /** if false, we have a host smaller 4 (no proto version for this existing) */
             this.noLegacyMultihost = true;
             try {
                 if (keys.length) {
@@ -590,6 +600,9 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Get the current status of the database
+     */
     getStatus() {
         return { type: 'redis', server: false };
     }
@@ -597,7 +610,7 @@ export class ObjectsInRedisClient {
      * Checks if given ID is a meta-object, else throws error
      *
      * @param id to check
-     * @throws Error if id is invalid
+     * @throws {Error} if id is invalid
      */
     async validateMetaObject(id) {
         if (this.existingMetaObjects[id] === undefined) {
@@ -615,6 +628,11 @@ export class ObjectsInRedisClient {
             throw new Error(`${id} is not an object of type "meta"`);
         }
     }
+    /**
+     * Normalize a file name by collapsing slashes and backslashes into a single forward slash
+     *
+     * @param name The file name to normalize
+     */
     normalizeFilename(name) {
         return name ? name.replace(/[/\\]+/g, '/') : name;
     }
@@ -622,7 +640,7 @@ export class ObjectsInRedisClient {
     /**
      * Sets a buffer to the Redis DB
      *
-     * @param id id of the file
+     * @param id ID of the file
      * @param data content, if string is passed it will be converted to a Buffer
      */
     async _setBinaryState(id, data) {
@@ -636,7 +654,7 @@ export class ObjectsInRedisClient {
         await this.client.publish(id, data.byteLength.toString(10));
     }
     /**
-     * get buffer of given id from redis
+     * Get a buffer of a given ID from redis
      *
      * @param id - id of the data with namespace prefix
      */
@@ -647,7 +665,7 @@ export class ObjectsInRedisClient {
         return this.client.getBuffer(id);
     }
     /**
-     * deletes binary state of given id from redis db
+     * deletes binary state of a given ID from redis db
      *
      * @param id - id to delete, with namespace prefix
      */
@@ -660,6 +678,13 @@ export class ObjectsInRedisClient {
             await this.client.publish(id, 'null'); // inform about deletion
         }
     }
+    /**
+     * Build the internal redis key for a file
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param isMeta Whether to return the key of the meta-entry (true) or the data entry (false)
+     */
     getFileId(id, name, isMeta) {
         name = this.normalizeFilename(name);
         // e.g. ekey.admin and admin/ekey.png
@@ -686,42 +711,66 @@ export class ObjectsInRedisClient {
         name = normalized.name;
         return `${this.fileNamespace + id}$%$${name}${isMeta !== undefined ? (isMeta ? '$%$meta' : '$%$data') : ''}`;
     }
-    async checkFile(id, name, options, flag, callback) {
+    /**
+     * Check whether the current options have the required rights on a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param userContext The resolved user context used for permission checks
+     * @param flag The access flag(s) to check for
+     */
+    async checkFileAsync(id, name, userContext, flag) {
         // read file settings from redis
-        const fileId = this.getFileId(id, name, true);
+        const fileId = this.getFileId(id, name ?? '', true);
         if (!fileId) {
-            const fileOptions = { notExists: true };
-            if (utils.checkFile(fileOptions, options, flag, this.defaultNewAcl)) {
-                return tools.maybeCallback(callback, false, options, fileOptions); // NO error
+            if (!utils.checkFile({ notExists: true }, userContext, flag, this.defaultNewAcl)) {
+                return null;
             }
-            return tools.maybeCallback(callback, true, options); // error
+            return { notExists: true };
         }
         if (!this.client) {
-            // @ts-expect-error TODO: not in specs, better just maybe cb check false?
-            return tools.maybeCallbackWithRedisError(callback, ERRORS.ERROR_DB_CLOSED, options);
+            throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        let fileOptions;
+        let fileOptionsStr;
         try {
-            fileOptions = await this.client.get(fileId);
+            fileOptionsStr = await this.client.get(fileId);
         }
         catch {
             // ignore
         }
-        fileOptions = fileOptions || '{"notExists": true}';
+        fileOptionsStr ||= '{"notExists": true}';
+        let fileOptions;
         try {
-            fileOptions = JSON.parse(fileOptions);
+            fileOptions = JSON.parse(fileOptionsStr);
         }
         catch {
-            this.log.error(`${this.namespace} Cannot parse JSON ${id}: ${fileOptions}`);
+            this.log.error(`${this.namespace} Cannot parse JSON ${id}: ${fileOptionsStr}`);
             fileOptions = { notExists: true };
         }
-        if (utils.checkFile(fileOptions, options, flag, this.defaultNewAcl)) {
-            return tools.maybeCallback(callback, false, options, fileOptions); // NO error
+        if (!utils.checkFile(fileOptions, userContext, flag, this.defaultNewAcl)) {
+            return null;
         }
-        return tools.maybeCallback(callback, true, options); // error
+        return fileOptions;
     }
+    /**
+     * Check whether the current user is allowed to access a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name, or null for the whole namespace
+     * @param options The current request options including the user
+     * @param flag The access flag(s) to check for
+     * @param callback Called with the effective options once the rights have been checked
+     */
     checkFileRights(id, name, options, flag, callback) {
-        return utils.checkFileRights(this, id, name, options, flag, callback);
+        try {
+            utils
+                .checkFileRightsAsync(this, id, name, options, flag)
+                .then(result => callback(null, result.fileOptions, result.userContext))
+                .catch(err => callback(err));
+        }
+        catch (error) {
+            callback(error);
+        }
     }
     async _setDefaultAcl(ids, defaultAcl) {
         for (const id of ids) {
@@ -737,6 +786,11 @@ export class ObjectsInRedisClient {
             }
         }
     }
+    /**
+     * Set the default ACL applied to new objects and apply it to all existing objects without an ACL
+     *
+     * @param defaultNewAcl The default ACL to use, or null to use the built-in default
+     */
     async setDefaultAcl(defaultNewAcl) {
         this.defaultNewAcl = defaultNewAcl || {
             owner: CONSTS.SYSTEM_ADMIN_USER,
@@ -756,17 +810,25 @@ export class ObjectsInRedisClient {
             this.log.error(`${this.namespace} Could not update default acl: ${e.message}`);
         }
     }
+    /**
+     * Determine the groups and effective ACL of the given user
+     *
+     * @param user The id of the user to look up
+     * @param callback Called with the user, its groups, and the effective ACL
+     */
     getUserGroup(user, callback) {
         return utils.getUserGroup(this, user, (error, user, userGroups, userAcl) => {
             if (error) {
                 this.log.error(`${this.namespace} ${error.stack}`);
             }
-            return tools.maybeCallback(callback, user, userGroups, userAcl);
+            if (typeof callback === 'function') {
+                callback(user, userGroups, userAcl);
+            }
         });
     }
     async _writeFile(id, name, data, options, callback, meta) {
         const matchedExtension = name.match(/\.[^.]+$/);
-        const ext = matchedExtension ? matchedExtension[0] : '';
+        const ext = matchedExtension?.[0] || '';
         const isTextData = typeof data === 'string';
         const { mimeType, isBinary } = utils.getMimeType(ext, isTextData);
         const metaID = this.getFileId(id, name, true);
@@ -788,33 +850,24 @@ export class ObjectsInRedisClient {
             }
         }
         else {
-            if (!meta) {
-                meta = { createdAt: Date.now() };
-            }
-            if (!meta.acl) {
-                meta.acl = {
-                    owner: options.user || (this.defaultNewAcl && this.defaultNewAcl.owner) || CONSTS.SYSTEM_ADMIN_USER,
-                    ownerGroup: options.group ||
-                        (this.defaultNewAcl && this.defaultNewAcl.ownerGroup) ||
-                        CONSTS.SYSTEM_ADMIN_GROUP,
-                    permissions: options.mode || (this.defaultNewAcl && this.defaultNewAcl.file) || 0x644,
-                };
-            }
+            meta ||= { createdAt: Date.now() };
+            meta.acl ||= {
+                owner: options.user || this.defaultNewAcl?.owner || CONSTS.SYSTEM_ADMIN_USER,
+                ownerGroup: options.group || this.defaultNewAcl?.ownerGroup || CONSTS.SYSTEM_ADMIN_GROUP,
+                permissions: options.mode || this.defaultNewAcl?.file || 0x644,
+            };
             meta.stats = {
-                size: data ? data.length : 0,
+                size: data?.length || 0,
             };
             if (Object.prototype.hasOwnProperty.call(meta, 'notExists')) {
                 delete meta.notExists;
             }
             meta.mimeType = options.mimeType || mimeType;
             meta.binary = isBinary;
-            meta.acl.ownerGroup =
-                meta.acl.ownerGroup ||
-                    (this.defaultNewAcl && this.defaultNewAcl.ownerGroup) ||
-                    CONSTS.SYSTEM_ADMIN_GROUP;
+            meta.acl.ownerGroup ||= this.defaultNewAcl?.ownerGroup || CONSTS.SYSTEM_ADMIN_GROUP;
             meta.modifiedAt = Date.now();
             try {
-                await this._setBinaryState(this.getFileId(id, name, false), data);
+                await this._setBinaryState(this.getFileId(id, name, false), data || '');
                 await this.client.set(metaID, JSON.stringify(meta));
                 return tools.maybeCallback(callback);
             }
@@ -823,17 +876,20 @@ export class ObjectsInRedisClient {
             }
         }
     }
+    /**
+     * Write data into a file of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param data The data to write
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the file has been written
+     */
     async writeFile(id, name, data, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (typeof options === 'string') {
-            options = { mimeType: options };
-        }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (!callback) {
             return this.writeFileAsync(id, name, data, options);
         }
@@ -854,13 +910,21 @@ export class ObjectsInRedisClient {
             data = null;
         }
         // If file yet exists => check the permissions
-        return this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, options, meta) => {
+        return this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, meta) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            return this._writeFile(id, name, data, options, callback, meta);
+            return this._writeFile(id, name, data, options || {}, callback, meta);
         });
     }
+    /**
+     * Promise-version of writeFile
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param data The data to write
+     * @param options The current request options including the user
+     */
     writeFileAsync(id, name, data, options) {
         return new Promise((resolve, reject) => this.writeFile(id, name, data, options, err => (err ? reject(err) : resolve())));
     }
@@ -871,22 +935,26 @@ export class ObjectsInRedisClient {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        let buffer;
-        buffer = await this._getBinaryState(this.getFileId(id, name, false));
+        let file = await this._getBinaryState(this.getFileId(id, name, false));
         const mimeType = meta?.mimeType;
-        if (meta && !meta.binary && buffer) {
-            buffer = buffer.toString();
+        if (meta && !meta.binary && file) {
+            file = file.toString();
         }
-        return { file: buffer, mimeType: mimeType };
+        return { file, mimeType };
     }
+    /**
+     * Read a file of an object
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the file content and mime type
+     */
     readFile(id, name, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (!callback) {
             return new Promise((resolve, reject) => this.readFile(id, name, options, (err, res, mimeType) => err ? reject(err) : resolve({ file: res, mimeType: mimeType })));
         }
@@ -896,8 +964,8 @@ export class ObjectsInRedisClient {
         if (name.startsWith('/')) {
             name = name.substring(1);
         }
-        options = options || {};
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_READ, async (err, options, meta) => {
+        options ||= {};
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_READ, async (err, meta) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
@@ -911,9 +979,9 @@ export class ObjectsInRedisClient {
         });
     }
     /**
-     * Check if given object exists
+     * Check if a given object exists
      *
-     * @param id id of the object
+     * @param id ID of the object
      * @param options optional user context
      */
     async objectExists(id, options) {
@@ -921,18 +989,11 @@ export class ObjectsInRedisClient {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
         if (!id || typeof id !== 'string') {
-            throw new Error(`invalid id ${JSON.stringify(id)}`);
+            throw new Error(`invalid ID ${JSON.stringify(id)}`);
         }
         try {
             await new Promise((resolve, reject) => {
-                utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_LIST, err => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        resolve();
-                    }
-                });
+                utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_LIST, err => err ? reject(err) : resolve());
             });
             const exists = await this.client.exists(this.objNamespace + id);
             return !!exists;
@@ -943,9 +1004,9 @@ export class ObjectsInRedisClient {
         }
     }
     /**
-     * Check if given file exists
+     * Check if a given file exists
      *
-     * @param id id of the namespace
+     * @param id ID of the namespace
      * @param name name of the file
      * @param options optional user context
      */
@@ -957,16 +1018,7 @@ export class ObjectsInRedisClient {
             name = name.substring(1);
         }
         try {
-            await new Promise((resolve, reject) => {
-                this.checkFileRights(id, name, options, CONSTS.ACCESS_READ, err => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        resolve();
-                    }
-                });
-            });
+            await utils.checkFileRightsAsync(this, id, name, options, CONSTS.ACCESS_READ);
             if (!this.client) {
                 throw new Error(ERRORS.ERROR_DB_CLOSED);
             }
@@ -979,41 +1031,46 @@ export class ObjectsInRedisClient {
             throw new Error(`Cannot check file existence of "${id}": ${e.message}`);
         }
     }
-    async _unlink(id, name, options, meta) {
+    async _unlink(id, name, userContext, meta) {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        if (meta && meta.notExists) {
-            return this._rm(id, name, options);
+        if (meta?.notExists) {
+            return this._rm(id, name, userContext);
         }
         const metaID = this.getFileId(id, name, true);
         const dataID = this.getFileId(id, name, false);
         await this._delBinaryState(dataID);
         await this.client.del(metaID);
     }
+    /**
+     * Delete a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the list of removed files
+     */
     unlink(id, name, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof name !== 'string') {
             name = '';
         }
         if (name.startsWith('/')) {
             name = name.substring(1);
         }
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_DELETE, async (err, options, meta) => {
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_DELETE, async (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.delete) {
+            if (!userContext.acl.file.delete) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
             try {
-                const files = await this._unlink(id, name, options, meta);
+                const files = await this._unlink(id, name, userContext, meta);
                 return tools.maybeCallbackWithError(callback, null, files);
             }
             catch (e) {
@@ -1021,16 +1078,38 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Promise-version of unlink
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user
+     */
     unlinkAsync(id, name, options) {
         return new Promise((resolve, reject) => this.unlink(id, name, options, err => (err ? reject(err) : resolve())));
     }
+    /**
+     * Delete a file of an object (alias for {@link unlink})
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name to delete
+     * @param options The current request options including the user
+     * @param callback Called once the file has been deleted
+     */
     delFile(id, name, options, callback) {
         return this.unlink(id, name, options, callback);
     }
+    /**
+     * Promise-version of delFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name to delete
+     * @param options The current request options including the user
+     */
     delFileAsync(id, name, options) {
         return this.unlinkAsync(id, name, options);
     }
-    async _readDir(id, name, options, callback) {
+    async _readDir(id, name, userContext, callback) {
         name = this.normalizeFilename(name);
         if (!this.client) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
@@ -1120,9 +1199,9 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
         const result = [];
-        const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-            options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-            options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+        const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+            userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+            userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
         for (let i = 0; i < keys.length; i++) {
             const file = keys[i].substring(start + baseName.length, keys[i].length - end);
             while (dirs.length && dirs[0] < file) {
@@ -1141,13 +1220,14 @@ export class ObjectsInRedisClient {
                 this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                 continue;
             }
-            if (dontCheck || utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+            if (dontCheck || utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                 if (!obj || obj.virtualFile) {
                     // virtual file, ignore
                     continue;
                 }
-                obj.acl = obj.acl || {};
-                if (options.user !== CONSTS.SYSTEM_ADMIN_USER && !options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP)) {
+                obj.acl ||= {};
+                if (userContext.user !== CONSTS.SYSTEM_ADMIN_USER &&
+                    !userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP)) {
                     obj.acl.read = !!(obj.acl.permissions & CONSTS.ACCESS_EVERY_READ);
                     obj.acl.write = !!(obj.acl.permissions & CONSTS.ACCESS_EVERY_WRITE);
                 }
@@ -1156,8 +1236,8 @@ export class ObjectsInRedisClient {
                     obj.acl.write = true;
                 }
                 result.push({
-                    file: file,
-                    stats: obj.stats,
+                    file,
+                    stats: obj.stats || {},
                     isDir: false,
                     acl: obj.acl,
                     modifiedAt: obj.modifiedAt,
@@ -1174,14 +1254,19 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallbackWithError(callback, null, result);
     }
+    /**
+     * List the contents of a directory of an object
+     *
+     * @param id The id of the object owning the files
+     * @param name The directory name to list
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the directory entries
+     */
     readDir(id, name, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof name !== 'string') {
             name = '';
         }
@@ -1192,16 +1277,23 @@ export class ObjectsInRedisClient {
         if (name.endsWith('/')) {
             name = name.substring(0, name.length - 1);
         }
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_READ, (err, options) => {
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_READ, (err, options, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.list) {
+            if (!userContext.acl.file.list) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            this._readDir(id, name, options, callback);
+            return this._readDir(id, name, userContext, callback);
         });
     }
+    /**
+     * Promise-version of readDir
+     *
+     * @param id The id of the object owning the files
+     * @param name The directory name to list
+     * @param options The current request options including the user
+     */
     readDirAsync(id, name, options) {
         return new Promise((resolve, reject) => this.readDir(id, name, options, (err, res) => (err ? reject(err) : resolve(res))));
     }
@@ -1231,7 +1323,7 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallback(callback);
     }
-    async _rename(id, oldName, newName, options, callback, meta) {
+    async _rename(id, oldName, newName, userContext, callback, meta) {
         const oldMetaID = this.getFileId(id, oldName, true);
         const oldDataID = this.getFileId(id, oldName, false);
         const newMetaID = this.getFileId(id, newName, true);
@@ -1284,9 +1376,9 @@ export class ObjectsInRedisClient {
                 return tools.maybeCallbackWithRedisError(callback, e);
             }
             let result;
-            const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-                options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-                options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+            const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+                userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+                userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
             if (!dontCheck) {
                 result = [];
                 for (let i = 0; i < keys.length; i++) {
@@ -1299,7 +1391,7 @@ export class ObjectsInRedisClient {
                         this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                         continue;
                     }
-                    if (utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+                    if (utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                         result.push(keys[i]);
                     }
                 }
@@ -1318,14 +1410,20 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
     }
+    /**
+     * Rename a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param oldName The current file or directory name
+     * @param newName The new file or directory name
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the file has been renamed
+     */
     rename(id, oldName, newName, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof oldName !== 'string' ||
             !oldName.length ||
             oldName === '/' ||
@@ -1348,20 +1446,29 @@ export class ObjectsInRedisClient {
         if (newName.endsWith('/')) {
             newName = newName.substring(0, newName.length - 1);
         }
-        this.checkFileRights(id, oldName, options, CONSTS.ACCESS_WRITE, (err, options, meta) => {
+        this.checkFileRights(id, oldName, options, CONSTS.ACCESS_WRITE, (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.write) {
+            if (!userContext.acl.file.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            this._rename(id, oldName, newName, options, callback, meta);
+            return this._rename(id, oldName, newName, userContext, callback, meta);
         });
     }
+    /**
+     * Promise-version of rename
+     *
+     * @param id The id of the object owning the file
+     * @param oldName The current file or directory name
+     * @param newName The new file or directory name
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
     renameAsync(id, oldName, newName, options) {
         return new Promise((resolve, reject) => this.rename(id, oldName, newName, options, err => (err ? reject(err) : resolve())));
     }
-    async _touch(id, name, callback, meta) {
+    async _touch(id, name, meta, callback) {
         const metaID = this.getFileId(id, name, true);
         if (!this.client) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
@@ -1378,27 +1485,40 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
     }
+    /**
+     * Update the modification time of a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the file has been touched
+     */
     touch(id, name, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof name !== 'string' || !name.length || name === '/') {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_NOT_FOUND);
         }
         if (name.startsWith('/')) {
             name = name.substring(1);
         }
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, options, meta) => {
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, meta) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            return this._touch(id, name, callback, meta);
+            return this._touch(id, name, meta, callback);
         });
     }
+    /**
+     * Promise-version of touch
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
     touchAsync(id, name, options) {
         return new Promise((resolve, reject) => this.touch(id, name, options, err => (err ? reject(err) : resolve())));
     }
@@ -1414,7 +1534,7 @@ export class ObjectsInRedisClient {
             await this.client.del(id);
         }
     }
-    async _rm(id, name, options, meta) {
+    async _rm(id, name, userContext, meta) {
         if (meta && !meta.isDir) {
             // it is a file
             const metaID = this.getFileId(id, name, true);
@@ -1447,30 +1567,30 @@ export class ObjectsInRedisClient {
                 throw new Error(ERRORS.ERROR_NOT_FOUND);
             }
             // Check permissions
-            let objs;
+            let strObjs;
             try {
-                objs = await this.client.mget(keys);
+                strObjs = await this.client.mget(keys);
             }
             catch {
                 // ignore
             }
             let result;
-            const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-                options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-                options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
-            objs = objs || [];
+            const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+                userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+                userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+            strObjs ||= [];
             if (!dontCheck) {
                 result = [];
                 for (let i = 0; i < keys.length; i++) {
+                    const strObj = strObjs[i];
                     try {
-                        const strObj = objs[i];
                         const obj = strObj ? JSON.parse(strObj) : null;
-                        if (utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+                        if (utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                             result.push(keys[i]);
                         }
                     }
                     catch {
-                        this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${objs[i]}`);
+                        this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                     }
                 }
             }
@@ -1494,26 +1614,31 @@ export class ObjectsInRedisClient {
             return files;
         }
     }
+    /**
+     * Delete a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the list of removed files
+     */
     rm(id, name, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof name !== 'string') {
             name = '';
         }
-        this.checkFileRights(id, null, options, CONSTS.ACCESS_DELETE, async (err, options, meta) => {
+        this.checkFileRights(id, null, options, CONSTS.ACCESS_DELETE, async (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.delete) {
+            if (!userContext.acl.file.delete) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
             try {
-                const files = await this._rm(id, name, options, meta?.notExists ? null : meta);
+                const files = await this._rm(id, name, userContext, meta?.notExists ? null : meta);
                 return tools.maybeCallbackWithError(callback, null, files);
             }
             catch (e) {
@@ -1521,10 +1646,26 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Promise-version of rm
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
     rmAsync(id, name, options) {
         return new Promise((resolve, reject) => this.rm(id, name, options, (err, files) => (err ? reject(err) : resolve(files))));
     }
     // simulate. redis has no dirs
+    /**
+     * Create a directory for an object's files (simulated, as redis has no real directories)
+     *
+     * @param id The id of the object owning the files
+     * @param dirName The directory name to create
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the directory has been created
+     */
     mkdir(id, dirName, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -1537,19 +1678,26 @@ export class ObjectsInRedisClient {
         if (dirName.startsWith('/')) {
             dirName = dirName.substring(1);
         }
-        this.checkFileRights(id, dirName, options, CONSTS.ACCESS_WRITE, (err, options) => {
+        this.checkFileRights(id, dirName, options, CONSTS.ACCESS_WRITE, (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.write) {
+            if (!userContext.acl.file.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            // we create a dummy file (for file this file exists to store meta data) - do not override passed options
-            options = { ...options, virtualFile: true };
+            // we create a dummy file (for file this file exists to store metadata) - do not override passed options
+            meta = { ...options, virtualFile: true };
             const realName = dirName + (dirName.endsWith('/') ? '' : '/');
-            this.writeFile(id, `${realName}_data.json`, '', options, callback);
+            return this.writeFile(id, `${realName}_data.json`, '', meta, callback);
         });
     }
+    /**
+     * Promise-version of mkdir
+     *
+     * @param id The id of the object owning the files
+     * @param dirName The directory name to create
+     * @param options The current request options including the user
+     */
     mkdirAsync(id, dirName, options) {
         return new Promise((resolve, reject) => this.mkdir(id, dirName, options, err => (err ? reject(err) : resolve())));
     }
@@ -1573,7 +1721,7 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallback(callback);
     }
-    async _chownFile(id, name, options, callback, meta) {
+    async _chownFile(id, name, options, meta, userContext, callback) {
         if (!meta) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_NOT_FOUND);
         }
@@ -1582,7 +1730,7 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
         }
         if (!meta.isDir && !meta.notExists) {
-            // it is file
+            // it is a file
             const metaID = this.getFileId(id, name, true);
             meta.acl.owner = options.owner;
             meta.acl.ownerGroup = options.ownerGroup;
@@ -1597,7 +1745,7 @@ export class ObjectsInRedisClient {
             const res = [
                 {
                     path: nameArr.join('/'),
-                    file: file,
+                    file,
                     stats: meta.stats,
                     isDir: false,
                     acl: meta.acl || {},
@@ -1637,9 +1785,9 @@ export class ObjectsInRedisClient {
         catch (e) {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
-        const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-            options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-            options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+        const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+            userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+            userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
         const keysFiltered = [];
         const objsFiltered = [];
         const processed = [];
@@ -1655,7 +1803,7 @@ export class ObjectsInRedisClient {
                 this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${metaStr}`);
                 continue;
             }
-            if (dontCheck || utils.checkObject(meta, options, CONSTS.ACCESS_WRITE)) {
+            if (dontCheck || utils.checkObject(meta, userContext, CONSTS.ACCESS_WRITE)) {
                 if (!meta || meta.virtualFile) {
                     continue;
                 } // virtual file, ignore
@@ -1675,39 +1823,43 @@ export class ObjectsInRedisClient {
                 });
             }
         }
-        this._chownFileHelper(keysFiltered, objsFiltered, options, err => {
+        return this._chownFileHelper(keysFiltered, objsFiltered, options, err => {
             return tools.maybeCallbackWithError(callback, err, processed);
         });
     }
+    /**
+     * Change the owner and owner group of a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new owner and the user
+     * @param options.owner The new owner (user id) to assign to the file
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.ownerGroup The new owner group to assign to the file
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     * @param callback Called with the processed file(s)
+     */
     chownFile(id, name, options, callback) {
-        if (typeof options === 'function') {
-            callback = options;
-            options = {};
-        }
-        options = options || {};
-        if (typeof options !== 'object') {
-            options = { owner: options };
-        }
         if (typeof name !== 'string' || !name.length || name === '/') {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_NOT_FOUND);
         }
         if (name.startsWith('/')) {
             name = name.substring(1);
         }
-        if (!options.ownerGroup && options.group) {
+        if (options?.group && !options.ownerGroup) {
             options.ownerGroup = options.group;
         }
-        if (!options.owner && options.user) {
+        if (options?.user && !options.owner) {
             options.owner = options.user;
         }
-        if (!options.owner) {
+        if (!options?.owner) {
             this.log.error(`${this.namespace} user is not defined`);
             return tools.maybeCallbackWithError(callback, 'invalid parameter');
         }
         if (!options.ownerGroup) {
             // get user group
             this.getUserGroup(options.owner, (user, groups) => {
-                if (!groups || !groups[0]) {
+                if (!groups?.[0]) {
                     return tools.maybeCallbackWithError(callback, `user "${options.owner}" belongs to no group`);
                 }
                 options.ownerGroup = groups[0];
@@ -1715,16 +1867,26 @@ export class ObjectsInRedisClient {
             });
             return;
         }
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, options, meta) => {
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.write) {
+            if (!userContext.acl.file.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            return this._chownFile(id, name, options, callback, meta);
+            return this._chownFile(id, name, options, meta, userContext, callback);
         });
     }
+    /**
+     * Promise-version of chownFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new owner and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the file
+     * @param options.ownerGroup The new owner group to assign to the file
+     */
     chownFileAsync(id, name, options) {
         return new Promise((resolve, reject) => this.chownFile(id, name, options, (err, processed) => (err ? reject(err) : resolve(processed))));
     }
@@ -1733,6 +1895,8 @@ export class ObjectsInRedisClient {
      * @param keys Key names to handle
      * @param metas Objects for the keys to handle
      * @param options options
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
      * @param callback callback function
      */
     async _chmodFileHelper(keys, metas, options, callback) {
@@ -1742,7 +1906,7 @@ export class ObjectsInRedisClient {
         if (!this.client) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
         }
-        for (const i in keys) {
+        for (let i = 0; i < keys.length; i++) {
             const id = keys[i];
             const meta = metas[i];
             meta.acl.permissions = options.mode;
@@ -1755,7 +1919,7 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallback(callback);
     }
-    async _chmodFile(id, name, options, callback, meta) {
+    async _chmodFile(id, name, options, meta, userContext, callback) {
         if (!meta) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_NOT_FOUND);
         }
@@ -1764,7 +1928,7 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
         }
         if (!meta.isDir && !meta.notExists) {
-            // it is file
+            // it is a file
             const metaID = this.getFileId(id, name, true);
             meta.acl.permissions = options.mode;
             try {
@@ -1778,7 +1942,7 @@ export class ObjectsInRedisClient {
             const res = [
                 {
                     path: nameArr.join('/'),
-                    file: file,
+                    file,
                     stats: meta.stats,
                     isDir: false,
                     acl: meta.acl || {},
@@ -1818,9 +1982,9 @@ export class ObjectsInRedisClient {
         catch (e) {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
-        const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-            options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-            options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+        const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+            userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+            userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
         const keysFiltered = [];
         const objsFiltered = [];
         const processed = [];
@@ -1836,7 +2000,7 @@ export class ObjectsInRedisClient {
                 this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                 continue;
             }
-            if (dontCheck || utils.checkObject(obj, options, CONSTS.ACCESS_WRITE)) {
+            if (dontCheck || utils.checkObject(obj, userContext, CONSTS.ACCESS_WRITE)) {
                 if (!obj || obj.virtualFile) {
                     continue;
                 } // virtual file, ignore
@@ -1856,14 +2020,22 @@ export class ObjectsInRedisClient {
                 });
             }
         }
-        this._chmodFileHelper(keysFiltered, objsFiltered, options, err => tools.maybeCallbackWithError(callback, err, processed));
+        return this._chmodFileHelper(keysFiltered, objsFiltered, options, err => tools.maybeCallbackWithError(callback, err, processed));
     }
+    /**
+     * Change the file mode (permissions) of a single file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new mode and the user, or the callback
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
+     * @param callback Called with the processed file
+     */
     chmodFile(id, name, options, callback) {
-        if (typeof options === 'function') {
-            callback = options;
-            options = null;
+        if (!options || options.mode === undefined) {
+            throw new Error('options.mode is not defined');
         }
-        options = options || {};
         if (typeof name !== 'string' || !name.length || name === '/') {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_NOT_FOUND);
         }
@@ -1880,28 +2052,41 @@ export class ObjectsInRedisClient {
         else if (typeof options.mode === 'string') {
             options.mode = parseInt(options.mode, 16);
         }
-        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, options, meta) => {
+        this.checkFileRights(id, name, options, CONSTS.ACCESS_WRITE, (err, meta, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
-            if (!options.acl.file.write) {
+            if (!userContext.acl.file.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            return this._chmodFile(id, name, options, callback, meta);
+            return this._chmodFile(id, name, options, meta, userContext, callback);
         });
     }
+    /**
+     * Promise-version of chmodFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new mode and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
+     */
     chmodFileAsync(id, name, options) {
         return new Promise((resolve, reject) => this.chmodFile(id, name, options, (err, processed) => (err ? reject(err) : resolve(processed))));
     }
+    /**
+     * Enable or disable the file cache
+     *
+     * @param enabled Whether the file cache should be enabled
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the resulting cache state
+     */
     enableFileCache(enabled, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, _options) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, err => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
@@ -1909,6 +2094,12 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithError(callback, null, false);
         });
     }
+    /**
+     * Promise-version of enableFileCache
+     *
+     * @param enabled Whether the file cache should be enabled
+     * @param options The current request options including the user
+     */
     enableFileCacheAsync(enabled, options) {
         return new Promise((resolve, reject) => this.enableFileCache(enabled, options, (err, res) => (err ? reject(err) : resolve(res))));
     }
@@ -1958,6 +2149,13 @@ export class ObjectsInRedisClient {
             }
         }
     }
+    /**
+     * Subscribe a user to file changes of an object
+     *
+     * @param id The id of the object owning the files
+     * @param pattern One or more file name patterns to subscribe to
+     * @param options The current request options including the user
+     */
     subscribeUserFile(id, pattern, options) {
         return new Promise((resolve, reject) => {
             utils.checkObjectRights(this, null, null, options, 'list', err => {
@@ -1972,6 +2170,13 @@ export class ObjectsInRedisClient {
             });
         });
     }
+    /**
+     * Unsubscribe a user from file changes of an object
+     *
+     * @param id The id of the object owning the files
+     * @param pattern One or more file name patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
     unsubscribeUserFile(id, pattern, options) {
         return new Promise((resolve, reject) => {
             utils.checkObjectRights(this, null, null, options, 'list', err => {
@@ -2025,6 +2230,13 @@ export class ObjectsInRedisClient {
             return this._subscribe(pattern, false, callback);
         });
     }
+    /**
+     * Subscribe to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the subscription is registered
+     */
     subscribe(pattern, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2032,9 +2244,22 @@ export class ObjectsInRedisClient {
         }
         return this.subscribeConfig(pattern, options, callback);
     }
+    /**
+     * Promise-version of subscribe
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     */
     subscribeAsync(pattern, options) {
         return new Promise((resolve, reject) => this.subscribe(pattern, options, err => (err ? reject(err) : resolve())));
     }
+    /**
+     * Subscribe a user to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the subscription is registered
+     */
     subscribeUser(pattern, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2047,6 +2272,12 @@ export class ObjectsInRedisClient {
             return this._subscribe(pattern, true, callback);
         });
     }
+    /**
+     * Promise-version of subscribeUser
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     */
     subscribeUserAsync(pattern, options) {
         return new Promise((resolve, reject) => this.subscribeUser(pattern, options, err => (err ? reject(err) : resolve())));
     }
@@ -2088,6 +2319,13 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Unsubscribe from object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the subscription is removed
+     */
     unsubscribe(pattern, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2095,9 +2333,22 @@ export class ObjectsInRedisClient {
         }
         return this.unsubscribeConfig(pattern, options, callback);
     }
+    /**
+     * Promise-version of unsubscribe
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
     unsubscribeAsync(pattern, options) {
         return new Promise((resolve, reject) => this.unsubscribe(pattern, options, err => (err ? reject(err) : resolve())));
     }
+    /**
+     * Unsubscribe a user from object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the subscription is removed
+     */
     unsubscribeUser(pattern, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2116,6 +2367,12 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Promise-version of unsubscribeUser
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
     unsubscribeUserAsync(pattern, options) {
         return new Promise((resolve, reject) => this.unsubscribeUser(pattern, options, err => (err ? reject(err) : resolve())));
     }
@@ -2153,7 +2410,7 @@ export class ObjectsInRedisClient {
             await this.client.publish(id, message);
         }
     }
-    _chownObject(pattern, options, callback) {
+    _chownObject(pattern, options, userContext, callback) {
         this.getKeys(pattern, options, async (err, keys) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
@@ -2183,7 +2440,7 @@ export class ObjectsInRedisClient {
                     this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                     continue;
                 }
-                if (!obj || !utils.checkObject(obj, options, CONSTS.ACCESS_WRITE)) {
+                if (!obj || !utils.checkObject(obj, userContext, CONSTS.ACCESS_WRITE)) {
                     continue;
                 }
                 if (!obj.acl) {
@@ -2214,20 +2471,22 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithError(callback, null, filteredObjs);
         }, true);
     }
+    /**
+     * Change the owner and owner group of all objects matching the given pattern
+     *
+     * @param pattern The pattern of object ids whose owner should be changed
+     * @param options The current request options including the new owner and the user, or the callback
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the objects
+     * @param options.ownerGroup The new owner group to assign to the objects
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     * @param callback Called with the list of changed objects
+     */
     chownObject(pattern, options, callback) {
-        if (typeof options === 'function') {
-            callback = options;
-            options = {};
-        }
-        options = options || {};
-        options.acl = null;
-        if (typeof options !== 'object') {
-            options = { owner: options };
-        }
-        if (!options.ownerGroup && options.group) {
+        if (options?.group && !options.ownerGroup) {
             options.ownerGroup = options.group;
         }
-        if (!options.owner && options.user) {
+        if (options?.user && !options.owner) {
             options.owner = options.user;
         }
         if (!options.owner) {
@@ -2237,28 +2496,38 @@ export class ObjectsInRedisClient {
         if (!options.ownerGroup) {
             // get user group
             this.getUserGroup(options.owner, (user, groups /* , permissions*/) => {
-                if (!groups || !groups[0]) {
+                if (!groups?.[0]) {
                     return tools.maybeCallbackWithError(callback, `user "${options.owner}" belongs to no group`);
                 }
                 options.ownerGroup = groups[0];
-                this.chownObject(pattern, options, callback);
+                return this.chownObject(pattern, options, callback);
             });
             return;
         }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, options) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithRedisError(callback, err);
             }
-            if (!options.acl.object || !options.acl.object.write) {
+            if (!userContext.acl.object || !userContext.acl.object.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            return this._chownObject(pattern, options, callback);
+            return this._chownObject(pattern, options, userContext, callback);
         });
     }
+    /**
+     * Promise-version of chownObject
+     *
+     * @param pattern The pattern of object ids whose owner should be changed
+     * @param options The current request options including the new owner and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the objects
+     * @param options.ownerGroup The new owner group to assign to the objects
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     */
     chownObjectAsync(pattern, options) {
         return new Promise((resolve, reject) => this.chownObject(pattern, options, (err, list) => (err ? reject(err) : resolve(list))));
     }
-    _chmodObject(pattern, options, callback) {
+    _chmodObject(pattern, options, userContext, callback) {
         this.getKeys(pattern, options, async (err, keys) => {
             if (err) {
                 return tools.maybeCallbackWithRedisError(callback, err);
@@ -2288,7 +2557,7 @@ export class ObjectsInRedisClient {
                     this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${strObj}`);
                     continue;
                 }
-                if (!utils.checkObject(obj, options, CONSTS.ACCESS_WRITE) || !obj) {
+                if (!utils.checkObject(obj, userContext, CONSTS.ACCESS_WRITE) || !obj) {
                     continue;
                 }
                 if (!obj.acl) {
@@ -2321,15 +2590,21 @@ export class ObjectsInRedisClient {
             }
         }, true);
     }
+    /**
+     * Change the file mode (permissions) of all files matching the given pattern
+     *
+     * @param pattern The pattern of object ids whose files should be changed
+     * @param options The current request options including the new mode and the user, or the callback
+     * @param options.mode The new permission mode to apply
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.object The permission bitmask for object access
+     * @param options.state The permission bitmask for state access
+     * @param callback Called with the list of changed objects
+     */
     chmodObject(pattern, options, callback) {
-        if (typeof options === 'function') {
-            callback = options;
-            options = null;
-        }
-        options = options || {};
-        options.acl = null;
-        if (typeof options !== 'object') {
-            options = { object: options };
+        if (!options) {
+            this.log.error(`${this.namespace} mode is not defined`);
+            return tools.maybeCallbackWithError(callback, 'invalid parameter');
         }
         if (options.mode && !options.object) {
             options.object = options.mode;
@@ -2341,20 +2616,30 @@ export class ObjectsInRedisClient {
         else if (typeof options.mode === 'string') {
             options.mode = parseInt(options.mode, 16);
         }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, options) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithRedisError(callback, err);
             }
-            if (!options.acl.file.write) {
+            if (!userContext.acl.file.write) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
-            return this._chmodObject(pattern, options, callback);
+            return this._chmodObject(pattern, options, userContext, callback);
         });
     }
+    /**
+     * Promise-version of chmodObject
+     *
+     * @param pattern The pattern of object ids whose files should be changed
+     * @param options The current request options including the new mode and the user
+     * @param options.mode The new permission mode to apply
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.object The permission bitmask for object access
+     * @param options.state The permission bitmask for state access
+     */
     chmodObjectAsync(pattern, options) {
         return new Promise((resolve, reject) => this.chmodObject(pattern, options, (err, list) => (err ? reject(err) : resolve(list))));
     }
-    async _getObject(id, options, callback) {
+    async _getObject(id, userContext, callback) {
         if (!this.client) {
             return tools.maybeCallbackWithRedisError(callback, ERRORS.ERROR_DB_CLOSED);
         }
@@ -2381,13 +2666,20 @@ export class ObjectsInRedisClient {
         }
         if (obj) {
             // Check permissions
-            if (utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+            if (utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                 return tools.maybeCallbackWithError(callback, null, obj);
             }
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
         }
         return tools.maybeCallbackWithRedisError(callback, err, obj);
     }
+    /**
+     * Get a single object by its id
+     *
+     * @param id The id of the object to read
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the read object
+     */
     getObject(id, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2397,27 +2689,25 @@ export class ObjectsInRedisClient {
             return new Promise((resolve, reject) => this.getObject(id, options, (err, obj) => (err ? reject(err) : resolve(obj))));
         }
         if (typeof callback === 'function') {
-            if (options?.acl) {
-                options.acl = null;
-            }
-            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, options) => {
+            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithError(callback, err);
                 }
-                return this._getObject(id, options, callback);
+                return this._getObject(id, userContext, callback);
             });
         }
     }
     /**
+     * Promise-version of getObject
      *
-     * @param id
-     * @param options
+     * @param id The id of the object to read
+     * @param options The current request options including the user
      * @deprecated use `getObject` without callback instead
      */
     getObjectAsync(id, options) {
         return new Promise((resolve, reject) => this.getObject(id, options, (err, obj) => (err ? reject(err) : resolve(obj))));
     }
-    async _getKeys(pattern, options, callback, dontModify) {
+    async _getKeys(pattern, userContext, dontModify, callback) {
         if (!this.client) {
             return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
         }
@@ -2439,9 +2729,9 @@ export class ObjectsInRedisClient {
         if (keys) {
             keys.sort();
             const result = [];
-            const dontCheck = options.user === CONSTS.SYSTEM_ADMIN_USER ||
-                options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-                options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
+            const dontCheck = userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+                userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+                userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP);
             if (dontCheck) {
                 for (let i = 0; i < keys.length; i++) {
                     const id = keys[i].substring(this.objNamespaceL);
@@ -2475,7 +2765,7 @@ export class ObjectsInRedisClient {
                     this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${metaStr}`);
                     continue;
                 }
-                if (r.test(keys[i]) && utils.checkObject(meta, options, CONSTS.ACCESS_READ)) {
+                if (r.test(keys[i]) && utils.checkObject(meta, userContext, CONSTS.ACCESS_READ)) {
                     if (!dontModify) {
                         result.push(keys[i].substring(this.objNamespaceL));
                     }
@@ -2488,6 +2778,14 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallbackWithError(callback, null, result);
     }
+    /**
+     * Get all object ids matching the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the matching keys
+     * @param dontModify If true, the returned keys are not stripped of the namespace
+     */
     getKeys(pattern, options, callback, dontModify) {
         if (typeof options === 'function') {
             callback = options;
@@ -2497,18 +2795,25 @@ export class ObjectsInRedisClient {
             return new Promise((resolve, reject) => this.getKeys(pattern, options, (err, obj) => (err ? reject(err) : resolve(obj)), dontModify));
         }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, 'list', (err, options) => {
+            utils.checkObjectRights(this, null, null, options, 'list', (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithRedisError(callback, err);
                 }
-                return this._getKeys(pattern, options, callback, dontModify);
+                return this._getKeys(pattern, userContext, dontModify, callback);
             });
         }
     }
-    getKeysAsync(id, options) {
-        return this.getKeys(id, options);
+    /**
+     * Promise-version of getKeys
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the keys are read
+     */
+    getKeysAsync(pattern, options) {
+        return this.getKeys(pattern, options);
     }
-    async _getObjects(keys, options, callback, dontModify) {
+    async _getObjects(keys, userContext, callback, dontModify) {
         if (!keys) {
             return tools.maybeCallbackWithError(callback, 'no keys');
         }
@@ -2540,10 +2845,10 @@ export class ObjectsInRedisClient {
         }
         let result = [];
         if (objs) {
-            const dontCheck = options &&
-                (options.user === CONSTS.SYSTEM_ADMIN_USER ||
-                    options.group !== CONSTS.SYSTEM_ADMIN_GROUP ||
-                    options.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP));
+            const dontCheck = userContext &&
+                (userContext.user === CONSTS.SYSTEM_ADMIN_USER ||
+                    userContext.group === CONSTS.SYSTEM_ADMIN_GROUP ||
+                    userContext.groups?.includes(CONSTS.SYSTEM_ADMIN_GROUP));
             if (!dontCheck) {
                 for (let i = 0; i < objs.length; i++) {
                     const strObj = objs[i];
@@ -2557,7 +2862,7 @@ export class ObjectsInRedisClient {
                         result.push({ error: ERRORS.ERROR_PERMISSION });
                         continue;
                     }
-                    if (utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+                    if (utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                         result.push(obj);
                     }
                     else {
@@ -2579,6 +2884,14 @@ export class ObjectsInRedisClient {
         }
         return tools.maybeCallbackWithError(callback, null, result);
     }
+    /**
+     * Get multiple objects by their ids
+     *
+     * @param keys The ids of the objects to read
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the read objects
+     * @param dontModify If true, the returned objects are not cloned/modified
+     */
     getObjects(keys, options, callback, dontModify) {
         if (typeof options === 'function') {
             callback = options;
@@ -2589,22 +2902,25 @@ export class ObjectsInRedisClient {
             // @ts-expect-error need to clarify, that objs is not undefined if no error is provided
             this.getObjects(keys, options, (err, objs) => (err ? reject(err) : resolve(objs)), dontModify));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, options) => {
+            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithRedisError(callback, err);
                 }
-                return this._getObjects(keys, options, callback, dontModify);
+                return this._getObjects(keys, userContext, callback, dontModify);
             });
         }
     }
+    /**
+     * Promise-version of getObjects
+     *
+     * @param keys The ids of the objects to read
+     * @param options The current request options including the user
+     */
     getObjectsAsync(keys, options) {
         return this.getObjects(keys, options);
     }
-    async _getObjectsByPattern(pattern, options, callback) {
+    async _getObjectsByPattern(pattern, userContext, callback) {
         if (!pattern || typeof pattern !== 'string') {
             return tools.maybeCallbackWithError(callback, `invalid pattern ${JSON.stringify(pattern)}`);
         }
@@ -2624,8 +2940,15 @@ export class ObjectsInRedisClient {
         if (this.settings.connection.enhancedLogging) {
             this.log.silly(`${this.namespace} redis keys ${keys.length} ${pattern}`);
         }
-        this._getObjects(keys, options, callback, true);
+        this._getObjects(keys, userContext, callback, true).catch(e => this.log.error(`${this.namespace} Cannot get objects: ${e.message}`));
     }
+    /**
+     * Get all objects whose id matches the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the matching objects
+     */
     getObjectsByPattern(pattern, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -2634,22 +2957,26 @@ export class ObjectsInRedisClient {
         if (!callback) {
             return new Promise((resolve, reject) => this.getObjectsByPattern(pattern, options, (err, obj) => (err ? reject(err) : resolve(obj))));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, options) => {
+            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_READ, (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithRedisError(callback, err);
                 }
-                return this._getObjectsByPattern(pattern, options, callback);
+                return this._getObjectsByPattern(pattern, userContext, callback);
             });
         }
     }
+    /**
+     * Promise-version of getObjectsByPattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the objects are read
+     */
     getObjectsByPatternAsync(pattern, options) {
         return new Promise((resolve, reject) => this.getObjectsByPattern(pattern, options, (err, objs) => (err ? reject(err) : resolve(objs))));
     }
-    async _setObject(id, obj, options) {
+    async _setObject(id, obj, userContext) {
         if (!id || typeof id !== 'string' || utils.REG_CHECK_ID.test(id)) {
             throw new Error(`Invalid ID: ${id}`);
         }
@@ -2658,7 +2985,7 @@ export class ObjectsInRedisClient {
             throw new Error('obj is null');
         }
         if (!tools.isObject(obj)) {
-            this.log.warn(`${this.namespace} setObject: Argument object is no object: ${obj}`);
+            this.log.warn(`${this.namespace} setObject: Argument object is no object: ${JSON.stringify(obj)}`);
             throw new Error('obj is no object');
         }
         if (!this.client) {
@@ -2776,16 +3103,16 @@ export class ObjectsInRedisClient {
                 delete obj.acl.state;
             }
             // take the current user as owner if given, but if admin we keep default
-            if (options.user && options.user !== CONSTS.SYSTEM_ADMIN_USER) {
-                obj.acl.owner = options.user;
+            if (userContext.user && userContext.user !== CONSTS.SYSTEM_ADMIN_USER) {
+                obj.acl.owner = userContext.user;
             }
             // take the current group as owner if given, but if admin we keep default
-            if (options.group && options.group !== CONSTS.SYSTEM_ADMIN_GROUP) {
-                obj.acl.ownerGroup = options.group;
+            if (userContext.group && userContext.group !== CONSTS.SYSTEM_ADMIN_GROUP) {
+                obj.acl.ownerGroup = userContext.group;
             }
         }
-        if (this.defaultNewAcl && obj.acl && !obj.acl.ownerGroup && options.group) {
-            obj.acl.ownerGroup = options.group;
+        if (this.defaultNewAcl && obj.acl && !obj.acl.ownerGroup && userContext.group) {
+            obj.acl.ownerGroup = userContext.group;
         }
         const message = JSON.stringify(obj);
         const commands = [];
@@ -2828,12 +3155,12 @@ export class ObjectsInRedisClient {
         return { id };
     }
     /**
-     * set anew or update object
+     * set anew or update an object
      *
      * This function writes the object into DB
      *
      * @param id ID of the object
-     * @param obj
+     * @param obj The object to write
      * @param options options for access control are optional
      * @param callback return function
      */
@@ -2845,16 +3172,13 @@ export class ObjectsInRedisClient {
         if (!callback) {
             return new Promise((resolve, reject) => this.setObject(id, obj, options, (err, res) => (err ? reject(err) : resolve(res))));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, async (err) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, async (err, userContext) => {
             // do not use options from checkObjectRights because this will mess up configured default acl
             if (err) {
                 return tools.maybeCallbackWithRedisError(callback, err);
             }
             try {
-                const res = await this._setObject(id, obj, options || {});
+                const res = await this._setObject(id, obj, userContext);
                 return tools.maybeCallbackWithError(callback, null, res);
             }
             catch (e) {
@@ -2863,10 +3187,11 @@ export class ObjectsInRedisClient {
         });
     }
     /**
+     * Promise-version of setObject
      *
-     * @param id
-     * @param obj
-     * @param options
+     * @param id ID of the object
+     * @param obj The object to write
+     * @param options options for access control are optional
      * @deprecated use `setObject` without callback instead
      */
     setObjectAsync(id, obj, options) {
@@ -2874,7 +3199,7 @@ export class ObjectsInRedisClient {
         // @ts-expect-error TODO we are returning type Object for ease of use to devs, but formally these are AnyObjects, e.g. not guaranteed to have common
         this.setObject(id, obj, options, (err, res) => (err ? reject(err) : resolve(res))));
     }
-    async _delObject(id, options) {
+    async _delObject(id, userContext) {
         if (!id || typeof id !== 'string' || utils.REG_CHECK_ID.test(id)) {
             throw new Error(`Invalid ID: ${id}`);
         }
@@ -2903,7 +3228,7 @@ export class ObjectsInRedisClient {
             this.log.warn(`${this.namespace} Cannot parse ${id} - ${oldObjStr}: ${e.message}`);
             oldObj = null;
         }
-        if (!utils.checkObject(oldObj, options, CONSTS.ACCESS_WRITE)) {
+        if (!utils.checkObject(oldObj, userContext, CONSTS.ACCESS_WRITE)) {
             throw new Error(ERRORS.ERROR_PERMISSION);
         }
         else {
@@ -2935,23 +3260,27 @@ export class ObjectsInRedisClient {
             await this.client.publish(this.objNamespace + id, 'null');
         }
     }
+    /**
+     * Delete an object
+     *
+     * @param id The id of the object to delete
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the object has been deleted
+     */
     delObject(id, options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
         if (!callback) {
-            return new Promise((resolve, reject) => this.delObject(id, options, err => (err ? reject(err) : resolve())));
+            return new Promise((resolve, reject) => this.delObject(id, options, err => err ? reject(err) : resolve()));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_DELETE, async (err, options) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_DELETE, async (err, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithError(callback, err);
             }
             try {
-                await this._delObject(id, options);
+                await this._delObject(id, userContext);
                 return tools.maybeCallback(callback);
             }
             catch (e) {
@@ -2959,11 +3288,18 @@ export class ObjectsInRedisClient {
             }
         });
     }
+    /**
+     * Promise-version of delObject
+     *
+     * @param id The id of the object to delete
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
     delObjectAsync(id, options) {
         return this.delObject(id, options);
     }
     /**
-     * Function to checks if comparisons will work according to the configured Locale
+     * Function to check if comparisons will work according to the configured Locale
      */
     async isSystemLocaleSupported() {
         if (!this.client) {
@@ -2979,15 +3315,13 @@ export class ObjectsInRedisClient {
         }
     }
     // this function is very ineffective. Because reads all objects and then process them
-    async _applyViewFunc(func, params, options = {}) {
+    async _applyViewFunc(func, params, userContext) {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        const result = {
-            rows: [],
-        };
+        let rows = [];
         /**
-         * filters objs which are already present (and parse Errors) in array by property 'id'
+         * filters objs which are already present (and parse Errors) in an array by property 'id'
          *
          * @param arr - Array of objects which should be filtered
          * @param duplicateFiltering - if duplicates need to be filtered
@@ -3008,9 +3342,9 @@ export class ObjectsInRedisClient {
                 return obj.value !== null;
             });
         };
-        params = params || {};
-        params.startkey = params.startkey || '';
-        params.endkey = params.endkey || '\u9999';
+        params ||= {};
+        params.startkey ||= '';
+        params.endkey ||= '\u9999';
         const wildcardPos = params.endkey.indexOf('\u9999');
         let wildCardLastPos = true;
         if (wildcardPos !== -1 && wildcardPos !== params.endkey.length - 1) {
@@ -3031,16 +3365,7 @@ export class ObjectsInRedisClient {
                 }
                 let objs;
                 try {
-                    objs = await this.client.evalsha([
-                        this.scripts.filter,
-                        6,
-                        this.objNamespace,
-                        params.startkey,
-                        params.endkey,
-                        matches[1],
-                        cursor,
-                        `${this.setNamespace}object.type.${matches[1]}`,
-                    ]);
+                    objs = (await this.client.evalsha(this.scripts.filter, 6, this.objNamespace, params.startkey, params.endkey, matches[1], cursor, `${this.setNamespace}object.type.${matches[1]}`));
                 }
                 catch (e) {
                     this.log.warn(`${this.namespace} Cannot get view: ${e.message}`);
@@ -3072,7 +3397,7 @@ export class ObjectsInRedisClient {
                     if (matches[2] && matches[2].trim() === 'doc._id') {
                         return { id: obj._id, value: obj };
                     }
-                    else if (matches[2] && matches[2].trim() === 'doc.common.name' && obj.common) {
+                    if (matches[2] && matches[2].trim() === 'doc.common.name' && obj.common) {
                         if (typeof obj.common.name === 'object') {
                             if (obj.common.name.en) {
                                 return { id: obj.common.name.en, value: obj };
@@ -3085,29 +3410,30 @@ export class ObjectsInRedisClient {
                     return { id: 'parseError', value: null };
                 });
                 if (currRows.length) {
-                    result.rows = [...result.rows, ...currRows];
+                    rows = [...rows, ...currRows];
                 } // endIf
             } while (cursor !== '0');
             // Now we have all objects -> calculate max if desired
             if (func.reduce === '_stats') {
                 let max = null;
-                for (let i = 0; i < result.rows.length; i++) {
-                    if (max === null || result.rows[i].value > max) {
-                        max = result.rows[i].value;
+                for (let i = 0; i < rows.length; i++) {
+                    const _value = rows[i].value;
+                    if (max === null || (_value !== null && _value > max)) {
+                        max = _value;
                     }
                 }
                 if (max !== null) {
-                    result.rows = [{ id: '_stats', value: { max: max } }];
+                    // @ts-expect-error missing typing
+                    rows = [{ id: '_stats', value: { max } }];
                 }
                 else {
-                    result.rows = [];
+                    rows = [];
                 }
             }
             // apply filter if needed
-            result.rows = filterEntries(result.rows, filterRequired);
-            return result;
+            return { rows: filterEntries(rows, filterRequired) };
         }
-        else if (
+        if (
         // filter by script
         wildCardLastPos &&
             func?.map &&
@@ -3121,15 +3447,7 @@ export class ObjectsInRedisClient {
                 }
                 let res;
                 try {
-                    res = await this.client.evalsha([
-                        this.scripts.script,
-                        5,
-                        this.objNamespace,
-                        params.startkey,
-                        params.endkey,
-                        cursor,
-                        `${this.setNamespace}object.type.script`,
-                    ]);
+                    res = (await this.client.evalsha(this.scripts.script, 5, this.objNamespace, params.startkey, params.endkey, cursor, `${this.setNamespace}object.type.script`));
                 }
                 catch (e) {
                     this.log.warn(`${this.namespace} Cannot get "scripts" view: ${e.message}`);
@@ -3157,14 +3475,13 @@ export class ObjectsInRedisClient {
                     }
                 });
                 if (currRows.length) {
-                    result.rows = [...result.rows, ...currRows];
+                    rows = [...rows, ...currRows];
                 } // endIf
             } while (cursor !== '0');
             // apply filter if needed
-            result.rows = filterEntries(result.rows, filterRequired);
-            return result;
+            return { rows: filterEntries(rows, filterRequired) };
         }
-        else if (
+        if (
         // filter by hm-rega programs
         wildCardLastPos &&
             func?.map &&
@@ -3178,15 +3495,7 @@ export class ObjectsInRedisClient {
                 }
                 let objs;
                 try {
-                    objs = await this.client.evalsha([
-                        this.scripts.programs,
-                        5,
-                        `${this.objNamespace}hm-rega.`,
-                        params.startkey,
-                        params.endkey,
-                        cursor,
-                        `${this.setNamespace}object.type.channel`,
-                    ]);
+                    objs = (await this.client.evalsha(this.scripts.programs, 5, `${this.objNamespace}hm-rega.`, params.startkey, params.endkey, cursor, `${this.setNamespace}object.type.channel`));
                 }
                 catch (e) {
                     this.log.warn(`${this.namespace} Cannot get view: ${e.message}`);
@@ -3212,14 +3521,13 @@ export class ObjectsInRedisClient {
                     }
                 });
                 if (currRows.length) {
-                    result.rows = [...result.rows, ...currRows];
+                    rows = [...rows, ...currRows];
                 } // endIf
             } while (cursor !== '0');
             // apply filter if needed
-            result.rows = filterEntries(result.rows, filterRequired);
-            return result;
+            return { rows: filterEntries(rows, filterRequired) };
         }
-        else if (
+        if (
         // filter by hm-rega variables
         wildCardLastPos &&
             func?.map &&
@@ -3233,15 +3541,7 @@ export class ObjectsInRedisClient {
                 }
                 let objs;
                 try {
-                    objs = await this.client.evalsha([
-                        this.scripts.variables,
-                        5,
-                        `${this.objNamespace}hm-rega.`,
-                        params.startkey,
-                        params.endkey,
-                        cursor,
-                        `${this.setNamespace}object.type.state`,
-                    ]);
+                    objs = (await this.client.evalsha(this.scripts.variables, 5, `${this.objNamespace}hm-rega.`, params.startkey, params.endkey, cursor, `${this.setNamespace}object.type.state`));
                 }
                 catch (e) {
                     this.log.warn(`${this.namespace} Cannot get view ${e.message}`);
@@ -3267,14 +3567,13 @@ export class ObjectsInRedisClient {
                     }
                 });
                 if (currRows.length) {
-                    result.rows = [...result.rows, ...currRows];
+                    rows = [...rows, ...currRows];
                 } // endIf
             } while (cursor !== '0');
             // apply filter if needed
-            result.rows = filterEntries(result.rows, filterRequired);
-            return result;
+            return { rows: filterEntries(rows, filterRequired) };
         }
-        else if (
+        if (
         // filter by custom, redis also returns if common.custom is not present
         wildCardLastPos &&
             func?.map &&
@@ -3288,15 +3587,7 @@ export class ObjectsInRedisClient {
                 }
                 let objs;
                 try {
-                    objs = await this.client.evalsha([
-                        this.scripts.custom,
-                        5,
-                        this.objNamespace,
-                        params.startkey,
-                        params.endkey,
-                        cursor,
-                        `${this.setNamespace}object.common.custom`,
-                    ]);
+                    objs = (await this.client.evalsha(this.scripts.custom, 5, this.objNamespace, params.startkey, params.endkey, cursor, `${this.setNamespace}object.common.custom`));
                 }
                 catch (e) {
                     this.log.warn(`${this.namespace} Cannot get view: ${e.message}`);
@@ -3323,17 +3614,17 @@ export class ObjectsInRedisClient {
                     }
                     if (obj?.common?.custom) {
                         if (useFullObject) {
-                            result.rows.push({ id: obj._id, value: obj });
+                            rows.push({ id: obj._id, value: obj });
                         }
                         else {
-                            result.rows.push({ id: obj._id, value: obj.common.custom });
+                            // @ts-expect-error missing typing
+                            rows.push({ id: obj._id, value: obj.common.custom });
                         }
                     }
                 }
             } while (cursor !== '0');
             // apply filter if needed
-            result.rows = filterEntries(result.rows, filterRequired);
-            return result;
+            return { rows: filterEntries(rows, filterRequired) };
         }
         if (!wildCardLastPos) {
             this.log.debug(`${this.namespace} Search can't be optimized because wildcard not at the end, fallback to keys!: ${func.map}`);
@@ -3381,7 +3672,7 @@ export class ObjectsInRedisClient {
             objs = [];
         }
         const _emit_ = (id, obj) => {
-            result.rows.push({ id: id, value: obj });
+            rows.push({ id: id, value: obj });
         };
         const f = eval(`(${func.map.replace(/^function\(([a-z0-9A-Z_]+)\)/g, 'function($1, emit)')})`);
         for (let i = 0; i < keys.length; i++) {
@@ -3394,7 +3685,7 @@ export class ObjectsInRedisClient {
                 this.log.error(`${this.namespace} Cannot parse JSON ${keys[i]}: ${objs[i]}`);
                 continue;
             }
-            if (!utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+            if (!utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                 continue;
             }
             if (obj) {
@@ -3409,21 +3700,23 @@ export class ObjectsInRedisClient {
         // Calculate max
         if (func.reduce === '_stats') {
             let max = null;
-            for (let i = 0; i < result.rows.length; i++) {
-                if (max === null || result.rows[i].value > max) {
-                    max = result.rows[i].value;
+            for (let i = 0; i < rows.length; i++) {
+                const _value = rows[i].value;
+                if (max === null || (_value !== null && _value > max)) {
+                    max = rows[i].value;
                 }
             }
             if (max !== null) {
-                result.rows = [{ id: '_stats', value: { max: max } }];
+                // @ts-expect-error the _stats reduce result is not a regular object value
+                rows = [{ id: '_stats', value: { max } }];
             }
             else {
-                result.rows = [];
+                rows = [];
             }
         }
-        return result;
+        return { rows: rows };
     }
-    async _getObjectView(design, search, params, options) {
+    async _getObjectView(design, search, params, userContext) {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
@@ -3444,7 +3737,8 @@ export class ObjectsInRedisClient {
                 throw new Error(`Cannot parse JSON: "_design/${design}" / "${obj}"`);
             }
             if (obj.views?.[search]) {
-                return this._applyViewFunc(obj.views[search], params, options);
+                // @ts-expect-error missing typing
+                return this._applyViewFunc(obj.views[search], params, userContext);
             }
             this.log.error(`${this.namespace} Cannot find search "${search}" in "${design}"`);
             throw new Error(`Cannot find search "${search}" in "${design}"`);
@@ -3454,6 +3748,15 @@ export class ObjectsInRedisClient {
             throw new Error(`Cannot find view "${design}"`);
         }
     }
+    /**
+     * Run a predefined object view (design document) and return the matching rows
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the matching rows
+     */
     getObjectView(design, search, params, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -3462,16 +3765,13 @@ export class ObjectsInRedisClient {
         if (!callback) {
             return new Promise((resolve, reject) => this.getObjectView(design, search, params, options, (err, obj) => (err ? reject(err) : resolve(obj))));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, 'list', async (err, options) => {
+            utils.checkObjectRights(this, null, null, options, 'list', async (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithRedisError(callback, err);
                 }
                 try {
-                    const res = await this._getObjectView(design, search, params, options);
+                    const res = await this._getObjectView(design, search, params, userContext);
                     return tools.maybeCallbackWithError(callback, null, res);
                 }
                 catch (e) {
@@ -3480,16 +3780,25 @@ export class ObjectsInRedisClient {
             });
         }
     }
+    /**
+     * Promise-version of getObjectView
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the view is queried
+     */
     getObjectViewAsync(design, search, params, options) {
         return this.getObjectView(design, search, params, options);
     }
-    async _getObjectList(params, options) {
+    async _getObjectList(params, userContext) {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        params = params || {};
-        params.startkey = params.startkey || '';
-        params.endkey = params.endkey || '\u9999';
+        params ||= {};
+        params.startkey ||= '';
+        params.endkey ||= '\u9999';
         const pattern = params.endkey.substring(0, params.startkey.length) === params.startkey
             ? `${this.objNamespace + params.startkey}*`
             : `${this.objNamespace}*`;
@@ -3538,7 +3847,7 @@ export class ObjectsInRedisClient {
                     this.log.error(`${this.namespace} Cannot parse JSON ${_keys[i]}: ${objs[i]}`);
                     continue;
                 }
-                if (!obj || !utils.checkObject(obj, options, CONSTS.ACCESS_READ)) {
+                if (!obj || !utils.checkObject(obj, userContext, CONSTS.ACCESS_READ)) {
                     continue;
                 }
                 // @ts-expect-error TODO we are returning type Object for ease of use to devs, but formally these are AnyObjects, e.g. not guaranteed to have common
@@ -3547,6 +3856,13 @@ export class ObjectsInRedisClient {
         }
         return result;
     }
+    /**
+     * Get the list of objects matching the given parameters
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the matching objects
+     */
     getObjectList(params, options, callback) {
         if (typeof options === 'function') {
             callback = options;
@@ -3555,16 +3871,13 @@ export class ObjectsInRedisClient {
         if (!callback) {
             return new Promise((resolve, reject) => this.getObjectList(params, options, (err, obj) => (err ? reject(err) : resolve(obj))));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, 'list', async (err, options) => {
+            utils.checkObjectRights(this, null, null, options, 'list', async (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithRedisError(callback, err);
                 }
                 try {
-                    const res = await this._getObjectList(params, options || {});
+                    const res = await this._getObjectList(params, userContext);
                     return tools.maybeCallbackWithError(callback, null, res);
                 }
                 catch (e) {
@@ -3573,35 +3886,34 @@ export class ObjectsInRedisClient {
             });
         }
     }
+    /**
+     * Promise-version of getObjectList
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     */
     getObjectListAsync(params, options) {
         return this.getObjectList(params, options);
     }
-    // could be optimized, to read object only once. Now it will read 3 times
-    async _extendObject(id, obj, options, callback) {
+    // could be optimized, to read an object only once. Now it will read 3 times
+    async _extendObject(id, obj, options, userContext) {
         if (!id || typeof id !== 'string' || utils.REG_CHECK_ID.test(id)) {
-            // @ts-expect-error we fix when removing cb
-            return tools.maybeCallbackWithError(callback, `Invalid ID: ${id}`);
+            throw new Error(`Invalid ID: ${id}`);
         }
         if (!this.client) {
-            return tools.maybeCallbackWithRedisError(callback, ERRORS.ERROR_DB_CLOSED);
+            throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
+        const oldObjStr = await this.client.get(this.objNamespace + id);
         let oldObj;
         try {
-            oldObj = await this.client.get(this.objNamespace + id);
-        }
-        catch (e) {
-            return tools.maybeCallbackWithRedisError(callback, e);
-        }
-        try {
-            oldObj = oldObj ? JSON.parse(oldObj) : null;
+            oldObj = oldObjStr ? JSON.parse(oldObjStr) : null;
         }
         catch {
-            this.log.error(`${this.namespace} Cannot parse JSON ${id}: ${oldObj}`);
-            // @ts-expect-error we fix when removing cb
-            return tools.maybeCallbackWithError(callback, `Cannot parse JSON ${id}: ${oldObj}`);
+            this.log.error(`${this.namespace} Cannot parse JSON ${id}: ${oldObjStr}`);
+            throw new Error(`Cannot parse JSON ${id}: ${oldObjStr}`);
         }
-        if (!utils.checkObject(oldObj, options, CONSTS.ACCESS_WRITE)) {
-            return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
+        if (!utils.checkObject(oldObj, userContext, CONSTS.ACCESS_WRITE)) {
+            throw new Error(ERRORS.ERROR_PERMISSION);
         }
         let _oldObj;
         if (oldObj?.nonEdit) {
@@ -3610,150 +3922,140 @@ export class ObjectsInRedisClient {
         }
         // we need to know if custom has been added/deleted
         const oldObjHasCustom = !!oldObj?.common?.custom;
-        oldObj = oldObj || {};
-        obj = deepClone(obj); // copy here to prevent "sandboxed" objects from JavaScript adapter
-        if (oldObj.common &&
-            oldObj.common.custom !== undefined &&
-            oldObj.common.custom !== null &&
-            !tools.isObject(oldObj.common.custom)) {
+        // Clone the update here to prevent "sandboxed" objects from the JavaScript adapter
+        const objClone = deepClone(obj);
+        // Start from the existing object so the update is merged into it instead of replacing it
+        let oldObjNotNull = oldObj || {};
+        if (oldObjNotNull.common?.custom !== undefined &&
+            oldObjNotNull.common.custom !== null &&
+            !tools.isObject(oldObjNotNull.common.custom)) {
             // custom has to be an object, else clean up
-            delete oldObj.common.custom;
+            delete oldObjNotNull.common.custom;
         }
         // we need to check if type has changed
-        const oldType = oldObj.type;
-        oldObj = extend(true, oldObj, obj);
-        oldObj._id = id;
+        const oldType = oldObjNotNull.type;
+        oldObjNotNull = extend(true, oldObjNotNull, objClone);
+        oldObjNotNull._id = id;
         // add user default rights
-        if (this.defaultNewAcl && !oldObj.acl) {
-            oldObj.acl = deepClone(this.defaultNewAcl);
-            delete oldObj.acl.file;
-            if (oldObj.type !== 'state') {
-                delete oldObj.acl.state;
+        if (this.defaultNewAcl && !oldObjNotNull.acl) {
+            oldObjNotNull.acl = {
+                owner: this.defaultNewAcl.owner,
+                ownerGroup: this.defaultNewAcl.ownerGroup,
+                object: this.defaultNewAcl.object,
+            };
+            if (oldObjNotNull.type === 'state') {
+                oldObjNotNull.acl.state = this.defaultNewAcl.state;
             }
             if (options.owner) {
-                oldObj.acl.owner = options.owner;
+                oldObjNotNull.acl.owner = options.owner;
                 if (!options.ownerGroup) {
-                    oldObj.acl.ownerGroup = null;
-                    return void this.getUserGroup(options.owner, (user, groups /*, permissions */) => {
-                        if (!groups || !groups[0]) {
-                            options.ownerGroup = this.defaultNewAcl?.ownerGroup || CONSTS.SYSTEM_ADMIN_GROUP;
-                        }
-                        else {
-                            options.ownerGroup = groups[0];
-                        }
-                        this._extendObject(id, obj, options, callback);
-                    });
+                    const [, groups] = await utils.getUserGroupAsync(this, options.owner);
+                    if (!groups?.[0]) {
+                        options.ownerGroup = this.defaultNewAcl.ownerGroup || CONSTS.SYSTEM_ADMIN_GROUP;
+                    }
+                    else {
+                        options.ownerGroup = groups[0];
+                    }
                 }
             }
         }
-        if (this.defaultNewAcl && options.ownerGroup && oldObj.acl && !oldObj.acl.ownerGroup) {
-            oldObj.acl.ownerGroup = options.ownerGroup;
+        if (this.defaultNewAcl && options.ownerGroup && oldObjNotNull.acl && !oldObjNotNull.acl.ownerGroup) {
+            oldObjNotNull.acl.ownerGroup = options.ownerGroup;
         }
         if (obj.common && 'alias' in obj.common && obj.common.alias.id) {
             if (typeof obj.common.alias.id === 'object') {
                 if (typeof obj.common.alias.id.write !== 'string' || typeof obj.common.alias.id.read !== 'string') {
-                    return tools.maybeCallbackWithError(callback, 'Invalid alias ID');
+                    throw new Error('Invalid alias ID');
                 }
                 if (obj.common.alias.id.write.startsWith('alias.') || obj.common.alias.id.read.startsWith('alias.')) {
-                    return tools.maybeCallbackWithError(callback, 'Cannot make alias on alias');
+                    throw new Error('Cannot make alias on alias');
                 }
             }
             else {
                 if (typeof obj.common.alias.id !== 'string') {
-                    return tools.maybeCallbackWithError(callback, 'Invalid alias ID');
+                    throw new Error('Invalid alias ID');
                 }
                 if (obj.common.alias.id.startsWith('alias.')) {
-                    return tools.maybeCallbackWithError(callback, 'Cannot make alias on alias');
+                    throw new Error('Cannot make alias on alias');
                 }
             }
         }
-        if (_oldObj && !tools.checkNonEditable(_oldObj, oldObj)) {
-            return tools.maybeCallbackWithError(callback, 'Invalid password for update of vendor information');
+        if (_oldObj && !tools.checkNonEditable(_oldObj, oldObjNotNull)) {
+            throw new Error('Invalid password for update of vendor information');
         }
-        const message = JSON.stringify(oldObj);
-        try {
-            const commands = [];
-            if (this.useSets) {
-                // what is called oldObj is acutally the obj we set, because it has been extended
-                if (oldObj.type && !oldType) {
-                    // new object or oldObj had no type -> add to set + set object
-                    commands.push(['sadd', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id]);
-                }
-                else if (oldObj.type && oldType && oldObj.type !== oldType) {
-                    // the old obj had a type which differs from the new type -> rem old, add new
-                    commands.push(['sadd', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id], ['srem', `${this.setNamespace}object.type.${oldObj.type}`, this.objNamespace + id]);
-                }
-                else if (oldType && !oldObj.type) {
-                    // the oldObj had a type, the new one has no -> rem
-                    commands.push(['srem', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id]);
-                }
-            }
-            if (oldObj.common?.custom && !oldObjHasCustom) {
-                // we now have custom, old object had no custom
-                commands.push(['sadd', `${this.setNamespace}object.common.custom`, this.objNamespace + id]);
-            }
-            else if (oldObjHasCustom && (!oldObj.common || !oldObj.common.custom)) {
-                // we no longer have custom
-                commands.push(['srem', `${this.setNamespace}object.common.custom`, this.objNamespace + id]);
-            }
-            if (!commands.length) {
-                await this.client.set(this.objNamespace + id, message);
+        const message = JSON.stringify(oldObjNotNull);
+        const commands = [];
+        if (this.useSets) {
+            // what is called oldObjNotNull is actually the obj we set, because it has been extended
+            if (oldObjNotNull.type && !oldType) {
+                // new object or oldObjNotNull had no type -> add to set + set object
+                commands.push(['sadd', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id]);
             }
-            else {
-                // set all commands atomic
-                commands.push(['set', this.objNamespace + id, message]);
-                await this.client.multi(commands).exec();
+            else if (oldObjNotNull.type && oldType && oldObjNotNull.type !== oldType) {
+                // the old obj had a type which differs from the new type -> rem old, add new
+                commands.push(['sadd', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id], ['srem', `${this.setNamespace}object.type.${oldObjNotNull.type}`, this.objNamespace + id]);
             }
-            // extended -> if its now type meta and currently marked as not -> cache
-            if (this.existingMetaObjects[id] === false && oldObj && oldObj.type === 'meta') {
-                this.existingMetaObjects[id] = true;
+            else if (oldType && !oldObjNotNull.type) {
+                // the oldObjNotNull had a type, the new one has no -> rem
+                commands.push(['srem', `${this.setNamespace}object.type.${obj.type}`, this.objNamespace + id]);
             }
-            await this.client.publish(this.objNamespace + id, message);
-            return tools.maybeCallbackWithError(callback, null, { id: id, value: oldObj }, id);
         }
-        catch (e) {
-            return tools.maybeCallbackWithRedisError(callback, e);
+        if (oldObjNotNull.common?.custom && !oldObjHasCustom) {
+            // we now have custom, old object had no custom
+            commands.push(['sadd', `${this.setNamespace}object.common.custom`, this.objNamespace + id]);
         }
-    }
-    extendObject(id, obj, options, callback) {
-        if (typeof options === 'function') {
-            callback = options;
-            options = null;
+        else if (oldObjHasCustom && (!oldObjNotNull.common || !oldObjNotNull.common.custom)) {
+            // we no longer have custom
+            commands.push(['srem', `${this.setNamespace}object.common.custom`, this.objNamespace + id]);
         }
-        if (!callback) {
-            return new Promise((resolve, reject) => this.extendObject(id, obj, options, (err, res) => (err ? reject(err) : resolve(res))));
+        if (!commands.length) {
+            await this.client.set(this.objNamespace + id, message);
         }
-        if (options?.acl) {
-            options.acl = null;
+        else {
+            // set all commands atomic
+            commands.push(['set', this.objNamespace + id, message]);
+            await this.client.multi(commands).exec();
         }
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, options) => {
-            if (err) {
-                return tools.maybeCallbackWithRedisError(callback, err);
-            }
-            // @ts-expect-error TODO we are returning type Object for ease of use to devs, but formally these are AnyObjects, e.g. not guaranteed to have common
-            return this._extendObject(id, obj, options, callback);
-        });
+        // extended -> if it's now type meta and currently marked as not -> cache
+        if (this.existingMetaObjects[id] === false && oldObjNotNull?.type === 'meta') {
+            this.existingMetaObjects[id] = true;
+        }
+        await this.client.publish(this.objNamespace + id, message);
+        return { id, value: oldObjNotNull };
     }
-    extendObjectAsync(id, obj, options) {
-        return new Promise((resolve, reject) => this.extendObject(id, obj, options || null, (err, res) => (err ? reject(err) : resolve(res))));
+    /**
+     * Extend an existing object with the given partial object, creating it if it does not exist
+     *
+     * @param id The id of the object to extend
+     * @param obj The partial object to merge into the existing object
+     * @param options The current request options including the user, or the callback
+     */
+    async extendObject(id, obj, options) {
+        const userContext = await checkObjectRightsAsync(this, null, null, options, CONSTS.ACCESS_WRITE);
+        return this._extendObject(id, obj, options || {}, userContext);
     }
     /**
      * Returns the object id if found
      *
-     * @param idOrName
-     * @param type
-     * @param options
-     * @param callback
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param options The current request options (may include a language)
+     * @param options.language The language to use when resolving names
+     * @param options.user The user on whose behalf the lookup is performed
+     * @param userContext The resolved user context to check the rights against
+     * @param callback Called with the found id and the original id/name
      */
-    _findObject(idOrName, type, options, callback) {
+    _findObject(idOrName, type, options, userContext, callback) {
         // Try to read by ID
-        this._getObject(idOrName, options, (err, obj) => {
+        this._getObject(idOrName, userContext, (err, obj) => {
             // Assume it is ID
-            if (obj && utils.checkObject(obj, options, CONSTS.ACCESS_READ) && (!type || obj.common?.type === type)) {
+            if (obj &&
+                utils.checkObject(obj, userContext, CONSTS.ACCESS_READ) &&
+                (!type || obj.common?.type === type)) {
                 return tools.maybeCallbackWithError(callback, null, idOrName, obj.common.name);
             }
             // Get all objects that this user may read
-            this._getKeys('*', options, async (err, keys) => {
+            return this._getKeys('*', userContext, true, async (err, keys) => {
                 if (!this.client) {
                     return tools.maybeCallbackWithError(callback, ERRORS.ERROR_DB_CLOSED);
                 }
@@ -3790,9 +4092,17 @@ export class ObjectsInRedisClient {
                     }
                 }
                 return tools.maybeCallbackWithError(callback, null, undefined, idOrName);
-            }, true);
-        });
+            });
+        }).catch(e => this.log.error(`${this.namespace} Cannot find object: ${e.message}`));
     }
+    /**
+     * Find an object by its id or name
+     *
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param options The current request options (may include a language), or the callback
+     * @param callback Called with the found id and the original id/name
+     */
     findObject(idOrName, type, options, callback) {
         if (typeof type === 'function') {
             callback = type;
@@ -3806,19 +4116,21 @@ export class ObjectsInRedisClient {
         if (!callback) {
             return new Promise((resolve, reject) => this.findObject(idOrName, type, options, (err, id, _idOrName) => (err ? reject(err) : resolve(id))));
         }
-        if (options?.acl) {
-            options.acl = null;
-        }
         if (typeof callback === 'function') {
-            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_LIST, (err, options) => {
+            utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_LIST, (err, userContext) => {
                 if (err) {
                     return tools.maybeCallbackWithError(callback, err);
                 }
-                return this._findObject(idOrName, type, options, callback);
+                return this._findObject(idOrName, type, options, userContext, callback);
             });
         }
     }
     // can be called only from js-controller
+    /**
+     * Add object property paths that should be preserved when an object is overwritten (controller only)
+     *
+     * @param settings One or more property paths to preserve
+     */
     addPreserveSettings(settings) {
         if (!Array.isArray(settings)) {
             settings = [settings];
@@ -3860,26 +4172,40 @@ export class ObjectsInRedisClient {
             return tools.maybeCallbackWithRedisError(callback, e);
         }
     }
+    /**
+     * Delete the whole objects database (requires admin rights)
+     *
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the database has been destroyed
+     */
     destroyDB(options, callback) {
         if (typeof options === 'function') {
             callback = options;
             options = null;
         }
         options = options || {};
-        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, options) => {
+        utils.checkObjectRights(this, null, null, options, CONSTS.ACCESS_WRITE, (err, userContext) => {
             if (err) {
                 return tools.maybeCallbackWithRedisError(callback, err);
             }
-            if (!options.acl.file.write || options.user !== CONSTS.SYSTEM_ADMIN_USER) {
+            if (!userContext.acl.file.write || userContext.user !== CONSTS.SYSTEM_ADMIN_USER) {
                 return tools.maybeCallbackWithError(callback, ERRORS.ERROR_PERMISSION);
             }
             return this._destroyDB(callback);
         });
     }
+    /**
+     * Promise-version of destroyDB
+     *
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the database is destroyed
+     */
     destroyDBAsync(options) {
         return new Promise((resolve, reject) => this.destroyDB(options, err => (err ? reject(err) : resolve())));
     }
-    // Destructor of the class. Called by shutting down.
+    /**
+     * Destructor of the class. Called when shutting down to close the redis connections.
+     */
     async destroy() {
         this.stop = true;
         if (this.client) {
@@ -3913,6 +4239,9 @@ export class ObjectsInRedisClient {
             }
         }
     }
+    /**
+     * Load and register the Lua scripts used for atomic operations on the redis server
+     */
     async loadLuaScripts() {
         let luaDirName;
         if (this.noLegacyMultihost && this.useSets) {
@@ -3933,15 +4262,13 @@ export class ObjectsInRedisClient {
             return { name: name.replace(/\.lua$/, ''), text: script, hash };
         });
         const hashes = scripts.map(e => e.hash);
-        hashes.unshift('EXISTS');
         if (!this.client) {
             throw new Error(tools.ERRORS.ERROR_DB_CLOSED);
         }
-        let arr;
         try {
-            arr = await this.client.script(hashes);
+            const arr = (await this.client.script('EXISTS', ...hashes));
             if (arr) {
-                scripts.forEach((e, i) => (scripts[i].loaded = !!arr[i]));
+                scripts.forEach((_e, i) => (scripts[i].loaded = !!arr[i]));
             }
         }
         catch {
@@ -3954,7 +4281,7 @@ export class ObjectsInRedisClient {
             if (!script.loaded) {
                 let hash;
                 try {
-                    hash = await this.client.script(['LOAD', script.text]);
+                    hash = (await this.client.script('LOAD', script.text));
                     script.loaded = true;
                 }
                 catch (e) {
@@ -3966,16 +4293,16 @@ export class ObjectsInRedisClient {
                         throw new Error(`Cannot load "${script.name}" into objects database: ${e.message}`);
                     }
                 }
-                script.hash = hash;
+                script.hash = hash || '';
             }
         }
         this.scripts = {};
         scripts.forEach(e => (this.scripts[e.name] = e.hash));
     }
     /**
-     * Get all keys matching a pattern using redis SCAN command, duplicates are filtered out
+     * Get all keys matching a pattern using redis SCAN command; duplicates are filtered out
      *
-     * @param pattern - pattern to match, e. g. io.hm-rpc.0*
+     * @param pattern - pattern to match, e.g. io.hm-rpc.0*
      * @param count - count argument used by redis SCAN, default is 250
      */
     _getKeysViaScan(pattern, count = 250) {
@@ -3997,6 +4324,7 @@ export class ObjectsInRedisClient {
                 // return without duplicates
                 resolve(Array.from(new Set(uniqueKeys)));
             });
+            stream.on('error', reject);
         });
     }
     /**
@@ -4023,7 +4351,7 @@ export class ObjectsInRedisClient {
         if (!this.client) {
             throw new Error(ERRORS.ERROR_DB_CLOSED);
         }
-        // to be safe we remove all sets before migration
+        // to be safe, we remove all sets before migration
         const keys = await this._getKeysViaScan(`${this.setNamespace}object.type.*`);
         for (const key of keys) {
             await this.client.del(key);
@@ -4074,17 +4402,11 @@ export class ObjectsInRedisClient {
             return Promise.resolve(0);
         }
         // try to extend lock
-        return this.client.evalsha([
-            this.scripts.redlock_extend,
-            3,
-            `${this.metaNamespace}objects.primaryHost`,
-            this.hostname,
-            ms,
-        ]);
+        return this.client.evalsha(this.scripts.redlock_extend, 3, `${this.metaNamespace}objects.primaryHost`, this.hostname, ms);
     }
     /**
-     * Sets current host as primary if no primary host active
-     * Value will expire after ms milliseconds
+     * Sets the current host as primary if no primary host active
+     * Value expires after ms milliseconds
      *
      * @param ms - ms until value expires
      * @returns 1 if lock acquired else 0
@@ -4098,16 +4420,10 @@ export class ObjectsInRedisClient {
             return Promise.resolve(0);
         }
         // try to acquire lock
-        return this.client.evalsha([
-            this.scripts.redlock_acquire,
-            3,
-            `${this.metaNamespace}objects.primaryHost`,
-            this.hostname,
-            ms,
-        ]);
+        return this.client.evalsha(this.scripts.redlock_acquire, 3, `${this.metaNamespace}objects.primaryHost`, this.hostname, ms);
     }
     /**
-     * Get name of the primary host
+     * Get the name of the primary host
      */
     getPrimaryHost() {
         if (!this.client) {
@@ -4130,14 +4446,7 @@ export class ObjectsInRedisClient {
             return Promise.resolve();
         }
         // try to release lock
-        return this.client.evalsha([
-            this.scripts.redlock_release,
-            4,
-            `${this.metaNamespace}objects.primaryHost`,
-            this.hostname,
-            this.settings.connection.options.db,
-            `${this.metaNamespace}objects.primaryHost`,
-        ]);
+        return this.client.evalsha(this.scripts.redlock_release, 4, `${this.metaNamespace}objects.primaryHost`, this.hostname, this.settings.connection.options.db || 0, `${this.metaNamespace}objects.primaryHost`);
     }
     /**
      * Sets the protocol version to the DB
@@ -4159,7 +4468,7 @@ export class ObjectsInRedisClient {
         }
     }
     /**
-     * Subscribe to expired events to get expiration of primary host
+     * Subscribe to expired events to get expiration of the primary host
      */
     async subscribePrimaryHost() {
         if (this.subSystem) {