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

package/build/esm/lib/objects/objectsUtils.d.ts

@@ -1,52 +1,174 @@
 /**
  *      Common functions between client and server
  *
- *      Copyright 2013-2024 bluefox <dogafox@gmail.com>
+ *      Copyright 2013-2026 bluefox <dogafox@gmail.com>
  *
  *      MIT License
  *
  */
 import * as CONSTS from '../../lib/objects/constants.js';
+import type { Client as ObjectClient } from '@iobroker/db-objects-redis';
 export * as CONSTS from '../../lib/objects/constants.js';
 export declare const ERRORS: typeof CONSTS.ERRORS;
 export declare const REG_CHECK_ID: RegExp;
+/** Resolved permission context of the user performing a request */
+export interface UserContext {
+    /** The user on whose behalf the request is performed */
+    user: ioBroker.ObjectIDs.User;
+    /** The primary group of the user */
+    group: ioBroker.ObjectIDs.Group;
+    /** All groups the user is a member of */
+    groups: ioBroker.ObjectIDs.Group[];
+    /** The effective permissions resolved from the user and its groups */
+    acl: ioBroker.ObjectPermissions;
+    /** Whether the permissions have already been resolved/checked */
+    checked?: boolean;
+}
+/** Information about a file's mime type */
 export interface FileMimeInformation {
     /** the mime type, of the file */
     mimeType: string;
-    /** if content is binary or textual */
+    /** if the content is binary or textual */
     isBinary: boolean;
 }
+/** The access control list of an object, state or file */
 export interface ACLObject {
-    owner: string;
-    ownerGroup: string;
+    /** The user that owns the object */
+    owner: ioBroker.ObjectIDs.User;
+    /** The group that owns the object */
+    ownerGroup: ioBroker.ObjectIDs.Group;
+    /** Permission bitmask for object access */
     object: number;
+    /** Permission bitmask for state access */
     state: number;
+    /** Permission bitmask for file access */
     file: number;
 }
+/** Metadata of a stored file */
 export interface FileObject {
+    /** Whether this is a virtual file (a directory placeholder) */
     virtualFile?: boolean;
-    stats: any;
-    modifiedAt: number;
-    createdAt: number;
-    acl: ioBroker.EvaluatedFileACL;
+    /** File system stats of the file */
+    stats?: {
+        size?: number;
+    };
+    /** Timestamp (ms) when the file was last modified */
+    modifiedAt?: number;
+    /** Timestamp (ms) when the file was created */
+    createdAt?: number;
+    /** Evaluated access control list of the file */
+    acl?: ioBroker.EvaluatedFileACL;
+    /** Whether the entry is a directory */
+    isDir?: boolean;
+    /** Whether the file does not exist (yet) */
+    notExists?: boolean;
+    /** The mime type of the file */
+    mimeType?: string;
+    /** Whether the file content is binary */
+    binary?: boolean;
 }
-export type CheckFileRightsCallback = (err: Error | null | undefined, options: Record<string, any>, opt?: any) => void;
 /**
  * Determines the mime type, of an extension and if it is binary content
  *
  * @param ext file extension e.g. `.txt`
  * @param isTextData if content is of type string
  */
-export declare function getMimeType(ext: string, isTextData: boolean): FileMimeInformation;
-export declare function checkFile(fileOptions: Record<string, any>, options: Record<string, any>, flag: any, defaultNewAcl?: ACLObject | null): boolean;
-export declare function checkFileRights(objects: any, id: string, name: string | null, options: Record<string, any> | null | undefined, flag: CONSTS.GenericAccessFlags, callback?: CheckFileRightsCallback): any;
-export type GetUserGroupPromiseReturn = [user: string, groups: string[], acl: ioBroker.ObjectPermissions];
-type GetUserGroupCallback = (err: Error | null | undefined, user: string, groups: string[], acl: ioBroker.ObjectPermissions) => void;
-export declare function getUserGroup(objects: any, user: ioBroker.ObjectIDs.User, callback?: GetUserGroupCallback): Promise<GetUserGroupPromiseReturn> | void;
+export declare function getMimeType(ext: string, isTextData?: boolean): FileMimeInformation;
+/**
+ * Check if the given options have the required rights on a file according to its ACL
+ *
+ * @param fileOptions The stored file options including its ACL
+ * @param fileOptions.mimeType The mime type of the file
+ * @param fileOptions.notExists Whether the file does not exist yet
+ * @param fileOptions.acl The access control list stored for the file
+ * @param userContext The current request options including the user and group
+ * @param flag The access flag(s) to check for
+ * @param defaultNewAcl The default ACL to use if the file has none yet
+ */
+export declare function checkFile(fileOptions: {
+    mimeType?: string;
+    notExists?: boolean;
+    acl?: ioBroker.FileACL;
+}, userContext: UserContext, flag: number, defaultNewAcl?: ACLObject | null): boolean;
+/**
+ * Check whether the given user is allowed to access a file and call back with the effective options
+ *
+ * @param objects The objects database client
+ * @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
+ */
+export declare function checkFileRightsAsync(objects: ObjectClient, id: string, name: string | null, options: {
+    user?: ioBroker.ObjectIDs.User;
+} | null | undefined, flag: CONSTS.GenericAccessFlags): Promise<{
+    fileOptions: FileObject;
+    userContext: UserContext;
+}>;
+export type GetUserGroupPromiseReturn = [
+    user: ioBroker.ObjectIDs.User,
+    groups: ioBroker.ObjectIDs.Group[],
+    acl: ioBroker.ObjectPermissions
+];
+type GetUserGroupCallback = (err: Error | null | undefined, user: ioBroker.ObjectIDs.User, groups: ioBroker.ObjectIDs.Group[], acl: ioBroker.ObjectPermissions) => void;
+/**
+ * Determine the groups and effective ACL of the given user
+ *
+ * @param objects The objects database client
+ * @param user The id of the user to look up
+ * @param callback Called with the user, its groups and the effective ACL
+ */
+export declare function getUserGroup(objects: ObjectClient, user: ioBroker.ObjectIDs.User, callback: GetUserGroupCallback): void;
+/**
+ * Determine the groups and effective ACL of the given user
+ *
+ * @param objects The objects database client
+ * @param user The id of the user to look up
+ */
+export declare function getUserGroupAsync(objects: ObjectClient, user: ioBroker.ObjectIDs.User): Promise<GetUserGroupPromiseReturn>;
+/**
+ * Sanitize an object id and file name so they cannot escape the intended directory
+ *
+ * @param id The object id owning the file
+ * @param name The file name to sanitize
+ */
 export declare function sanitizePath(id: string, name: string): {
+    /** The sanitized object id */
     id: string;
+    /** The sanitized file name */
     name: string;
 };
-export declare function checkObject(obj: ioBroker.AnyObject | FileObject | null, options: Record<string, any>, flag: CONSTS.GenericAccessFlags): boolean;
-export declare function checkObjectRights(objects: any, id: string | null, object: ioBroker.Object | null, options: Record<string, any> | null | undefined, flag: CONSTS.GenericAccessFlags, callback: (err: Error | null | undefined, options: Record<string, any>) => void): void | Promise<Record<string, any>>;
+/**
+ * Check if the given options have the required rights on an object according to its ACL
+ *
+ * @param obj The object (or file object) to check, or null
+ * @param options The current request options including the user and group
+ * @param flag The access flag(s) to check for
+ */
+export declare function checkObject(obj: ioBroker.AnyObject | FileObject | null, options: UserContext, flag: CONSTS.GenericAccessFlags): boolean;
+/**
+ * Check whether the given user is allowed to access an object and call back with the effective options
+ *
+ * @param objects The objects database client
+ * @param id The id of the object, or null
+ * @param object The object to check, or null
+ * @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
+ */
+export declare function checkObjectRights(objects: ObjectClient, id: string | null, object: ioBroker.Object | null, options: {
+    user?: ioBroker.ObjectIDs.User;
+} | null | undefined, flag: CONSTS.GenericAccessFlags, callback: (err: Error | null | undefined, userContext?: UserContext) => void): void;
+/**
+ * Check whether the given user is allowed to access an object and call back with the effective options
+ *
+ * @param objects The objects database client
+ * @param id The id of the object, or null
+ * @param object The object to check, or null
+ * @param options The current request options including the user
+ * @param flag The access flag(s) to check for
+ */
+export declare function checkObjectRightsAsync(objects: ObjectClient, id: string | null, object: ioBroker.Object | null, options: {
+    user?: ioBroker.ObjectIDs.User;
+} | null | undefined, flag: CONSTS.GenericAccessFlags): Promise<UserContext>;
 //# sourceMappingURL=objectsUtils.d.ts.map

package/build/esm/lib/objects/objectsUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objectsUtils.d.ts","sourceRoot":"","sources":["../../../../src/lib/objects/objectsUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"objectsUtils.d.ts","sourceRoot":"","sources":["../../../../src/lib/objects/objectsUtils.ts"],"names":[],"mappings":"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"}