From eb55af59c83c016fb387824b8bb08eadf1872ed4 Mon Sep 17 00:00:00 2001 From: Andrei Onel Date: Tue, 12 Aug 2025 00:32:13 +0300 Subject: [PATCH] Added reference documentation for: src/backend/src/services/auth/Actor.js --- src/backend/src/services/auth/Actor.js | 197 ++++++++++++++++++------- 1 file changed, 146 insertions(+), 51 deletions(-) diff --git a/src/backend/src/services/auth/Actor.js b/src/backend/src/services/auth/Actor.js index ac55e3343..7df3bc971 100644 --- a/src/backend/src/services/auth/Actor.js +++ b/src/backend/src/services/auth/Actor.js @@ -31,11 +31,11 @@ const PRIVATE_UID_SECRET = config.private_uid_secret /** -* Represents an Actor in the system, extending functionality from AdvancedBase. -* The Actor class is responsible for managing actor instances, including -* creating new actors, generating unique identifiers, and handling related types -* that represent different roles within the context of the application. -*/ + * Represents an Actor in the system, extending functionality from AdvancedBase. + * The Actor class is responsible for managing actor instances, including + * creating new actors, generating unique identifiers, and handling related types + * that represent different roles within the context of the application. + */ class Actor extends AdvancedBase { static MODULES = { uuidv5: require('uuid').v5, @@ -43,9 +43,9 @@ class Actor extends AdvancedBase { } static system_actor_ = null; + /** * Retrieves the system actor instance, creating it if it doesn't exist. - * * This static method ensures that there is only one instance of the system actor. * If the system actor has not yet been created, it will be instantiated with a * new SystemActorType. @@ -61,6 +61,16 @@ class Actor extends AdvancedBase { return this.system_actor_; } + /** + * Creates a new Actor instance with the specified type and parameters. + * Resolves user and app references from UIDs if provided in the parameters. + * + * @param {Function} type - The ActorType constructor to instantiate. + * @param {Object} params - Parameters for the actor type. + * @param {string} [params.user_uid] - UUID of the user to resolve. + * @param {string} [params.app_uid] - UID of the app to resolve. + * @returns {Promise} A new Actor instance. + */ static async create (type, params) { params = { ...params }; if ( params.user_uid ) { @@ -75,12 +85,12 @@ class Actor extends AdvancedBase { } /** - * Initializes the Actor instance with the provided parameters. - * This constructor assigns object properties from the input object to the instance. - * - * @param {Object} o - The object containing actor parameters. - * @param {...any} a - Additional arguments passed to the parent class constructor. - */ + * Initializes the Actor instance with the provided parameters. + * This constructor assigns object properties from the input object to the instance. + * + * @param {Object} o - The object containing actor parameters. + * @param {...any} a - Additional arguments passed to the parent class constructor. + */ constructor (o, ...a) { super(o, ...a); for ( const k in o ) { @@ -88,10 +98,20 @@ class Actor extends AdvancedBase { } } + /** + * Gets the unique identifier for this actor. + * + * @returns {string} The actor's UID from its type. + */ get uid () { return this.type.uid; } + /** + * Returns fields suitable for logging this actor. + * + * @returns {Object} Object containing UID and optionally username for logging. + */ toLogFields () { return { uid: this.type.uid, @@ -102,13 +122,13 @@ class Actor extends AdvancedBase { } /** - * Generates a cryptographically-secure deterministic UUID - * from an actor's UID. The generated UUID is derived by - * applying SHA-256 HMAC to the actor's UID using a secret, - * then formatting the result as a UUID V5. - * - * @returns {string} The derived UUID corresponding to the actor's UID. - */ + * Generates a cryptographically-secure deterministic UUID + * from an actor's UID. The generated UUID is derived by + * applying SHA-256 HMAC to the actor's UID using a secret, + * then formatting the result as a UUID V5. + * + * @returns {string} The derived UUID corresponding to the actor's UID. + */ get private_uid () { // Pass the UUID through SHA-2 first because UUIDv5 // is not cryptographically secure (it uses SHA-1) @@ -139,6 +159,12 @@ class Actor extends AdvancedBase { }); } + /** + * Creates a related actor of the specified type based on the current actor. + * + * @param {Function} type_class - The ActorType class to create a related actor for. + * @returns {Actor} A new Actor instance with the related type. + */ get_related_actor (type_class) { const actor = this.clone(); actor.type = this.type.get_related_type(type_class); @@ -146,7 +172,16 @@ class Actor extends AdvancedBase { } } +/** + * Base class for all actor types in the system. + * Provides common initialization functionality for actor type instances. + */ class ActorType { + /** + * Initializes the ActorType with the provided properties. + * + * @param {Object} o - Object containing properties to assign to this instance. + */ constructor (o) { for ( const k in o ) { this[k] = o[k]; @@ -155,15 +190,28 @@ class ActorType { } /** -* Class representing the system actor type within the actor framework. -* This type serves as a specific implementation of an actor that -* represents a system-level entity and provides methods for UID retrieval -* and related type management. -*/ + * Class representing the system actor type within the actor framework. + * This type serves as a specific implementation of an actor that + * represents a system-level entity and provides methods for UID retrieval + * and related type management. + */ class SystemActorType extends ActorType { + /** + * Gets the unique identifier for the system actor. + * + * @returns {string} Always returns 'system'. + */ get uid () { return 'system'; } + + /** + * Gets a related actor type for the system actor. + * + * @param {Function} type_class - The ActorType class to get a related type for. + * @returns {SystemActorType} Returns this instance if type_class is SystemActorType. + * @throws {Error} If the requested type_class is not supported. + */ get_related_type (type_class) { if ( type_class === SystemActorType ) { return this; @@ -174,14 +222,27 @@ class SystemActorType extends ActorType { /** -* Represents the type of a User Actor in the system, allowing operations and relations -* specific to user actors. This class extends the base functionality to uniquely identify -* user actors and define how they relate to other types of actors within the system. -*/ + * Represents the type of a User Actor in the system, allowing operations and relations + * specific to user actors. This class extends the base functionality to uniquely identify + * user actors and define how they relate to other types of actors within the system. + */ class UserActorType extends ActorType { + /** + * Gets the unique identifier for the user actor. + * + * @returns {string} The UID in format 'user:{uuid}'. + */ get uid () { return 'user:' + this.user.uuid; } + + /** + * Gets a related actor type for the user actor. + * + * @param {Function} type_class - The ActorType class to get a related type for. + * @returns {UserActorType} Returns this instance if type_class is UserActorType. + * @throws {Error} If the requested type_class is not supported. + */ get_related_type (type_class) { if ( type_class === UserActorType ) { return this; @@ -189,16 +250,30 @@ class UserActorType extends ActorType { throw new Error(`cannot get ${type_class.name} from ${this.constructor.name}`) } } + /** -* Represents a user actor type in the application. This class defines the structure -* and behavior specific to user actors, including obtaining unique identifiers and -* retrieving related actor types. It extends the base actor type functionality -* to cater to user-specific needs. -*/ + * Represents a user actor type in the application. This class defines the structure + * and behavior specific to user actors, including obtaining unique identifiers and + * retrieving related actor types. It extends the base actor type functionality + * to cater to user-specific needs. + */ class AppUnderUserActorType extends ActorType { + /** + * Gets the unique identifier for the app-under-user actor. + * + * @returns {string} The UID in format 'app-under-user:{user_uuid}:{app_uid}'. + */ get uid () { return 'app-under-user:' + this.user.uuid + ':' + this.app.uid; } + + /** + * Gets a related actor type for the app-under-user actor. + * + * @param {Function} type_class - The ActorType class to get a related type for. + * @returns {UserActorType|AppUnderUserActorType} The related actor type instance. + * @throws {Error} If the requested type_class is not supported. + */ get_related_type (type_class) { if ( type_class === UserActorType ) { return new UserActorType({ user: this.user }); @@ -212,26 +287,33 @@ class AppUnderUserActorType extends ActorType { /** -* Represents the type of access tokens in the system. -* An AccessTokenActorType associates an authorizer and an authorized actor -* with a string token, facilitating permission checks and identity management. -*/ + * Represents the type of access tokens in the system. + * An AccessTokenActorType associates an authorizer and an authorized actor + * with a string token, facilitating permission checks and identity management. + */ class AccessTokenActorType extends ActorType { // authorizer: an Actor who authorized the token // authorized: an Actor who is authorized by the token // token: a string + /** + * Gets the unique identifier for the access token actor. + * The UID is constructed based on the authorizer's UID, the authorized actor's UID (if available), + * and the token string. This UID format is useful for identifying the access token's context. + * + * @returns {string} The generated UID for the access token. + */ get uid () { return 'access-token:' + this.authorizer.uid + ':' + ( this.authorized?.uid ?? '' ) + ':' + this.token; } + /** - * Generate a unique identifier (UID) for the access token. - * The UID is constructed based on the authorizer's UID, the authorized actor's UID (if available), - * and the token string. This UID format is useful for identifying the access token's context. + * Throws an error as getting related actors is not supported for access tokens. + * This would be dangerous because of ambiguity between authorizer and authorized. * - * @returns {string} The generated UID for the access token. + * @throws {Error} Always throws an error indicating this operation is not supported. */ get_related_actor () { // This would be dangerous because of ambiguity @@ -242,29 +324,42 @@ class AccessTokenActorType extends ActorType { /** -* Represents a Site Actor Type, which encapsulates information about a site-specific actor. -* This class is used to manage details related to the site and implement functionalities -* pertinent to site-level operations and interactions in the actor framework. -*/ + * Represents a Site Actor Type, which encapsulates information about a site-specific actor. + * This class is used to manage details related to the site and implement functionalities + * pertinent to site-level operations and interactions in the actor framework. + */ class SiteActorType { /** - * Constructor for the SiteActorType class. - * Initializes a new instance of SiteActorType with the provided properties. - * - * @param {Object} o - The properties to initialize the SiteActorType with. - * @param {...*} a - Additional arguments. - */ + * Constructor for the SiteActorType class. + * Initializes a new instance of SiteActorType with the provided properties. + * + * @param {Object} o - The properties to initialize the SiteActorType with. + * @param {...*} a - Additional arguments. + */ constructor (o, ...a) { for ( const k in o ) { this[k] = o[k]; } } + /** + * Gets the unique identifier for the site actor. + * + * @returns {string} The UID in format 'site:{site_name}'. + */ get uid () { return `site:` + this.site.name } } +/** + * Adapts various input types to a proper Actor instance. + * If no actor is provided, attempts to get one from the current context. + * Handles legacy user objects by wrapping them in UserActorType. + * + * @param {Actor|Object} [actor] - The actor to adapt, or undefined to use context. + * @returns {Actor} A properly formatted Actor instance. + */ Actor.adapt = function (actor) { actor = actor || Context.get('actor');