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

package/build/cjs/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